Class ModbusBitUtilities


  • @NonNullByDefault
    public class ModbusBitUtilities
    extends Object
    Utilities for working with binary data.
    Author:
    Sami Salonen - Initial contribution
    • Method Summary

      All Methods Static Methods Concrete Methods 
      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.
    • Constructor Detail

      • ModbusBitUtilities

        public ModbusBitUtilities()
    • Method Detail

      • 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
        registerIndex - index of register. First register has index of 0.
        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
        registerIndex - index of register. First register has index of 0.
        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