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:
|
the first register holds the most significant word (default) |
|
the first register holds the least significant word (common on PLCs) |
|
the bytes of each register are swapped |
|
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:
ABCDandBIG_ENDIANare 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
Codecof 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.
- 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,
wordsper 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”).
- 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
FLOAT32andFLOAT64.