com.eurotech.framework.protocol.modbus
Class Modbus

java.lang.Object
  extended by com.eurotech.framework.protocol.modbus.ModbusProtocolDevice
      extended by 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:
KeyDescription
unitNameName to be returned by toString
unitAddressModbus address of the unit (1-255)
txModeMust be set to "RTU", "ASCII" not supported
respTimeoutmaximum 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


Copyright © 2013. All Rights Reserved.