pyModbusTCP.codec

Values on several registers: types and byte orders. See Values on several registers: Codec for an introduction.

from pyModbusTCP.codec import ByteOrder, Codec, DataType

Values on 16 bits registers: data types and byte orders.

A Modbus register holds a 16 bits value, sent big endian. A device stores a 32 or 64 bits value on 2 or 4 consecutive registers, in an order that it chooses: there is no standard. A Codec converts the values of a DataType to registers and back, in a ByteOrder, named in the notation of most Modbus software, where A is the most significant byte of the value:

ByteOrder.ABCD (BIG_ENDIAN)

the first register holds the most significant word (default)

ByteOrder.CDAB (WORD_SWAP)

the first register holds the least significant word (common on PLCs)

ByteOrder.BADC (BYTE_SWAP)

the bytes of each register are swapped

ByteOrder.DCBA (LITTLE_ENDIAN)

word swap and byte swap

For a 64 bits value, CDAB reverses the order of the 4 registers. For a 16 bits value, only the byte swap (BADC, DCBA) changes something.

A few devices store a 64 bits value in another order, like two 32 bits values in word swap (CDABGHEF): for these rare cases, ByteOrder64 gives the 8 orders of the 8 bytes (A to H) on 4 registers, for a Codec of a 64 bits type only.

from pyModbusTCP.codec import ByteOrder, Codec, DataType

f32 = Codec(DataType.FLOAT32, ByteOrder.CDAB)
f32.encode([3.14])              # [0xF5C3, 0x4048]
f32.decode([0xF5C3, 0x4048])    # [3.140000104904175]
class pyModbusTCP.codec.ByteOrder(*values)[source]

The order of the bytes of a value on the registers, A being the most significant byte of the value.

Each order has 2 names: ABCD and BIG_ENDIAN are the same member.

ABCD = 'ABCD'

Big endian: the first register holds the most significant word (the order of the Modbus specification).

CDAB = 'CDAB'

Word swap: the first register holds the least significant word (common on PLCs).

BADC = 'BADC'

Byte swap: the bytes of each register are swapped.

DCBA = 'DCBA'

Little endian: word swap and byte swap.

property word_swap: bool

True if the first register holds the least significant word (CDAB, DCBA).

property byte_swap: bool

True if the bytes of each register are swapped (BADC, DCBA).

class pyModbusTCP.codec.ByteOrder64(*values)[source]

The order of the 8 bytes of a 64 bits value on 4 registers, A being the most significant byte.

For the rare devices that ByteOrder doesn’t cover (only with a Codec of UINT64, INT64 or FLOAT64). The value of a member is its notation: the bytes in the order of the registers, 2 per register.

ABCDEFGH = 'ABCDEFGH'

Big endian (like ByteOrder.ABCD).

CDABGHEF = 'CDABGHEF'

Word swap in each 32 bits half (two 32 bits values in CDAB).

EFGHABCD = 'EFGHABCD'

The two 32 bits halves swapped, each half big endian.

GHEFCDAB = 'GHEFCDAB'

The 4 registers reversed (like ByteOrder.CDAB).

BADCFEHG = 'BADCFEHG'

Byte swap in each register (like ByteOrder.BADC).

DCBAHGFE = 'DCBAHGFE'

Each 32 bits half little endian, the halves in big endian order.

FEHGBADC = 'FEHGBADC'

The halves swapped, byte swap in each register.

HGFEDCBA = 'HGFEDCBA'

Little endian (like ByteOrder.DCBA).

class pyModbusTCP.codec.Codec(data_type: DataType = DataType.UINT16, byte_order: ByteOrder | ByteOrder64 = ByteOrder.ABCD)[source]

Convert the values of a data type to registers, and back, in a byte order.

A codec is immutable: create one per data type and byte order of a device, and reuse it.

Parameters:
  • data_type – the type of the values

  • byte_order – the order of the bytes on the registers, a ByteOrder64 for a rare order of a 64 bits type

Raises:
  • TypeError – if data_type is not a DataType, or byte_order not a ByteOrder (or ByteOrder64)

  • ValueError – for a ByteOrder64 with a type of 1 or 2 registers

property words: int

The number of registers of a value: 1, 2 or 4.

property is_float: bool

True for FLOAT32 and FLOAT64.

decode(registers: Sequence[int]) → list[int | float][source]

The values stored on registers.

Parameters:

registers – register values (0 to 65535), words per value

Returns:

the values (int, or float for a float type)

Raises:

ValueError – if the number of registers is not a multiple of words, or for a register that is not an int between 0 and 65535

encode(values: Sequence[int | float]) → list[int][source]

The registers of values, ready for a write.

Parameters:

values – the values (int, or int/float for a float type)

Returns:

the register values, words per value

Raises:
  • TypeError – for a value that is not a number, or a float for an integer type

  • ValueError – for a value out of the range of the type

parse(text: str) → int | float[source]

A value from a text: an int in any Python notation (42, 0x2a, 0b101010…), a float for a float type.

Raises:

ValueError – for a text that is not a value of the type

text(value: int | float) → str[source]

A value as text, the shortest one that gives back the same value of the type.

A FLOAT32 read as 3.140000104904175 is “3.14”; an integral float keeps its float look (“10.0”).

bits(value: int | float) → int[source]

The bits of a value (its bytes in the ABCD order) as an unsigned int: 0x4048F5C3 for the FLOAT32 3.14.

hex(value: int | float) → str[source]

The bits of a value in hexadecimal: “0x4048F5C3” for the FLOAT32 3.14.

class pyModbusTCP.codec.DataType(*values)[source]

The type of a value on registers (the value of a member is its name in the command line tools).

UINT16 = 'uint16'

Unsigned 16 bits int, 1 register.

INT16 = 'int16'

Signed 16 bits int (2’s complement), 1 register.

UINT32 = 'uint32'

Unsigned 32 bits int, 2 registers.

INT32 = 'int32'

Signed 32 bits int (2’s complement), 2 registers.

FLOAT32 = 'float32'

IEEE 754 single precision float, 2 registers.

UINT64 = 'uint64'

Unsigned 64 bits int, 4 registers.

INT64 = 'int64'

Signed 64 bits int (2’s complement), 4 registers.

FLOAT64 = 'float64'

IEEE 754 double precision float, 4 registers.

property words: int

The number of registers of a value: 1, 2 or 4.

property is_float: bool

True for FLOAT32 and FLOAT64.

pyModbusTCP.codec.Number = int | float

A value of a data type: an int, or a float for FLOAT32 and FLOAT64.