Package net.solarnetwork.node.io.modbus

Class ModbusData

java.lang.Object
net.solarnetwork.node.io.modbus.ModbusData
All Implemented Interfaces:
net.solarnetwork.node.domain.DataAccessor
public class ModbusData extends Object implements net.solarnetwork.node.domain.DataAccessor
Object to hold raw data extracted from a Modbus device.

This class is designed to operate as a cache of data read from a Modbus device. The data is modeled as a sparse array of register address keys with associated 16-bit values. It supports thread-safe write access to the saved data and thread-safe read access if ModbusData(ModbusData) or copy() are invoked to get a copy of the data.

Since:
2.3
Version:
3.1
Author:
matt

  • Constructor Details

    • ModbusData

      public ModbusData()
      Default constructor.

    • ModbusData

      public ModbusData(ModbusData other)
      Copy constructor.

      This method provides a thread-safe way to get a copy of the current data.

      Parameters:
      other - the object to copy

  • Method Details

    • size

      public int size()
      Get the number of registers with a set value.
      Returns:
      the number of set registers

    • isEmpty

      public boolean isEmpty()
      Test if the register data is empty.
      Returns:
      true if no registers have been set

    • getDataTimestamp

      public Instant getDataTimestamp()
      Specified by:
      getDataTimestamp in interface net.solarnetwork.node.domain.DataAccessor

    • getDeviceInfo

      public Map<String,Object> getDeviceInfo()
      Specified by:
      getDeviceInfo in interface net.solarnetwork.node.domain.DataAccessor

    • copy

      public ModbusData copy()
      Create a copy of this object.

      This method provides a thread-safe way to get a copy of the current data.

      Returns:
      the new instance
      See Also:

    • getNumber

      public final Number getNumber(ModbusReference ref)
      Get a number value from a reference.
      Parameters:
      ref - the reference to get the number value for
      Returns:
      the value, or null if ref is null
      Throws:
      IllegalArgumentException - if the reference data type is not numeric
      Since:
      1.4

    • getNumber

      public final Number getNumber(ModbusReference ref, int offset)
      Get a number value from a relative reference.
      Parameters:
      ref - the relative reference to get the number value for
      offset - the address offset to add to ModbusReference.getAddress()
      Returns:
      the value, or null if ref is null
      Throws:
      IllegalArgumentException - if the reference data type is not numeric
      Since:
      1.4

    • getBoolean

      public final Boolean getBoolean(int addr)
      Construct a 1-bit boolean from a data register address.
      Parameters:
      addr - the address
      Returns:
      the boolean, never null

    • getUnsignedInt16

      public final Integer getUnsignedInt16(int addr)
      Construct an unsigned 16-bit integer from a data register address.
      Parameters:
      addr - the register address
      Returns:
      the integer, never null

    • getInt16

      public final Short getInt16(int addr)
      Construct a signed 16-bit integer from a data register address.
      Parameters:
      addr - the register address
      Returns:
      the short, never null

    • getUnsignedInt32

      public final Long getUnsignedInt32(int hiAddr, int loAddr)
      Construct an unsigned 32-bit integer from data register addresses.
      Parameters:
      hiAddr - the address of the high 16 bits
      loAddr - the address of the low 16 bits
      Returns:
      the parsed value, or null if not available

    • getInt32

      public final Integer getInt32(int hiAddr, int loAddr)
      Construct a signed 32-bit integer from data register addresses.
      Parameters:
      hiAddr - the address of the high 16 bits
      loAddr - the address of the low 16 bits
      Returns:
      the parsed value, or null if not available
      Since:
      1.1

    • getInt32

      public final Integer getInt32(int addr)
      Construct a signed 32-bit integer from data register addresses.

      This method will respect the configured getWordOrder() value.

      Parameters:
      addr - the address of the first register; the second register is assumed to be addr + 1
      Returns:
      the parsed value, or null if not available
      Since:
      1.1

    • getUnsignedInt32

      public final Long getUnsignedInt32(int addr)
      Construct an unsigned 32-bit integer from a starting data register address.

      This method will respect the configured getWordOrder() value.

      Parameters:
      addr - the address of the first register; the second register is assumed to be addr + 1
      Returns:
      the parsed value, or null if not available

    • getFloat16

      public final net.solarnetwork.util.Half getFloat16(int addr)
      Construct a 16-bit float from data register addresses.
      Parameters:
      addr - the address of the 16 bits
      Returns:
      the parsed value, or null if not available.
      Since:
      1.4

    • getFloat32

      public final Float getFloat32(int hiAddr, int loAddr)
      Construct a 32-bit float from data register addresses.
      Parameters:
      hiAddr - the address of the high 16 bits
      loAddr - the address of the low 16 bits
      Returns:
      the parsed value, or null if not available.

    • getFloat32

      public final Float getFloat32(int addr)
      Construct a 32-bit float from a starting data register address.

      This method will respect the configured getWordOrder() value.

      Parameters:
      addr - the address of the first register; the second register is assumed to be addr + 1
      Returns:
      The parsed value, or null if not available.

    • getInt64

      public final Long getInt64(int h1Addr, int h2Addr, int l1Addr, int l2Addr)
      Construct a signed 64-bit long value from data register addresses.
      Parameters:
      h1Addr - the address of bits 63-48
      h2Addr - the address of bits 47-32
      l1Addr - the address of bits 31-16
      l2Addr - the address of bits 15-0
      Returns:
      the parsed long

    • getInt64

      public final Long getInt64(int addr)
      Construct a signed 64-bit integer from a starting data register address.

      This method will respect the configured getWordOrder() value.

      Parameters:
      addr - the address of the first register; the remaining three registers are assumed to be addr + 1, addr + 2, and addr + 3
      Returns:
      the parsed value, or null if not available

    • getUnsignedInt64

      public final BigInteger getUnsignedInt64(int h1Addr, int h2Addr, int l1Addr, int l2Addr)
      Construct an unsigned 64-bit integer from data register addresses.
      Parameters:
      h1Addr - the address of bits 63-48
      h2Addr - the address of bits 47-32
      l1Addr - the address of bits 31-16
      l2Addr - the address of bits 15-0
      Returns:
      the parsed value, or null if not available
      Since:
      1.1

    • getUnsignedInt64

      public final BigInteger getUnsignedInt64(int addr)
      Construct an unsigned 64-bit integer from data register addresses.

      This method will respect the configured getWordOrder() value.

      Parameters:
      addr - the address of the first register; the remaining three registers are assumed to be addr + 1, addr + 2, and addr + 3
      Returns:
      the parsed value, or null if not available
      Since:
      1.1

    • getFloat64

      public final Double getFloat64(int h1Addr, int h2Addr, int l1Addr, int l2Addr)
      Construct a 32-bit float from data register addresses.
      Parameters:
      h1Addr - the address of bits 63-48
      h2Addr - the address of bits 47-32
      l1Addr - the address of bits 31-16
      l2Addr - the address of bits 15-0
      Returns:
      the parsed value, or null if not available

    • getFloat64

      public final Double getFloat64(int addr)
      Construct a 32-bit float from a starting data register address.

      This method will respect the configured getWordOrder() value.

      Parameters:
      addr - the address of the first register; the remaining three registers are assumed to be addr + 1, addr + 2, and addr + 3
      Returns:
      The parsed value, or null if not available.

    • getBytes

      public byte[] getBytes(int addr, int count)
      Construct a byte array out of a data address range.

      This method will assume ModbusWordOrder.MostToLeastSignificant word ordering.

      Parameters:
      addr - the starting address of the 16-bit register to read
      count - the number of 16-bit registers to read
      Returns:
      the byte array, which will have a length of count * 2

    • getString

      public final String getString(int addr, int count, boolean trim, String charsetName)
      Construct a string out of a data address range.

      This method calls getBytes(int, int) to interpret the data addresses as a raw byte array, and then interprets the result as a string in the given character set.

      Parameters:
      addr - the starting address of the 16-bit register to read
      count - the number of 16-bit registers to read
      trim - if true then remove leading/trailing whitespace from the resulting string
      charsetName - the character set to interpret the bytes as
      Returns:
      the parsed string, or null if count is 0
      Throws:
      IllegalCharsetNameException - If the given character set name is illegal
      IllegalArgumentException - If charsetName is null
      UnsupportedCharsetException - If no support for the named character set is available

    • getString

      public final String getString(int addr, int count, boolean trim, Charset charset)
      Construct a string out of a data address range.

      This method calls getBytes(int, int) to interpret the data addresses as a raw byte array, and then interprets the result as a string in the given character set.

      Parameters:
      addr - the starting address of the 16-bit register to read
      count - the number of 16-bit registers to read
      trim - if true then remove leading/trailing whitespace from the resulting string as well as any null bytes, i.e. \0
      charset - the character set to interpret the bytes as
      Returns:
      the parsed string, or null if count is 0

    • getUtf8String

      public final String getUtf8String(int addr, int count, boolean trim)
      Construct a UTF-8 string out of a data address range.
      Parameters:
      addr - the starting address of the 16-bit register to read
      count - the number of 16-bit registers to read
      trim - if true then remove leading/trailing whitespace from the resulting string
      Returns:
      the parsed string

    • getAsciiString

      public final String getAsciiString(int addr, int count, boolean trim)
      Construct an ASCII string out of a data address range.
      Parameters:
      addr - the starting address of the 16-bit register to read
      count - the number of 16-bit registers to read
      trim - if true then remove leading/trailing whitespace from the resulting string
      Returns:
      the parsed string

    • getUtf8String

      public final String getUtf8String(ModbusReference ref, boolean trim)
      Construct a UTF-8 string from a reference.
      Parameters:
      ref - the reference to get the string value for
      trim - if true then remove leading/trailing whitespace from the resulting string
      Returns:
      the parsed string
      Since:
      1.4

    • getUtf8String

      public final String getUtf8String(ModbusReference ref, int offset, boolean trim)
      Construct a UTF-8 string from a reference.
      Parameters:
      ref - the reference to get the string value for
      offset - the address offset to add to ModbusReference.getAddress()
      trim - if true then remove leading/trailing whitespace from the resulting string
      Returns:
      the parsed string
      Since:
      1.4

    • getAsciiString

      public final String getAsciiString(ModbusReference ref, boolean trim)
      Construct an ASCII string from a reference.
      Parameters:
      ref - the reference to get the string value for
      trim - if true then remove leading/trailing whitespace from the resulting string
      Returns:
      the parsed string
      Since:
      1.4

    • getAsciiString

      public final String getAsciiString(ModbusReference ref, int offset, boolean trim)
      Construct an ASCII string from a relative reference.
      Parameters:
      ref - the reference to get the string value for
      offset - the address offset to add to ModbusReference.getAddress()
      trim - if true then remove leading/trailing whitespace from the resulting string
      Returns:
      the parsed string
      Since:
      1.4

    • getLatin1String

      public final String getLatin1String(ModbusReference ref, int offset, boolean trim)
      Construct an ISO-LATIN-1 string from a relative reference.
      Parameters:
      ref - the reference to get the string value for
      offset - the address offset to add to ModbusReference.getAddress()
      trim - if true then remove leading/trailing whitespace from the resulting string
      Returns:
      the parsed string
      Since:
      1.8

    • performUpdates

      public final ModbusData performUpdates(ModbusData.ModbusDataUpdateAction action) throws IOException
      Perform a set of updates to saved register data.
      Parameters:
      action - the callback to perform the updates on
      Returns:
      this object to allow method chaining
      Throws:
      IOException - if any communication error occurs

    • expire

      public final ModbusData expire()
      Force the data timestamp to be expired.

      Calling this method will reset the dataTimestamp to zero, effectively expiring the data.

      Returns:
      this object to allow method chaining
      Since:
      1.2

    • getValue

      public Object getValue(ModbusReference ref)
      Get a value for a reference.
      Parameters:
      ref - the reference to get the number value for
      Returns:
      the value, or null if ref is null
      Since:
      3.1

    • getValue

      public Object getValue(ModbusDataType dataType, int address, int count)
      Get a value.
      Parameters:
      dataType - the data type
      address - the register address
      count - the word length, for variable-length data types only
      Returns:
      the decoded value, or null
      Since:
      3.1

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • dataDebugString

      public final String dataDebugString()
      Get a string of data values, useful for debugging.

      The generated string will contain a register address followed by two register values per line, printed as hexidecimal integers, with a prefix and suffix line. For example: 

       ModbusData{
      30000: 0x4141, 0x727E
      30006: 0xFFC0, 0x0000
      ...
      30344: 0x0000, 0x0000
 }
      Returns:
      debug string

    • slice

      public final void slice(short[] dest, int destFrom, int address, int length)
      Copy the raw modbus data for a set of addresses into an array.
      Parameters:
      dest - the destination array
      destFrom - the starting destination array index to populate
      address - the Modbus address to start from
      length - the number of Modbus registers to copy
      Since:
      2.0

    • getWordOrder

      public final ModbusWordOrder getWordOrder()
      Get the word ordering to use when reading multi-register data types.
      Returns:
      the word order
      Since:
      1.3

    • setWordOrder

      public final void setWordOrder(ModbusWordOrder wordOrder)
      Set the word ordering to use when reading multi-register data types.
      Parameters:
      wordOrder - the word order to use; null will be ignored
      Since:
      1.3

    • refreshData

      public final void refreshData(ModbusConnection conn, net.solarnetwork.util.IntRangeSet rangeSet) throws IOException
      Refresh a range of data from the Modbus device into this object.

      This method uses the ModbusReadFunction.ReadHoldingRegister with a maximum of 64 addresses read per transaction.

      Parameters:
      conn - the connection
      rangeSet - the Modbus registers to read, where each IntRange in the set defines inclusive address ranges to read
      Throws:
      IOException - if any communication error occurs
      Since:
      1.6

    • refreshData

      public final void refreshData(ModbusConnection conn, ModbusReadFunction readFunction, net.solarnetwork.util.IntRangeSet rangeSet, int maxRangeLength) throws IOException
      Refresh a range of data from the Modbus device into this object.
      Parameters:
      conn - the connection
      readFunction - the Modbus read function to use
      rangeSet - the Modbus registers to read, where each IntRange in the set defines inclusive address ranges to read
      maxRangeLength - the maximum length of any combined range in the resulting set
      Throws:
      IOException - if any communication error occurs
      Since:
      1.6

    • refreshData

      public final void refreshData(ModbusConnection conn, ModbusReadFunction readFunction, Collection<net.solarnetwork.util.IntRange> ranges) throws IOException
      Refresh a range of data from the Modbus device into this object.
      Parameters:
      conn - the connection
      readFunction - the Modbus read function to use
      ranges - the Modbus registers to read, where each IntRange in the set defines inclusive address ranges to read
      Throws:
      IOException - if any communication error occurs
      Since:
      2.0

    • refreshData

      public final void refreshData(ModbusConnection conn, ModbusReadFunction readFunction, Collection<net.solarnetwork.util.IntRange> ranges, ModbusData.MutableModbusData m) throws IOException
      Read data from the device and update a mutable data instance.
      Parameters:
      conn - the connection
      readFunction - the read function
      ranges - the ranges of Modbus addresses to read/update
      m - the mutable data to update
      Throws:
      IOException - if any communication error occurs
      Since:
      2.0

    • getUnsignedDataMap

      public final Map<Integer,Integer> getUnsignedDataMap()
      Get a read-only Map view of all modbus registers as unsigned integer values.
      Returns:
      the data map, never null
      Since:
      1.7

    • dataRegisters

      public final net.solarnetwork.util.IntShortMap dataRegisters()
      Get direct access to all modbus registers.
      Returns:
      the data map, never null
      Since:
      3.1