Package net.solarnetwork.node.io.modbus

Interface ModbusConnection

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
LockingModbusConnection, ModbusConnectionSupport, StaticDataMapModbusConnection, StaticDataMapReadonlyModbusConnection
public interface ModbusConnection extends Closeable
High level Modbus connection API.

This API aims to simplify accessing Modbus capable devices without having any direct dependency on Jamod (or any other Modbus implementation).

Since:
2.0
Version:
3.1
Author:
matt

  • Method Details

    • getUnitId

      int getUnitId()
      Get the Modbus Unit ID this device represents.
      Returns:
      the unit ID

    • open

      void open() throws IOException, net.solarnetwork.node.service.LockTimeoutException
      Open the connection, if it is not already open. The connection must be opened before calling any of the other methods in this API.
      Throws:
      IOException - if the connection cannot be opened
      net.solarnetwork.node.service.LockTimeoutException - if a lock is required to open the connection and it could not be obtained within a configured maximum amount of time

    • close

      void close()
      Close the connection, if it is open.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • readDiscreteValues

      default BitSet readDiscreteValues(int address, int count) throws IOException
      Get the values of a set of "coil" type registers, as a BitSet.

      This uses a Modbus function code 1 request.

      This method by default invokes readDiscreetValues(int, int) for backwards compatibility.

      Parameters:
      address - the 0-based Modbus register address to read
      count - the count of discreet registers to read
      Returns:
      BitSet, with indexes set from 0 to a count - 1
      Throws:
      IOException - if any communication error occurs
      Since:
      3.1

    • readDiscreetValues

      @Deprecated BitSet readDiscreetValues(int address, int count) throws IOException
      Deprecated.
      since 3.1 use readDiscreteValues(int, int)
      Get the values of a set of "coil" type registers, as a BitSet.

      This uses a Modbus function code 1 request.

      This method is required but deprecated to preserve backwards compatibility.

      Parameters:
      address - the 0-based Modbus register address to read
      count - the count of discreet registers to read
      Returns:
      BitSet, with indexes set from 0 to a count - 1
      Throws:
      IOException - if any communication error occurs
      Since:
      1.1

    • readDiscreteValues

      default BitSet readDiscreteValues(int[] addresses, int count) throws IOException
      Get the values of a set of "coil" type registers, as a BitSet.

      This uses a Modbus function code 1 request. The returned set will have a size equal to addresses.length * count.

      This method by default invokes readDiscreetValues(int, int) for backwards compatibility.

      Parameters:
      addresses - the 0-based Modbus register addresses to read
      count - the count of coils to read with each address
      Returns:
      BitSet, with each count indexes for each index in the addresses parameter
      Throws:
      IOException - if any communication error occurs

    • readDiscreetValues

      @Deprecated BitSet readDiscreetValues(int[] addresses, int count) throws IOException
      Deprecated.
      since 3.1 use readDiscreteValues(int[], int)
      Get the values of a set of "coil" type registers, as a BitSet.

      This uses a Modbus function code 1 request. The returned set will have a size equal to addresses.length * count.

      This method is required but deprecated to preserve backwards compatibility.

      Parameters:
      addresses - the 0-based Modbus register addresses to read
      count - the count of coils to read with each address
      Returns:
      BitSet, with each count indexes for each index in the addresses parameter
      Throws:
      IOException - if any communication error occurs

    • writeDiscreteValues

      default void writeDiscreteValues(int[] addresses, BitSet bits) throws IOException
      Write values of a set of "coil" type registers, via a BitSet.

      This uses a Modbus function code 5 request, once for each address in addresses. Each address at index i corresponds to the value of bit at index i. Thus bits 0 to addresses.length - 1 are used.

      This method by default invokes writeDiscreetValues(int[], BitSet) for backwards compatibility.

      Parameters:
      addresses - the Modbus register addresses to start writing to
      bits - the bits to write, each index corresponding to an index in addresses
      Throws:
      IOException - if any communication error occurs

    • writeDiscreetValues

      @Deprecated void writeDiscreetValues(int[] addresses, BitSet bits) throws IOException
      Deprecated.
      since 3.1 use writeDiscreteValues(int[], BitSet)
      Write values of a set of "coil" type registers, via a BitSet.

      This uses a Modbus function code 5 request, once for each address in addresses. Each address at index i corresponds to the value of bit at index i. Thus bits 0 to addresses.length - 1 are used.

      This method is required but deprecated to preserve backwards compatibility.

      Parameters:
      addresses - the Modbus register addresses to start writing to
      bits - the bits to write, each index corresponding to an index in addresses
      Throws:
      IOException - if any communication error occurs

    • readInputDiscreteValues

      BitSet readInputDiscreteValues(int address, int count) throws IOException
      Get the values of a set of "input discrete" type registers, as a BitSet.

      This uses a Modbus function code 2 request. The returned bitset will have count values set, from 0 to count - 1.

      Parameters:
      address - the Modbus register addresses to start reading from
      count - the count of registers to read
      Returns:
      BitSet, with each 0 to count indexes
      Throws:
      IOException - if any communication error occurs

    • readWords

      short[] readWords(ModbusReadFunction function, int address, int count) throws IOException
      Get the values of specific 16-bit Modbus registers as an array of 16-bit words.

      Note that the raw short values can be treated as unsigned shorts by converting them to integers, like int unsigned = ((int)s) && 0xFFFF, or by calling Short.toUnsignedInt(short). Thus the values returned by this method are technically the same as those returned by readWordsUnsigned(ModbusReadFunction, int, int), without having been cast to ints.

      Parameters:
      function - the Modbus function code to use
      address - the 0-based Modbus register address to start reading from
      count - the number of Modbus 16-bit registers to read
      Returns:
      array of register values; the result will have a length equal to count
      Throws:
      IOException - if any communication error occurs

    • readWordsUnsigned

      int[] readWordsUnsigned(ModbusReadFunction function, int address, int count) throws IOException
      Get the values of specific 16-bit Modbus registers as an array of unsigned 16-bit words.

      Note that the raw int values can be treated as signed shorts by casting them to shorts, like short signed = (short)s. Thus the values returned by this method are technically the same as those returned by readWords(ModbusReadFunction, int, int), having been cast to ints.

      Parameters:
      function - the Modbus function code to use
      address - the 0-based Modbus register address to start reading from
      count - the number of 16-bit Modbus registers to read
      Returns:
      array of register values; the result will have a length equal to count
      Throws:
      IOException - if any communication error occurs

    • writeWords

      void writeWords(ModbusWriteFunction function, int address, short[] values) throws IOException
      Write 16-bit word values to 16-bit Modbus registers.
      Parameters:
      function - the Modbus function code to use
      address - the 0-based Modbus register address to start writing to
      values - the 16-bit values to write
      Throws:
      IOException - if any communication error occurs

    • writeWords

      void writeWords(ModbusWriteFunction function, int address, int[] values) throws IOException
      Write unsigned 16-bit word values to 16-bit Modbus registers.

      All the elements in values will be truncated to 16-bits and then stored in Modbus registers.

      Parameters:
      function - the Modbus function code to use
      address - the 0-based Modbus register address to start writing to
      values - the unsigned 16-bit values to write
      Throws:
      IOException - if any communication error occurs

    • readBytes

      byte[] readBytes(ModbusReadFunction function, int address, int count) throws IOException
      Get the raw bytes of specific registers.

      Each 16-bit modbus register value will be decomposed into two output bytes, so that the returned result will have a length equal to count * 2.

      Parameters:
      function - the Modbus function code to use
      address - the 0-based Modbus register address to start reading from
      count - the number of Modbus 16-bit registers to read
      Returns:
      register words as an array of bytes
      Throws:
      IOException - if any communication error occurs

    • writeBytes

      void writeBytes(ModbusWriteFunction function, int address, byte[] values) throws IOException
      Write raw byte values to registers.
      Parameters:
      function - the Modbus function code to use
      address - the 0-based Modbus register address to start writing to; values.length * 2 16-bit registers will be written
      values - the byte values to write
      Throws:
      IOException - if any communication error occurs

    • readString

      String readString(ModbusReadFunction function, int address, int count, boolean trim, Charset charset) throws IOException
      Read a set of registers as bytes and interpret as a string.
      Parameters:
      function - the Modbus function code to use
      address - the 0-based Modbus register address to start reading from
      count - the number of Modbus 16-bit registers to read
      trim - if true then remove leading/trailing whitespace from the resulting string
      charset - the character set to interpret the bytes as
      Returns:
      String from interpreting raw bytes as a string
      Throws:
      IOException - if any communication error occurs
      See Also:

    • writeString

      void writeString(ModbusWriteFunction function, int address, String value, Charset charset) throws IOException
      Write a string as raw byte values to registers.
      Parameters:
      function - the Modbus function code to use
      address - the 0-based Modbus register address to start writing to
      value - the string value to write
      charset - the character set to interpret the bytes as
      Throws:
      IOException - if any communication error occurs