User Data¶

The handling of user data is not specified by the Modbus protocol. In principle, any sequence of bytes can be sent as payload. In order to support a variety of use cases, there exist two building blocks for user data:

Class (DataType) and derived classes implement the actual storage layout of the payload, including the translation from and to byte sequences.
Class Payload and classes derived from it wrap a DataType to provide a generic interface to store metadata and to perform scaling.

The various payload types are described in chapter Payload Types. For more information on data types, refer to chapter Data Types.

Payload Types¶

Payload Base¶

class modbusclient.payload.Payload(dtype, address, mode='r', reader=None, writer=None, **kwargs)[source]¶

Payload parser

Small wrapper around parser objects to simplify payload definition. The actual parser is passed as argument dtype and has to provide

a method encode to encode python objects to bytes
a method decode to convert bytes to python objects
a __len__ implementation returning the number of bytes required in the encoded string.

For examples of compatible parser implementations refer to the data_types module.

Parameters:	dtype (object) – Datatype object capable of converting from python object to bytes and back. Must provide methods `encode` and `decode`. address (int) – Starting address (register number) of the message mode (str) – Permissible read write modes. Defaults to read only (`'r'`) *kwargs (dict*) – Additional properties added verbatim to this instance.

__eq__(other)[source]¶

Equality comparison

Two messages are considered equal, if and only if their addresses match.

Parameters:	other (`Payload`) – Payload to compare to
Returns:	`True` if and only if the addresses of both messages are equal.
Return type:	bool

__hash__()[source]¶

Get hash of this Message

Returns:	equivalent of `hash(self.address)`
Return type:	str

__len__()[source]¶

Get length of this message in bytes

Returns:	Number of bytes required by this message
Return type:	int

__ne__(other)[source]¶

Inequality comparison

Parameters:	other (`Payload`) – Payload to compare to
Returns:	`False` if and only if the addresses of both messages are equal.
Return type:	bool

__str__()[source]¶: Return str(self).

address¶

Get address (numeric ID) of this message

Returns:	(starting) address of this message
Return type:	int

decode(buffer)[source]¶

Convert bytes from binary modbus representation into variable

Parameters:	buffer (bytes) – Data in packed binary format
Returns:	Python representation of the data
Return type:	object

encode(value)[source]¶

Convert a value to binary modbus representation

Parameters:	value (object) – Python variable to encode
Returns:	Packed binary version of :value:
Return type:	bytes

is_writable¶: Check if this message is writable

is_write_protected¶

Check if message requires Grid guard code to be written

Returns:	True if and only if this message is writable with special permissions only.
Return type:	bool

reader¶

Get function code used to read this value from device

Returns:	Function code used to read this value from device. `None` if value cannot be read.
Return type:	int

register_count¶

Get number of registers used by this parser

Returns:	Number of 2-byte registers used by this parser
Return type:	int

writer¶

Get function code used to write this value to device

Returns:	Function code used to write this value to a device. `None` if value cannot be written.
Return type:	int

Fixpoint Floating Point¶

class modbusclient.Fixpoint(dtype, address, mode='r', digits=0, **kwargs)[source]¶

Bases: modbusclient.payload.Payload

Specialisation of :class:´Payload` for fixed point floats

Parameters:	() (dtype) –

__eq__(other)¶

Equality comparison

Two messages are considered equal, if and only if their addresses match.

Parameters:	other (`Payload`) – Payload to compare to
Returns:	`True` if and only if the addresses of both messages are equal.
Return type:	bool

__hash__()¶

Get hash of this Message

Returns:	equivalent of `hash(self.address)`
Return type:	str

__len__()¶

Get length of this message in bytes

Returns:	Number of bytes required by this message
Return type:	int

__ne__(other)¶

Inequality comparison

Parameters:	other (`Payload`) – Payload to compare to
Returns:	`False` if and only if the addresses of both messages are equal.
Return type:	bool

__str__()¶: Return str(self).

address¶

Get address (numeric ID) of this message

Returns:	(starting) address of this message
Return type:	int

decode(bytes)[source]¶

Convert bytes from binary modbus representation into variable

Parameters:	buffer (bytes) – Data in packed binary format
Returns:	Python representation of the data
Return type:	object

encode(value)[source]¶

Convert a value to binary modbus representation

Parameters:	value (object) – Python variable to encode
Returns:	Packed binary version of :value:
Return type:	bytes

is_writable¶: Check if this message is writable

is_write_protected¶

Check if message requires Grid guard code to be written

Returns:	True if and only if this message is writable with special permissions only.
Return type:	bool

reader¶

Get function code used to read this value from device

Returns:	Function code used to read this value from device. `None` if value cannot be read.
Return type:	int

register_count¶

Get number of registers used by this parser

Returns:	Number of 2-byte registers used by this parser
Return type:	int

writer¶

Get function code used to write this value to device

Returns:	Function code used to write this value to a device. `None` if value cannot be written.
Return type:	int

Enumeration Type¶

class modbusclient.Enum(dtype, address, choices={}, mode='r', **kwargs)[source]¶

Bases: modbusclient.payload.Payload

Specialisation for enumeration messages

Accepts an additional dictionary as argument, which relates the keys to a string describing the meaning.

Parameters:	choices (dict) – Dictionary mapping enum values to values

__eq__(other)¶

Equality comparison

Two messages are considered equal, if and only if their addresses match.

Parameters:	other (`Payload`) – Payload to compare to
Returns:	`True` if and only if the addresses of both messages are equal.
Return type:	bool

__hash__()¶

Get hash of this Message

Returns:	equivalent of `hash(self.address)`
Return type:	str

__len__()¶

Get length of this message in bytes

Returns:	Number of bytes required by this message
Return type:	int

__ne__(other)¶

Inequality comparison

Parameters:	other (`Payload`) – Payload to compare to
Returns:	`False` if and only if the addresses of both messages are equal.
Return type:	bool

__str__()¶: Return str(self).

address¶

Get address (numeric ID) of this message

Returns:	(starting) address of this message
Return type:	int

decode(buffer)¶

Convert bytes from binary modbus representation into variable

Parameters:	buffer (bytes) – Data in packed binary format
Returns:	Python representation of the data
Return type:	object

encode(value)¶

Convert a value to binary modbus representation

Parameters:	value (object) – Python variable to encode
Returns:	Packed binary version of :value:
Return type:	bytes

is_writable¶: Check if this message is writable

is_write_protected¶

Check if message requires Grid guard code to be written

Returns:	True if and only if this message is writable with special permissions only.
Return type:	bool

reader¶

Get function code used to read this value from device

Returns:	Function code used to read this value from device. `None` if value cannot be read.
Return type:	int

register_count¶

Get number of registers used by this parser

Returns:	Number of 2-byte registers used by this parser
Return type:	int

writer¶

Get function code used to write this value to device

Returns:	Function code used to write this value to a device. `None` if value cannot be written.
Return type:	int

Data Types¶

This implementation provides several basic datatypes, which can be wrapped in a Payload object.

Base Class for Data Types¶

The data type class is a base class for datatypes, which provides an interface compatible with ``

class modbusclient.data_types.DataType(format, nan=None, swap_words=False)[source]¶

Bases: object

Base class for data type objects

Base class for objects to be used as parser in combination with Payload objects. This base wraps a Struct parser for the conversion between python objects and binary strings.

Parameters:

format (str) – Format definition as used by Struct. If
leading exclamation mark (the) –
byte order marks have to be specified explicitly. (Other) –
nan (object) – NAN value to use for this object.
swap_words (bool) – Swap registers (DWORDS) before conversion. This may
necessary depending on the memory layout used by the application, (be) –
MODBUS does not define, how multi-word data types are distributed (since) –
various registers. Defaults to False. (over) –

__delattr__¶: Implement delattr(self, name).

__dir__() → list¶: default dir() implementation

__eq__¶: Return self==value.

__format__()¶: default object formatter

__ge__¶: Return self>=value.

__getattribute__¶: Return getattr(self, name).

__gt__¶: Return self>value.

__hash__¶: Return hash(self).

__init__(format, nan=None, swap_words=False)[source]¶: Initialize self. See help(type(self)) for accurate signature.

__init_subclass__()¶

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__¶: Return self<=value.

__len__()[source]¶

Get length of this message in bytes

Returns:	Number of bytes required by this message
Return type:	int

__lt__¶: Return self<value.

__ne__¶: Return self!=value.

__new__()¶: Create and return a new object. See help(type) for accurate signature.

__reduce__()¶: helper for pickle

__reduce_ex__()¶: helper for pickle

__repr__¶: Return repr(self).

__setattr__¶: Implement setattr(self, name, value).

__sizeof__() → int¶: size of object in memory, in bytes

__str__¶: Return str(self).

__subclasshook__()¶

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__¶: list of weak references to the object (if defined)

Numeric Types¶

An data type intended for atomic numeric types such as integers or floats of varying precision.

class modbusclient.data_types.AtomicType(format, nan=None, swap_words=False)[source]¶

A wrapper for Atomic datatypes which maps NaN to None

Identical to DataType, except that NaN will be mapped to None when parsing bytes.

String Types¶

class modbusclient.data_types.String(len, encoding='utf8', swap_words=False)[source]¶

Parser for strings with configurable encoding

Parameters:	len (int) – Length of the string in bytes encoding (str) – Encoding. Defaults to ‘utf8’ swap_words (bool) – Defaults to `False`

Helper Functions¶

The following two functions may come in handy, when you have to create your own data type for Binary Coded Decimal types.

modbusclient.data_types.bcd_decode(byte)[source]¶

Decode BCD encoded byte into number

Parameters:	byte (int) – A single byte
Returns:	Number as integer
Return type:	int

modbusclient.data_types.bcd_decode(byte)[source]

Decode BCD encoded byte into number

Parameters:	byte (int) – A single byte
Returns:	Number as integer
Return type:	int

modbusclient.data_types.swap_words(arr)[source]¶

Swap 16-bit words of an array

Parameters:	arr (bytes) – bytes
Returns:	Bytes with pairwise swap of 16-bit words
Return type:	bytes