com.eurotech.framework.protocol.modbus
Interface ModbusProtocolDeviceService

All Known Implementing Classes:

ModbusProtocolDevice

public interface ModbusProtocolDeviceService

OSGI service providing a connection to a device via Serial link (RS232/RS485) or Ethernet using Modbus protocol. This service implements a subset of Modbus Application Protocol as defined by Modbus Organization : http://www.modbus.org/specs.php.
For the moment in Ethernet mode, only RTU over TCP/IP is supported

Function codes implemented are :

01 (0x01) readCoils(int dataAddress, int count) : Read 1 to 2000 max contiguous status of coils from the attached field device. It returns an array of booleans representing the requested data points.

02 (0x02) readDiscreteInputs(int dataAddress, int count) : Read 1 to 2000 max contiguous status of discrete inputs from the attached field device. It returns an array of booleans representing the requested data points.

03 (0x03) readHoldingRegisters(int dataAddress, int count) : Read contents of 1 to 125 max contiguous block of holding registers from the attached field device. It returns an array of int representing the requested data points (data registers on 2 bytes).

04 (0x04) readInputRegisters(int dataAddress, int count) : Read contents of 1 to 125 max contiguous block of input registers from the attached field device. It returns an array of int representing the requested data points (data registers on 2 bytes).

05 (0x05) writeSingleCoil(int dataAddress, boolean data) : Write a single output to either ON or OFF in the attached field device.

06 (0x06) writeSingleRegister(int dataAddress, int data) : write a single holding register in the attached field device.

07 (0x07) readExceptionStatus() : read the content of 8 Exception Status outputs in the field device.

11 (0x0B) getCommEventCounter() : Get a status word and an event count from the field device.

12 (0x0C) getCommEventLog() : Get a status word, an event count, a message count and a list of event bytes from the field device.

15 (0x0F) writeMultipleCoils(int dataAddress, boolean[] data) : Write multiple coils in a sequence of coils to either ON or OFF in the attached field device.

16 (0x10) writeMultipleRegister(int dataAddress, int[] data) : write a block of contiguous registers (1 to 123) in the attached field device.

Field Summary

static String

SERVICE_NAME name of this service

Method Summary

void	configureConnection(Properties connectionConfig) Configure access to the physical device.
void	configureProtocol(Properties protocolConfig) Required properties for 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.
ModbusCommEvent	getCommEventCounter() Modbus function 11 (0x0B) Get a status word and an event count from the device. Return values in a ModbusCommEvent.
ModbusCommEvent	getCommEventLog() Modbus function 12 (0x0C) Get a status word, an event count, a message count and a list of event bytes from the device. Return values in a ModbusCommEvent.
int	getConnectStatus() for expedience, can test the status of the connection prior to attempting a command.
NmeaPosition	getNmeaPosition() Return NMEA Position of the device
org.osgi.util.position.Position	getPosition() Return OSGI Position of the device
String	getProtocolName() returns the protocol name for the specific protocol implemented.
String	getUnitAddress() this returns the address given the RTU in the configureProtocol.
boolean[]	readCoils(int dataAddress, int count) Modbus function 01 Read 1 to 2000 contiguous status of coils from the attached field device.
boolean[]	readDiscreteInputs(int dataAddress, int count) Modbus function 02 Read 1 to 2000 contiguous status of discrete inputs from the attached field device.
boolean[]	readExceptionStatus() Modbus function 07 read the content of 8 Exception Status outputs in the field device.
int[]	readHoldingRegisters(int dataAddress, int count) Modbus function 03 Read contents of 1 to 125 contiguous block of holding registers from the attached field device.
int[]	readInputRegisters(int dataAddress, int count) Modbus function 04 Read contents of 1 to 125 contiguous block of input registers from the attached field device.
String	toString() returns the unit name given in the configureProtocol call.
void	writeMultipleCoils(int dataAddress, boolean[] data) Modbus function 15 (0x0F) write multiple coils in a sequence of coils to either ON or OFF in the attached field device.
void	writeMultipleRegister(int dataAddress, int[] data) Modbus function 16 (0x10) write a block of contiguous registers (1 to 123) in the attached field device.
void	writeSingleCoil(int dataAddress, boolean data) Modbus function 05 write a single output to either ON or OFF in the attached field device.
void	writeSingleRegister(int dataAddress, int data) Modbus function 06 write a single holding register in the attached field device.

Field Detail

SERVICE_NAME

static final String SERVICE_NAME

name of this service

Method Detail

toString

String toString()

returns the unit name given in the configureProtocol call. Prior to configuration, this method will return the built-in name of the protocol, the same as returned by getProtocolName.

Overrides:

toString in class Object

Returns:

assigned unit name

See Also:

Object.toString()

getProtocolName

String getProtocolName()

returns the protocol name for the specific protocol implemented. This name should follow Java member naming conventions, so the first (or only) part of the name should be all lower case, all subsequent parts to the name should begin with an upper case and continue with lower case.

Returns:

name following the above rules

getUnitAddress

String getUnitAddress()

this returns the address given the RTU in the configureProtocol. Until configured, this returns an empty string. The address is returned as a string rather than an integer or other number as some protocols may have multi-part addresses or addresses that contain non-numeric parts.

Returns:

address of physical device this instance represents

configureProtocol

void configureProtocol(Properties protocolConfig)
                       throws ModbusProtocolException

Required properties for modbus protocol configuration.

Parameters:

protocolConfig - (key/value pairing directly from configuration file)

unitName : Name to be returned by toString

unitAddress : Modbus address of the unit (1-255)

txMode : Must be set to "RTU" or "ASCII"

respTimeout : maximum time, in milliseconds, to wait for a response to a command

Throws:

ModbusProtocolException(INVALID_CONFIGURATION) - unspecified problem with the configuration

ModbusProtocolException

configureConnection

void configureConnection(Properties connectionConfig)
                         throws ModbusProtocolException

Configure access to the physical device.

Parameters:

connectionConfig - (key/value pairing directly from configuration file)

connectionType : PROTOCOL_CONNECTION_TYPE_SERIAL("SERIAL") or PROTOCOL_CONNECTION_TYPE_ETHER_TCP("ETHERTCP")

for SERIAL mode :

port : Name of the port ("/dev/ttyUSB0")

baudRate : baudrate

stopBits : number of stopbits

parity : parity mode (0=none, 1=odd, 2=even)

bitsPerWord : number of bits per word

serialMode : Serial Mode : SERIAL_232("RS232") or SERIAL_485("RS485").
if SERIAL_485

serialGPIOswitch : pin number as a filename in "/sys/class/gpio/"

serialGPIOrsmode : pin number as a filename in "/sys/class/gpio/"

for ETHERNET mode :

port : TCP port to be used

ipAddress : the 4 octet IP address of the field device (xxx.xxx.xxx.xxx)

Throws:

ModbusProtocolException(INVALID_CONFIGURATION) - unspecified problem with the configuration

ModbusProtocolException

getConnectStatus

int getConnectStatus()

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.

Returns:

current connection status as defined in EsfConnectionStatus.

connect

void connect()
             throws ModbusProtocolException

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.

Throws:

ModbusProtocolException(INVALID_CONFIGURATION) - this operates on the basic assumption that access to a device should exist, if the device is unreachable, it is interpreted as a failure of the configuration.

ModbusProtocolException

disconnect

void disconnect()

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.

See Also:

getConnectStatus()

readCoils

boolean[] readCoils(int dataAddress,
                    int count)
                    throws ModbusProtocolException

Modbus function 01
Read 1 to 2000 contiguous status of coils from the attached field device.

Parameters:

dataAddress - starting address

count - quantity of coils

Returns:

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

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

readDiscreteInputs

boolean[] readDiscreteInputs(int dataAddress,
                             int count)
                             throws ModbusProtocolException

Modbus function 02
Read 1 to 2000 contiguous status of discrete inputs from the attached field device.

Parameters:

dataAddress - starting address

count - quantity of inputs

Returns:

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

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

writeSingleCoil

void writeSingleCoil(int dataAddress,
                     boolean data)
                     throws ModbusProtocolException

Modbus function 05
write a single output to either ON or OFF in the attached field device.

Parameters:

dataAddress - Output address.

data - Output value (boolean) to write.

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

writeMultipleCoils

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

Modbus function 15 (0x0F)
write multiple coils in a sequence of coils to either ON or OFF in the attached field device.

Parameters:

dataAddress - Starting Output address.

data - Outputs value (array of boolean) to write.

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

readHoldingRegisters

int[] readHoldingRegisters(int dataAddress,
                           int count)
                           throws ModbusProtocolException

Modbus function 03
Read contents of 1 to 125 contiguous block of holding registers from the attached field device.

Parameters:

dataAddress - starting address

count - quantity of registers (maximum 0x7D)

Returns:

an array of int representing the requested data points (data registers on 2 bytes).

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

readInputRegisters

int[] readInputRegisters(int dataAddress,
                         int count)
                         throws ModbusProtocolException

Modbus function 04
Read contents of 1 to 125 contiguous block of input registers from the attached field device.

Parameters:

dataAddress - starting address

count - quantity of registers (maximum 0x7D)

Returns:

an array of int representing the requested data points (data registers on 2 bytes).

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

writeSingleRegister

void writeSingleRegister(int dataAddress,
                         int data)
                         throws ModbusProtocolException

Modbus function 06
write a single holding register in the attached field device.

Parameters:

dataAddress - Output address.

data - Output value (2 bytes) to write.

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

readExceptionStatus

boolean[] readExceptionStatus()
                              throws ModbusProtocolException

Modbus function 07
read the content of 8 Exception Status outputs in the field device.

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

getCommEventCounter

ModbusCommEvent getCommEventCounter()
                                    throws ModbusProtocolException

Modbus function 11 (0x0B)
Get a status word and an event count from the device.
Return values in a ModbusCommEvent.

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

See Also:

getCommEventLog

ModbusCommEvent getCommEventLog()
                                throws ModbusProtocolException

Modbus function 12 (0x0C)
Get a status word, an event count, a message count and a list of event bytes from the device.
Return values in a ModbusCommEvent.

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

See Also:

writeMultipleRegister

void writeMultipleRegister(int dataAddress,
                           int[] data)
                           throws ModbusProtocolException

Modbus function 16 (0x10)
write a block of contiguous registers (1 to 123) in the attached field device.

Parameters:

dataAddress - Output address.

data - Registers value (array of int converted in 2 bytes values) to write.

Throws:

ModbusProtocolException(NOT_CONNECTED) - current connection is in a status other than CONNECTED

ModbusProtocolException(TRANSACTION_FAILURE) - should include a protocol specific message to help clarify the cause of the exception

ModbusProtocolException

getPosition

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

Return OSGI Position of the device

See Also:

Position

getNmeaPosition

NmeaPosition getNmeaPosition()

Return NMEA Position of the device

See Also:

NmeaPosition