com.eurotech.framework.protocol.modbus
Class Modbus

java.lang.Object
  com.eurotech.framework.protocol.modbus.ModbusProtocolDevice
      com.eurotech.framework.protocol.modbus.Modbus

public class Modbus
extends ModbusProtocolDevice

The Modbus protocol implements a subset of the Modbus standard command set. It also provides for the extension of some data typing to allow register pairings to hold 32 bit data (see the configureDataMap for more detail).

The protocol only supports RTU mode operation.

Author:

matt.demaree

See Also:

ProtocolDevice

Field Summary

static String	PROTOCOL_CONNECTION_TYPE_ETHER_TCP
static String	PROTOCOL_CONNECTION_TYPE_SERIAL

Constructor Summary

Modbus()
creates the default data map

Method Summary

void	configureConnection(org.osgi.service.io.ConnectionFactory connFactory, Properties connectionConfig) two connection types are available, PROTOCOL_CONNECTION_TYPE_SERIAL and PROTOCOL_CONNECTION_TYPE_ETHER_TCP.
void	configureDataMap(Properties dataConfig) use of this method is optional, Modbus initializes with a default DataMap.
void	configureProtocol(Properties protocolConfig) modbus protocol configuration.
void	connect() attempt to connect to the field device using the provided configuration.
void	disconnect() attempt to disconnect from the field device.
int	getConnectStatus() for expedience, can test the status of the connection prior to attempting a command.
String	getDataType(int dataAddress) get the primitive data type for the selected address.
int	getEndOfRange(int dataAddress) gets the last address in a contiguous block of the same type data.
NmeaPosition	getNmeaPosition()
org.osgi.util.position.Position	getPosition()
String	getProtocolName() get the name "modbus" for this protocol
int	getStartOfRange(int dataAddress) gets the first address in a contiguous block of the same type data.
String	getUnitAddress() Modbus unit addresses must always be in the range of 1-255
boolean	isAddressMapped(int dataAddress) validate that the protocol has a mapping for the desired address.
boolean[]	readBooleans(int dataAddress, int count) read 1 or more boolean points from the attached field device.
float[]	readFloats(int dataAddress, int count) read 1 or more float points from the attached field device.
int[]	readInts(int dataAddress, int count) read 1 or more int points from the attached field device.
short[]	readShorts(int dataAddress, int count) read 1 or more short points from the attached field device.
long[]	readUnsignedInts(int dataAddress, int count) read 1 or more unsigned int points from the attached field device.
int[]	readUnsignedShorts(int dataAddress, int count) read 1 or more unsigned short points from the attached field device.
String	toString() get the unit name registered for this instance
void	writeBooleans(int dataAddress, boolean[] data) write 1 or more boolean values to the attached field device.
void	writeFloats(int dataAddress, float[] data) write 1 or more float values to the attached field device.
void	writeInts(int dataAddress, int[] data) write 1 or more int values to the attached field device.
void	writeShorts(int dataAddress, short[] data) write 1 or more short values to the attached field device.
void	writeUnsignedInts(int dataAddress, long[] data) write 1 or more unsigned int values to the attached field device.
void	writeUnsignedShorts(int dataAddress, int[] data) write 1 or more unsigned short values to the attached field device.

Methods inherited from class com.eurotech.framework.protocol.modbus.ModbusProtocolDevice

readBytes, readChars, readDoubles, readLongs, readObject, writeBytes, writeChars, writeDoubles, writeLongs, writeObject

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PROTOCOL_CONNECTION_TYPE_SERIAL

public static final String PROTOCOL_CONNECTION_TYPE_SERIAL

See Also:

Constant Field Values

PROTOCOL_CONNECTION_TYPE_ETHER_TCP

public static final String PROTOCOL_CONNECTION_TYPE_ETHER_TCP

See Also:

Constant Field Values

Constructor Detail

Modbus

public Modbus()

creates the default data map

Method Detail

configureProtocol

public void configureProtocol(Properties protocolConfig)
                       throws ModbusProtocolException

modbus protocol configuration. Required properties for the modbus protocol configuration are:

Key	Description
unitName	Name to be returned by toString
unitAddress	Modbus address of the unit (1-255)
txMode	Must be set to "RTU", "ASCII" not supported
respTimeout	maximum time, in milliseconds, to wait for a response to a command

Specified by:

configureProtocol in class ModbusProtocolDevice

Parameters:

protocolConfig - key/value pairing directly from configuration file or may be generated.

Throws:

ModbusProtocolException

configureConnection

public void configureConnection(org.osgi.service.io.ConnectionFactory connFactory,
                                Properties connectionConfig)
                         throws ModbusProtocolException

two connection types are available, PROTOCOL_CONNECTION_TYPE_SERIAL and PROTOCOL_CONNECTION_TYPE_ETHER_TCP. The required properties for the connection will vary with each connection.

PROTOCOL_CONNECTION_TYPE_SERIAL

see CommConnection package for more detail.

Key	Description
connectionType	"SERIAL" (from PROTOCOL_CONNECTION_TYPE_SERIAL). This parameter indicates the connection type for the configuration. See CommConnection for more details on serial port configuration.
port	the actual device port, such as "/dev/ttyUSB0" in linux
baudRate	baud rate to be configured for the port
stopBits	number of stop bits to be configured for the port
parity	parity mode to be configured for the port
bitsPerWord	only RTU mode supported, bitsPerWord must be 8

PROTOCOL_CONNECTION_TYPE_ETHER_TCP

The Ethernet mode merely opens a socket and sends the full RTU mode Modbus packet over that socket connection and expects to receive a full RTU mode Modbus response, including the CRC bytes.

Key	Description
connectionType	"ETHERTCP" (from PROTOCOL_CONNECTION_TYPE_ETHER_TCP). This parameter indicates the connection type for the configurator.
ipAddress	the 4 octet IP address of the field device (xxx.xxx.xxx.xxx)
port	port on the field device to connect to

Specified by:

configureConnection in class ModbusProtocolDevice

connectionConfig - key/value pairing directly from configuration file or may be generated.

Throws:

ModbusProtocolException

configureDataMap

public void configureDataMap(Properties dataConfig)
                      throws ModbusProtocolException

use of this method is optional, Modbus initializes with a default DataMap. The data map is a group of 1 or more ModbusFieldDeviceDataMap objects. Each parameter of each object must be distinguished from the same parameter of other objects in the configuration properties. Each parameter then will carry an index value to associate properties into object settings (n in the table below). The index value must start at 0 and increment by 1 for any configuration Properties object passed in, even if a configuration already exists (the index is not stored or reused outside the properties object).

New data maps do not cause the removal of existing data maps, but may displace them or even split them into two separate maps.

See modbusFieldDeviceDataMap for more detail.

Single data field mapping

(repeat entry sets with n indexing up from 0 for each set)

Key	Description
startAddressn	starting address of field as seen by client
countn	number of readable points in this field
dataOrdern	data order in data stream
dataFormationn	Modbus data streams may contain 1 bit, 16 bit or 32 bit data
modbusDataOffsetn	offset of associated data in the field device
modbusReadCommandn	the Modbus command used to read the data helps to identify the specific Modbus data

Default map:

Key	Description
startAddress0	1
count0	9999
dataOrder0	MODBUS_BOOLEAN_ORDER
dataFormation0	BOOLEAN
modbusDataOffset0	0
modbusReadCommand0	READ_COIL_STATUS
startAddress1	10001
count1	9999
dataOrder1	MODBUS_BOOLEAN_ORDER
dataFormation1	BOOLEAN
modbusDataOffset1	0
modbusReadCommand1	READ_INPUT_STATUS
startAddress2	30001
count2	9999
dataOrder2	MODBUS_WORD_ORDER_BIG_ENDIAN
dataFormation2	SINGLE16
modbusDataOffset2	0
modbusReadCommand2	READ_INPUT_REGS
startAddress3	40001
count3	65535
dataOrder3	MODBUS_WORD_ORDER_BIG_ENDIAN
dataFormation3	SINGLE16
modbusDataOffset3	0
modbusReadCommand3	READ_HOLDING_REGS

Overrides:

configureDataMap in class ModbusProtocolDevice

Parameters:

dataConfig - key/value pairing directly from configuration file or may be generated.

Throws:

ModbusProtocolException

toString

public String toString()

get the unit name registered for this instance

Specified by:

toString in class ModbusProtocolDevice

Returns:

unitName

See Also:

Object.toString()

getProtocolName

public String getProtocolName()

get the name "modbus" for this protocol

Specified by:

getProtocolName in class ModbusProtocolDevice

Returns:

"modbus"

getUnitAddress

public String getUnitAddress()

Modbus unit addresses must always be in the range of 1-255

Specified by:

getUnitAddress in class ModbusProtocolDevice

Returns:

unit address (1-255) as a string

connect

public void connect()
             throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

attempt to connect to the field device using the provided configuration. Attempts to connect before configuring the connection or any issues with connecting to the field device will result in an exception being thrown. This includes things like a networking failure in the case of a protocol configured to access the field device of a network.

Refer to getConnectStatus to determine if the connection is completed.

All protocols must implement this method.

Specified by:

connect in class ModbusProtocolDevice

Throws:

ModbusProtocolException

disconnect

public void disconnect()

Description copied from class: ModbusProtocolDevice

attempt to disconnect from the field device. This should close any port used exclusively for this protocol to talk with its attached device. Attempting to close an already closed connection is not invalid.

All protocols must implement this method.

Specified by:

disconnect in class ModbusProtocolDevice

See Also:

ModbusProtocolDevice.getConnectStatus()

getConnectStatus

public int getConnectStatus()

Description copied from class: ModbusProtocolDevice

for expedience, can test the status of the connection prior to attempting a command. A connection status of CONNECTED does not assure that a subsequent command will succeed.

All protocols must implement this method.

Specified by:

getConnectStatus in class ModbusProtocolDevice

Returns:

current connection status as defined in EsfConnectionStatus.

getDataType

public String getDataType(int dataAddress)
                   throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

get the primitive data type for the selected address.

All protocols must implement this method.

Specified by:

getDataType in class ModbusProtocolDevice

Parameters:

dataAddress - address of the data point for which the data type is being requested

Returns:

an enumeration of the data type from PrototocolPrimitiveDataTypes

Throws:

ModbusProtocolException

getEndOfRange

public int getEndOfRange(int dataAddress)
                  throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

gets the last address in a contiguous block of the same type data. Most protocols are capable of working with more than one data type, often grouped in sections or records, this method works on the mapping provided for the given device to determine a range of same typed data.

All protocols must implement this method.

Specified by:

getEndOfRange in class ModbusProtocolDevice

Parameters:

dataAddress - may be the first or last address or anywhere n between for the range determined.

Returns:

the last address within (inclusive of) the block of same data types

Throws:

ModbusProtocolException

getStartOfRange

public int getStartOfRange(int dataAddress)
                    throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

gets the first address in a contiguous block of the same type data. Most protocols are capable of working with more than one data type, often grouped in sections or records, this method works on the mapping provided for the given device to determine a range of same typed data.

All protocols must implement this method.

Specified by:

getStartOfRange in class ModbusProtocolDevice

Parameters:

dataAddress - may be the first or last address or anywhere in between for the range determined.

Returns:

the first address within the block of same data types

Throws:

ModbusProtocolException

isAddressMapped

public boolean isAddressMapped(int dataAddress)

Description copied from class: ModbusProtocolDevice

validate that the protocol has a mapping for the desired address.

All protocols must implement this method.

Specified by:

isAddressMapped in class ModbusProtocolDevice

Parameters:

dataAddress - this is the local address, not the field address

Returns:

true if address is mapped, false otherwise

readBooleans

public boolean[] readBooleans(int dataAddress,
                              int count)
                       throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

read 1 or more boolean points from the attached field device.

Protocols are not required to implement this method.

Overrides:

readBooleans in class ModbusProtocolDevice

Parameters:

dataAddress - first point to read

count - count of points to read

Returns:

an array of booleans representing the requested data points. true for a given point if the point is set, false otherwise.

Throws:

ModbusProtocolException

readFloats

public float[] readFloats(int dataAddress,
                          int count)
                   throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

read 1 or more float points from the attached field device.

Protocols are not required to implement this method.

Overrides:

readFloats in class ModbusProtocolDevice

Parameters:

dataAddress - first point to read

count - count of points to read

Returns:

an array of floats representing the requested data points

Throws:

ModbusProtocolException

readUnsignedInts

public long[] readUnsignedInts(int dataAddress,
                               int count)
                        throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

read 1 or more unsigned int points from the attached field device.

Protocols are not required to implement this method.

Overrides:

readUnsignedInts in class ModbusProtocolDevice

Parameters:

dataAddress - first point to read

count - count of points to read

Returns:

an array of longs representing the requested data points

Throws:

ModbusProtocolException

readInts

public int[] readInts(int dataAddress,
                      int count)
               throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

read 1 or more int points from the attached field device.

Protocols are not required to implement this method.

Overrides:

readInts in class ModbusProtocolDevice

Parameters:

dataAddress - first point to read

count - count of points to read

Returns:

an array of ints representing the requested data points

Throws:

ModbusProtocolException

readUnsignedShorts

public int[] readUnsignedShorts(int dataAddress,
                                int count)
                         throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

read 1 or more unsigned short points from the attached field device.

Protocols are not required to implement this method.

Overrides:

readUnsignedShorts in class ModbusProtocolDevice

Parameters:

dataAddress - first point to read

count - count of points to read

Returns:

an array of ints representing the requested data points

Throws:

ModbusProtocolException

readShorts

public short[] readShorts(int dataAddress,
                          int count)
                   throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

read 1 or more short points from the attached field device.

Protocols are not required to implement this method.

Overrides:

readShorts in class ModbusProtocolDevice

Parameters:

dataAddress - first point to read

count - count of points to read

Returns:

an array of shorts representing the requested data points

Throws:

ModbusProtocolException

writeBooleans

public void writeBooleans(int dataAddress,
                          boolean[] data)
                   throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

write 1 or more boolean values to the attached field device.

Protocols are not required to implement this method.

Overrides:

writeBooleans in class ModbusProtocolDevice

Parameters:

dataAddress - first address to write to

data - array of 1 or more booleans to write. The data will be written to consecutive addresses starting with dataAddress.

Throws:

ModbusProtocolException

writeFloats

public void writeFloats(int dataAddress,
                        float[] data)
                 throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

write 1 or more float values to the attached field device.

Protocols are not required to implement this method.

Overrides:

writeFloats in class ModbusProtocolDevice

Parameters:

dataAddress - first address to write to

data - array of 1 or more floats to write. The data will be written to consecutive addresses starting with dataAddress.

Throws:

ModbusProtocolException

writeUnsignedInts

public void writeUnsignedInts(int dataAddress,
                              long[] data)
                       throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

write 1 or more unsigned int values to the attached field device.

Protocols are not required to implement this method.

Overrides:

writeUnsignedInts in class ModbusProtocolDevice

Parameters:

dataAddress - first address to write to

data - array of 1 or more longs to write. The data will be written to consecutive addresses starting with dataAddress.

Throws:

ModbusProtocolException

writeInts

public void writeInts(int dataAddress,
                      int[] data)
               throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

write 1 or more int values to the attached field device.

Protocols are not required to implement this method.

Overrides:

writeInts in class ModbusProtocolDevice

Parameters:

dataAddress - first address to write to

data - array of 1 or more ints to write. The data will be written to consecutive addresses starting with dataAddress.

Throws:

ModbusProtocolException

writeUnsignedShorts

public void writeUnsignedShorts(int dataAddress,
                                int[] data)
                         throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

write 1 or more unsigned short values to the attached field device.

Protocols are not required to implement this method.

Overrides:

writeUnsignedShorts in class ModbusProtocolDevice

Parameters:

dataAddress - first address to write to

data - array of 1 or more ints to write. The data will be written to consecutive addresses starting with dataAddress.

Throws:

ModbusProtocolException

writeShorts

public void writeShorts(int dataAddress,
                        short[] data)
                 throws ModbusProtocolException

Description copied from class: ModbusProtocolDevice

write 1 or more short values to the attached field device.

Protocols are not required to implement this method.

Overrides:

writeShorts in class ModbusProtocolDevice

Parameters:

dataAddress - first address to write to

data - array of 1 or more shorts to write. The data will be written to consecutive addresses starting with dataAddress.

Throws:

ModbusProtocolException

getPosition

public org.osgi.util.position.Position getPosition()

Specified by:

getPosition in class ModbusProtocolDevice

getNmeaPosition

public NmeaPosition getNmeaPosition()

Specified by:

getNmeaPosition in class ModbusProtocolDevice