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


    Copyright © 2013. All Rights Reserved.