Package org.openhab.core.io.transport.modbus

Class ModbusBitUtilities

java.lang.Object
org.openhab.core.io.transport.modbus.ModbusBitUtilities
@NonNullByDefault public class ModbusBitUtilities extends Object
Utilities for working with binary data.
Author:
Sami Salonen - Initial contribution

  • Constructor Summary

    Constructors
    Constructor
    Description
    ModbusBitUtilities()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static ModbusRegisterArray
    commandToRegisters(Command command, ModbusConstants.ValueType type)
    Convert command to array of registers using a specific value type
    static int
    extractBit(byte[] bytes, int index)
    Extract single bit from registers represented by sequence of bytes - indices between 0...15 (inclusive) represent bits of the first register - indices between 16...31 (inclusive) represent bits of the second register, etc.
    static int
    extractBit(byte[] bytes, int registerIndex, int bitIndexWithinRegister)
    Extract single bit from registers represented by sequence of bytes bitIndexWithinRegister between 0...15 (inclusive) represent bits of the first register, where 0 refers to the least significant bit of the register, index 1 refers to the second least significant bit of the register, etc.
    static float
    extractFloat32(byte[] bytes, int index)
    Extract single-precision 32-bit IEEE 754 floating point from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
    static float
    extractFloat32Swap(byte[] bytes, int index)
    Extract single-precision 32-bit IEEE 754 floating point from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
    static short
    extractSInt16(byte[] bytes, int index)
    Extract signed 16-bit integer (short) from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order
    static int
    extractSInt32(byte[] bytes, int index)
    Extract signed 32-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order
    static int
    extractSInt32Swap(byte[] bytes, int index)
    Extract signed 32-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
    static long
    extractSInt64(byte[] bytes, int index)
    Extract signed 64-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
    static long
    extractSInt64Swap(byte[] bytes, int index)
    Extract signed 64-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
    static byte
    extractSInt8(byte[] bytes, int index)
    Extract signed 8-bit integer (byte) from registers represented by sequence of bytes - index 0 refers to low byte of the first register, 1 high byte of first register - index 2 refers to low byte of the second register, 3 high byte of second register, etc.
    static byte
    extractSInt8(byte[] bytes, int registerIndex, boolean hiByte)
    Extract signed 8-bit integer (byte) from registers represented by sequence of bytes
    static Optional<DecimalType>
    extractStateFromRegisters(ModbusRegisterArray registers, int index, ModbusConstants.ValueType type)
    Read data from registers and convert the result to DecimalType Interpretation of index goes as follows depending on type BIT: - a single bit is read from the registers - indices between 0...15 (inclusive) represent bits of the first register - indices between 16...31 (inclusive) represent bits of the second register, etc.
    static String
    extractStringFromBytes(byte[] bytes, int byteIndex, int length, Charset charset)
    Read data from bytes and convert the result to String Raw byte array values are converted using the charset parameter and a maximum of length bytes are read.
    static String
    extractStringFromRegisters(ModbusRegisterArray registers, int registerIndex, int length, Charset charset)
    Read data from registers and convert the result to String Strings should start the the first byte of a register, but could have an odd number of characters.
    static int
    extractUInt16(byte[] bytes, int index)
    Extract unsigned 16-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order
    static long
    extractUInt32(byte[] bytes, int index)
    Extract unsigned 32-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order
    static long
    extractUInt32Swap(byte[] bytes, int index)
    Extract unsigned 32-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
    static BigInteger
    extractUInt64(byte[] bytes, int index)
    Extract unsigned 64-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
    static BigInteger
    extractUInt64Swap(byte[] bytes, int index)
    Extract unsigned 64-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
    static short
    extractUInt8(byte[] bytes, int index)
    Extract unsigned 8-bit integer (byte) from registers represented by sequence of bytes - index 0 refers to low byte of the first register, 1 high byte of first register - index 2 refers to low byte of the second register, 3 high byte of second register, etc.
    static short
    extractUInt8(byte[] bytes, int registerIndex, boolean hiByte)
    Extract unsigned 8-bit integer (byte) from registers represented by sequence of bytes
    static Optional<Boolean>
    translateCommand2Boolean(Command command)
    Converts command to a boolean true value is represented by OnOffType.ON, OpenClosedType.OPEN.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ModbusBitUtilities

      public ModbusBitUtilities()

  • Method Details

    • extractStateFromRegisters

      public static Optional<DecimalType> extractStateFromRegisters(ModbusRegisterArray registers, int index, ModbusConstants.ValueType type)
      Read data from registers and convert the result to DecimalType Interpretation of index goes as follows depending on type BIT: - a single bit is read from the registers - indices between 0...15 (inclusive) represent bits of the first register - indices between 16...31 (inclusive) represent bits of the second register, etc. - index 0 refers to the least significant bit of the first register - index 1 refers to the second least significant bit of the first register, etc. INT8: - a byte (8 bits) from the registers is interpreted as signed integer - index 0 refers to low byte of the first register, 1 high byte of first register - index 2 refers to low byte of the second register, 3 high byte of second register, etc. - it is assumed that each high and low byte is encoded in most significant bit first order UINT8: - same as INT8 except value is interpreted as unsigned integer INT16: - register with index (counting from zero) is interpreted as 16 bit signed integer. - it is assumed that each register is encoded in most significant bit first order UINT16: - same as INT16 except value is interpreted as unsigned integer INT32: - registers (index) and (index + 1) are interpreted as signed 32bit integer. - it assumed that the first register contains the most significant 16 bits - it is assumed that each register is encoded in most significant bit first order INT32_SWAP: - Same as INT32 but registers swapped UINT32: - same as INT32 except value is interpreted as unsigned integer UINT32_SWAP: - same as INT32_SWAP except value is interpreted as unsigned integer FLOAT32: - registers (index) and (index + 1) are interpreted as signed 32bit floating point number. - it assumed that the first register contains the most significant 16 bits - it is assumed that each register is encoded in most significant bit first order - floating point NaN and infinity will return as empty optional FLOAT32_SWAP: - Same as FLOAT32 but registers swapped INT64: - registers (index), (index + 1), (index + 2), (index + 3) are interpreted as signed 64bit integer. - it assumed that the first register contains the most significant 16 bits - it is assumed that each register is encoded in most significant bit first order INT64_SWAP: - same as INT64 but registers swapped, that is, registers (index + 3), (index + 2), (index + 1), (index + 0) are interpreted as signed 64bit integer UINT64: - same as INT64 except value is interpreted as unsigned integer UINT64_SWAP: - same as INT64_SWAP except value is interpreted as unsigned integer
      Parameters:
      registers - list of registers, each register represent 16bit of data
      index - zero based item index. Interpretation of this depends on type, see examples above. With type larger or equal to 16 bits, the index tells the register index to start reading from. With type less than 16 bits, the index tells the N'th item to read from the registers.
      type - item type, e.g. unsigned 16bit integer (ModbusBindingProvider.ValueType.UINT16)
      Returns:
      number representation queried value, DecimalType. Empty optional is returned with NaN and infinity floating point values
      Throws:
      IllegalStateException - in cases where implementation is lacking for the type. This can be considered a bug
      IllegalArgumentException - when index is out of bounds of registers

    • extractBit

      public static int extractBit(byte[] bytes, int index)
      Extract single bit from registers represented by sequence of bytes - indices between 0...15 (inclusive) represent bits of the first register - indices between 16...31 (inclusive) represent bits of the second register, etc. - index 0 refers to the least significant bit of the first register - index 1 refers to the second least significant bit of the first register, etc.
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of bit
      Returns:
      0 when bit is set, 1 otherwise
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractBit

      public static int extractBit(byte[] bytes, int registerIndex, int bitIndexWithinRegister)
      Extract single bit from registers represented by sequence of bytes bitIndexWithinRegister between 0...15 (inclusive) represent bits of the first register, where 0 refers to the least significant bit of the register, index 1 refers to the second least significant bit of the register, etc.
      Parameters:
      bytes - registers represented by sequence of bytes
      registerIndex - index of register. First register has index of 0.
      bitIndexWithinRegister - bit index within the register
      Returns:
      0 when bit is set, 1 otherwise
      Throws:
      IllegalArgumentException - when registerIndex and/or bitIndexWithinRegister is out of bounds

    • extractSInt8

      public static byte extractSInt8(byte[] bytes, int registerIndex, boolean hiByte)
      Extract signed 8-bit integer (byte) from registers represented by sequence of bytes
      Parameters:
      bytes - registers represented by sequence of bytes
      registerIndex - index of register. First register has index of 0.
      hiByte - whether to extract hi byte or lo byte
      Returns:
      0 when bit is set, 1 otherwise
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractSInt8

      public static byte extractSInt8(byte[] bytes, int index)
      Extract signed 8-bit integer (byte) from registers represented by sequence of bytes - index 0 refers to low byte of the first register, 1 high byte of first register - index 2 refers to low byte of the second register, 3 high byte of second register, etc. - it is assumed that each high and low byte is encoded in most significant bit first order
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of the byte in registers
      Returns:
      0 when bit is set, 1 otherwise
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractUInt8

      public static short extractUInt8(byte[] bytes, int registerIndex, boolean hiByte)
      Extract unsigned 8-bit integer (byte) from registers represented by sequence of bytes
      Parameters:
      bytes - registers represented by sequence of bytes
      registerIndex - index of register. First register has index of 0.
      hiByte - whether to extract hi byte or lo byte
      Returns:
      0 when bit is set, 1 otherwise
      Throws:
      IllegalArgumentException - when registerIndex is out of bounds

    • extractUInt8

      public static short extractUInt8(byte[] bytes, int index)
      Extract unsigned 8-bit integer (byte) from registers represented by sequence of bytes - index 0 refers to low byte of the first register, 1 high byte of first register - index 2 refers to low byte of the second register, 3 high byte of second register, etc. - it is assumed that each high and low byte is encoded in most significant bit first order
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of the byte in registers
      Returns:
      0 when bit is set, 1 otherwise
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractSInt16

      public static short extractSInt16(byte[] bytes, int index)
      Extract signed 16-bit integer (short) from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of register. First register has index of 0.
      Returns:
      register with index interpreted as 16 bit signed integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractUInt16

      public static int extractUInt16(byte[] bytes, int index)
      Extract unsigned 16-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of register. First register has index of 0.
      Returns:
      register with index interpreted as 16 bit unsigned integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractSInt32

      public static int extractSInt32(byte[] bytes, int index)
      Extract signed 32-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index) and (index+1) interpreted as 32 bit signed integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractUInt32

      public static long extractUInt32(byte[] bytes, int index)
      Extract unsigned 32-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index) and (index+1) interpreted as 32 bit unsigned integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractSInt32Swap

      public static int extractSInt32Swap(byte[] bytes, int index)
      Extract signed 32-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order. This is identical with extractSInt32, but with registers swapped.
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index+1), (index) interpreted as 32 bit signed integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractUInt32Swap

      public static long extractUInt32Swap(byte[] bytes, int index)
      Extract unsigned 32-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order. This is identical with extractUInt32, but with registers swapped.
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index+1), (index) interpreted as 32 bit unsigned integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractSInt64

      public static long extractSInt64(byte[] bytes, int index)
      Extract signed 64-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index), (index+1), (index+2), (index+3) interpreted as 64 bit signed integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractUInt64

      public static BigInteger extractUInt64(byte[] bytes, int index)
      Extract unsigned 64-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order.
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index), (index+1), (index+2), (index+3) interpreted as 64 bit unsigned integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractSInt64Swap

      public static long extractSInt64Swap(byte[] bytes, int index)
      Extract signed 64-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order. This is identical with extractInt64, but with registers swapped (registers with higher index before lower index).
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index+3), (index+2), (index+1), (index) interpreted as 64 bit signed integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractUInt64Swap

      public static BigInteger extractUInt64Swap(byte[] bytes, int index)
      Extract unsigned 64-bit integer from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order. This is identical with extractUInt64, but with registers swapped (registers with higher index before lower index).
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index+3), (index+2), (index+1), (index) interpreted as 64 bit unsigned integer
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractFloat32

      public static float extractFloat32(byte[] bytes, int index)
      Extract single-precision 32-bit IEEE 754 floating point from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order. Note that this method can return floating point NaN and floating point infinity.
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index), (index+1), (index+2), (index+3) interpreted as single-precision 32-bit IEEE 754 floating point
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractFloat32Swap

      public static float extractFloat32Swap(byte[] bytes, int index)
      Extract single-precision 32-bit IEEE 754 floating point from registers represented by sequence of bytes It is assumed that each register is encoded in most significant bit first order. This is identical with extractFloat32, but with registers swapped (registers with higher index before lower index). Note that this method can return floating point NaN and floating point infinity.
      Parameters:
      bytes - registers represented by sequence of bytes
      index - index of first register. First register has index of 0.
      Returns:
      registers (index+3), (index+2), (index+1), (index) interpreted as single-precision 32-bit IEEE 754 floating point
      Throws:
      IllegalArgumentException - when index is out of bounds

    • extractStringFromRegisters

      public static String extractStringFromRegisters(ModbusRegisterArray registers, int registerIndex, int length, Charset charset)
      Read data from registers and convert the result to String Strings should start the the first byte of a register, but could have an odd number of characters. Raw byte array values are converted using the charset parameter and a maximum of length bytes are read. However reading stops at the first NUL byte encountered. Registers are read in big-endian order, i.e. two registers consisting 4 bytes (ab, cd) are parsed as sequence of bytes (a,b,c,d).
      Parameters:
      registers - list of registers, each register represent 16bit of data
      registerIndex - zero based register index. Registers are handled as 16bit registers, this parameter defines the starting register.
      length - maximum length of string in 8bit characters (number of bytes considered)
      charset - the character set used to construct the string.
      Returns:
      string representation queried value
      Throws:
      IllegalArgumentException - when index is out of bounds of registers

    • extractStringFromBytes

      public static String extractStringFromBytes(byte[] bytes, int byteIndex, int length, Charset charset)
      Read data from bytes and convert the result to String Raw byte array values are converted using the charset parameter and a maximum of length bytes are read. However reading stops at the first NUL byte encountered.
      Parameters:
      bytes - bytes representing the registers
      byteIndex - zero based byte index
      length - maximum length of string in 8bit characters (number of bytes considered)
      charset - the character set used to construct the string.
      Returns:
      string representation queried value
      Throws:
      IllegalArgumentException - when index is out of bounds of registers

    • commandToRegisters

      public static ModbusRegisterArray commandToRegisters(Command command, ModbusConstants.ValueType type)
      Convert command to array of registers using a specific value type
      Parameters:
      command - command to be converted. Either OnOffType, OpenClosedType, DecimalType or QuantityType that can be converted to dimensionless unit.
      type - value type to use in conversion
      Returns:
      array of registers
      Throws:
      IllegalArgumentException - in cases where implementation is lacking for the type. This is thrown with 1-bit and 8-bit value types. Also raised with unsupported command types

    • translateCommand2Boolean

      public static Optional<Boolean> translateCommand2Boolean(Command command)
      Converts command to a boolean true value is represented by OnOffType.ON, OpenClosedType.OPEN. false value is represented by OnOffType.OFF, OpenClosedType.CLOSED. Furthermore, DecimalType are converted to boolean true if they are unequal to zero.
      Parameters:
      command - to convert to boolean
      Returns:
      Boolean value matching the command. Empty if command cannot be converted