Bit Contents
----------------------------------
0   Not Used
2   Not Used
3   Not Used
4   Character Overrun
5   Currently in Listen Only Mode
6   Broadcast Receive
class pymodbus.events.RemoteSendEvent(read=False, slave_abort=False, slave_busy=False, slave_nak=False, write_timeout=False, listen=False)
Bases: ModbusEvent
Remote device MODBUS Send Event.
The remote device stores this type of event byte when it finishes
processing a request message. It is stored if the remote device
returned a normal or exception response, or no response.
This event is defined by bit 7 set to a logic “0”, with bit 6 set to a “1”.
The other bits will be set to a logic “1” if the corresponding
condition is TRUE. The bit layout is:
Bit Contents
-----------------------------------------------------------
0   Read Exception Sent (Exception Codes 1-3)
1   Slave Abort Exception Sent (Exception Code 4)
2   Slave Busy Exception Sent (Exception Codes 5-6)
3   Slave Program NAK Exception Sent (Exception Code 7)
4   Write Timeout Error Occurred
5   Currently in Listen Only Mode
exception pymodbus.exceptions.ConnectionException(string='')
Bases: ModbusException
Error resulting from a bad connection.
exception pymodbus.exceptions.InvalidMessageReceivedException(string='')
Bases: ModbusException
Error resulting from invalid response received or decoded.
exception pymodbus.exceptions.MessageRegisterException(string='')
Bases: ModbusException
Error resulting from failing to register a custom message request/response.
exception pymodbus.exceptions.ModbusIOException(string='', function_code=None)
Bases: ModbusException
Error resulting from data i/o.
exception pymodbus.exceptions.NoSuchSlaveException(string='')
Bases: ModbusException
Error resulting from making a request to a slave that does not exist.
exception pymodbus.exceptions.NotImplementedException(string='')
Bases: ModbusException
Error resulting from not implemented function.
exception pymodbus.exceptions.ParameterException(string='')
Bases: ModbusException
Error resulting from invalid parameter.
Modbus Request/Response Decoder Factories.
The following factories make it easy to decode request/response messages.
To add a new request/response pair to be decodeable by the library, simply
add them to the respective function lookup table (order doesn’t matter, but
it does help keep things organized).
Regardless of how many functions are added to the lookup, O(1) behavior is
kept as a result of a pre-computed lookup dictionary.
class pymodbus.factory.ClientDecoder
Bases: object
Response Message Factory (Client).
To add more implemented functions, simply add them to the list
decode(message)
Decode a response packet.
Parameters:
message – The raw packet to decode
Returns:
The decoded modbus message or None if error
function_table = [<class 'pymodbus.pdu.register_read_message.ReadHoldingRegistersResponse'>, <class 'pymodbus.pdu.bit_read_message.ReadDiscreteInputsResponse'>, <class 'pymodbus.pdu.register_read_message.ReadInputRegistersResponse'>, <class 'pymodbus.pdu.bit_read_message.ReadCoilsResponse'>, <class 'pymodbus.pdu.bit_write_message.WriteMultipleCoilsResponse'>, <class 'pymodbus.pdu.register_write_message.WriteMultipleRegistersResponse'>, <class 'pymodbus.pdu.register_write_message.WriteSingleRegisterResponse'>, <class 'pymodbus.pdu.bit_write_message.WriteSingleCoilResponse'>, <class 'pymodbus.pdu.register_read_message.ReadWriteMultipleRegistersResponse'>, <class 'pymodbus.pdu.diag_message.DiagnosticStatusResponse'>, <class 'pymodbus.pdu.other_message.ReadExceptionStatusResponse'>, <class 'pymodbus.pdu.other_message.GetCommEventCounterResponse'>, <class 'pymodbus.pdu.other_message.GetCommEventLogResponse'>, <class 'pymodbus.pdu.other_message.ReportSlaveIdResponse'>, <class 'pymodbus.pdu.file_message.ReadFileRecordResponse'>, <class 'pymodbus.pdu.file_message.WriteFileRecordResponse'>, <class 'pymodbus.pdu.register_write_message.MaskWriteRegisterResponse'>, <class 'pymodbus.pdu.file_message.ReadFifoQueueResponse'>, <class 'pymodbus.pdu.mei_message.ReadDeviceInformationResponse'>]
Bases: object




    

Request Message Factory (Server).
To add more implemented functions, simply add them to the list
decode(message)
Decode a request packet.
Parameters:
message – The raw modbus request packet
Returns:
The decoded modbus message or None if error
Modbus Payload Builders.
A collection of utilities for building and decoding
modbus messages payloads.
class pymodbus.payload.BinaryPayloadBuilder(payload=None, byteorder=Endian.LITTLE, wordorder=Endian.BIG, repack=False)
Bases: object
A utility that helps build payload messages to be written with the various modbus messages.
It really is just a simple wrapper around the struct module,
however it saves time looking up the format strings.
What follows is a simple example:
builder = BinaryPayloadBuilder(byteorder=Endian.Little)
builder.add_8bit_uint(1)
builder.add_16bit_uint(2)
payload = builder.build()
add_bits(values: list[bool]) → None
Add a collection of bits to be encoded.
If these are less than a multiple of eight,
they will be left padded with 0 bits to make
it so.
Parameters:
values – The value to add to the buffer
build() → list[bytes]
Return the payload buffer as a list.
This list is two bytes per element and can
thus be treated as a list of registers.
Returns:
The payload buffer as a list
to_coils() → list[bool]
Convert the payload buffer into a coil layout that can be used as a context block.
Returns:
The coil layout to use as a block
to_registers()
Convert the payload buffer to register layout that can be used as a context block.
Returns:
The register layout to use as a block
class pymodbus.payload.BinaryPayloadDecoder(payload, byteorder=Endian.LITTLE, wordorder=Endian.BIG)
Bases: object
A utility that helps decode payload messages from a modbus response message.
It really is just a simple wrapper around
the struct module, however it saves time looking up the format
strings. What follows is a simple example:
decoder = BinaryPayloadDecoder(payload)
first   = decoder.decode_8bit_uint()
second  = decoder.decode_16bit_uint()
classmethod fromRegisters(registers, byteorder=Endian.LITTLE, wordorder=Endian.BIG)
Initialize a payload decoder.
With the result of reading a collection of registers from a modbus device.
The registers are treated as a list of 2 byte values.
We have to do this because of how the data has already
been decoded by the rest of the library.
Parameters:
registers – The register results to initialize with
byteorder – The Byte order of each word
wordorder – The endianness of the word (when wordcount is >= 2)
Returns:
An initialized PayloadDecoder
Raises:
ParameterException – 
class pymodbus.transaction.ModbusTransactionManager
Bases: object
Implement a transaction for a manager.
Results are keyed based on the supplied transaction id.
addTransaction(request: ModbusPDU)
Add a transaction to the handler.
This holds the request in case it needs to be resent.
After being sent, the request is removed.
Parameters:
request – The request to hold on to
getNextTID() → int
Retrieve the next unique transaction identifier.
This handles incrementing the identifier after
retrieval
Returns:
The next unique transaction identifier
getTransaction(tid: int)
Return a transaction matching the referenced tid.
If the transaction does not exist, None is returned
Parameters:
tid – The transaction to retrieve
class pymodbus.transaction.SyncModbusTransactionManager(client: ModbusBaseSyncClient, retries)
Bases: ModbusTransactionManager
Implement a transaction for a manager.
The transaction protocol can be represented by the following pseudo code:
count = 0
  result = send(message)
  if (timeout or result == bad)
     count++
  else break
while (count < 3)
This module helps to abstract this away from the framer and protocol.
Results are keyed based on the supplied transaction id.
execute(request: ModbusPDU)
Start the producer to send the next request to consumer.write(Frame(request)).
Modbus Utilities.
A collection of utilities for packing data, unpacking
data computing checksums, and decode checksums.
pymodbus.utilities.default(value)
Return the default value of object.
Parameters:
value – The value to get the default of
Returns:
The default value
pymodbus.utilities.pack_bitstring(bits: list[bool]) → bytes
Create a bytestring out of a list of bits.
Parameters:
bits – A list of bits
example:
bits   = [False, True, False, True]
result = pack_bitstring(bits)
pymodbus.utilities.unpack_bitstring(data: bytes) → list[bool]
Create bit list out of a bytestring.




    

Parameters:
data – The modbus data packet to decode
example:
bytes  = "bytes to decode"
result = unpack_bitstring(bytes)
class pymodbus.pdu.bit_read_message.ReadBitsRequestBase(address, count, slave, transaction, skip_encode)
Bases: ModbusRequest
Base class for Messages Requesting bit values.
decode(data)
Decode a request pdu.
Parameters:
data – The packet data to decode
get_response_pdu_size()
Get response pdu size.
Func_code (1 byte) + Byte Count(1 byte) + Quantity of Coils (n Bytes)/8,
if the remainder is different of 0 then N = N+1
:return:
class pymodbus.pdu.bit_read_message.ReadBitsResponseBase(values, slave, transaction, skip_encode)
Bases: ModbusResponse
Base class for Messages responding to bit-reading values.
The requested bits can be found in the .bits list.
bits
A list of booleans representing bit values
class pymodbus.pdu.bit_read_message.ReadCoilsRequest(address=None, count=None, slave=1, transaction=0, skip_encode=False)
Bases: ReadBitsRequestBase
This function code is used to read from 1 to 2000(0x7d0) contiguous status of coils in a remote device.
The Request PDU specifies the starting
address, ie the address of the first coil specified, and the number of
coils. In the PDU Coils are addressed starting at zero. Therefore coils
numbered 1-16 are addressed as 0-15.
async execute(context)
Run a read coils request against a datastore.
Before running the request, we make sure that the request is in
the max valid range (0x001-0x7d0). Next we make sure that the
request is valid against the current datastore.
Parameters:
context – The datastore to request from
Returns:
An initialized ReadCoilsResponse, or an ExceptionResponse if an error occurred
class pymodbus.pdu.bit_read_message.ReadCoilsResponse(values=None, slave=1, transaction=0, skip_encode=False)
Bases: ReadBitsResponseBase
The coils in the response message are packed as one coil per bit of the data field.
Status is indicated as 1= ON and 0= OFF. The LSB of the
first data byte contains the output addressed in the query. The other
coils follow toward the high order end of this byte, and from low order
to high order in subsequent bytes.
If the returned output quantity is not a multiple of eight, the
remaining bits in the final data byte will be padded with zeros
(toward the high order end of the byte). The Byte Count field specifies
the quantity of complete bytes of data.
The requested coils can be found in boolean form in the .bits list.
function_code = 1
class pymodbus.pdu.bit_read_message.ReadDiscreteInputsRequest(address=None, count=None, slave=1, transaction=0, skip_encode=False)
Bases: ReadBitsRequestBase
This function code is used to read from 1 to 2000(0x7d0).
Contiguous status of discrete inputs in a remote device. The Request PDU specifies the
starting address, ie the address of the first input specified, and the
number of inputs. In the PDU Discrete Inputs are addressed starting at
zero. Therefore Discrete inputs numbered 1-16 are addressed as 0-15.
async execute(context)
Run a read discrete input request against a datastore.
Before running the request, we make sure that the request is in
the max valid range (0x001-0x7d0). Next we make sure that the
request is valid against the current datastore.
Parameters:
context – The datastore to request from
Returns:
An initialized ReadDiscreteInputsResponse, or an ExceptionResponse if an error occurred
class pymodbus.pdu.bit_read_message.ReadDiscreteInputsResponse(values=None, slave=1, transaction=0, skip_encode=False)
Bases: ReadBitsResponseBase
The discrete inputs in the response message are packed as one input per bit of the data field.
Status is indicated as 1= ON; 0= OFF. The LSB of
the first data byte contains the input addressed in the query. The other
inputs follow toward the high order end of this byte, and from low order
to high order in subsequent bytes.
If the returned input quantity is not a multiple of eight, the
remaining bits in the final data byte will be padded with zeros
(toward the high order end of the byte). The Byte Count field specifies
the quantity of complete bytes of data.
The requested coils can be found in boolean form in the .bits list.
function_code = 2
class pymodbus.pdu.bit_write_message.WriteMultipleCoilsRequest(address=None, values=None, slave=None, transaction=0, skip_encode=0)
Bases: ModbusRequest
This function code is used to forcea sequence of coils.
To either ON or OFF in a remote device. The Request PDU specifies the coil
references to be forced. Coils are addressed starting at zero. Therefore
coil numbered 1 is addressed as 0.
The requested ON/OFF states are specified by contents of the request
data field. A logical “1” in a bit position of the field requests the
corresponding output to be ON. A logical “0” requests it to be OFF.”
decode(data)
Decode a write coils request.




    

Parameters:
data – The packet data to decode
get_response_pdu_size()
Get response pdu size.
Func_code (1 byte) + Output Address (2 byte) + Quantity of Outputs  (2 Bytes)
:return:
class pymodbus.pdu.bit_write_message.WriteMultipleCoilsResponse(address=None, count=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
The normal response returns the function code.
Starting address, and quantity of coils forced.
decode(data)
Decode a write coils response.
Parameters:
data – The packet data to decode
class pymodbus.pdu.bit_write_message.WriteSingleCoilRequest(address=None, value=None, slave=None, transaction=0, skip_encode=0)
Bases: ModbusRequest
This function code is used to write a single output to either ON or OFF in a remote device.
The requested ON/OFF state is specified by a constant in the request
data field. A value of FF 00 hex requests the output to be ON. A value
of 00 00 requests it to be OFF. All other values are illegal and will
not affect the output.
The Request PDU specifies the address of the coil to be forced. Coils
are addressed starting at zero. Therefore coil numbered 1 is addressed
as 0. The requested ON/OFF state is specified by a constant in the Coil
Value field. A value of 0XFF00 requests the coil to be ON. A value of
0X0000 requests the coil to be off. All other values are illegal and
will not affect the coil.
decode(data)
Decode a write coil request.
Parameters:
data – The packet data to decode
get_response_pdu_size()
Get response pdu size.
Func_code (1 byte) + Output Address (2 byte) + Output Value  (2 Bytes)
:return:
class pymodbus.pdu.bit_write_message.WriteSingleCoilResponse(address=None, value=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
The normal response is an echo of the request.
Returned after the coil state has been written.
decode(data)
Decode a write coil response.
Parameters:
data – The packet data to decode
Diagnostic Record Read/Write.
These need to be tied into a the current server context
or linked to the appropriate data
class pymodbus.pdu.diag_message.ChangeAsciiInputDelimiterRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Change ascii input delimiter.
The character “CHAR” passed in the request data field becomes the end of
message delimiter for future messages (replacing the default LF
character). This function is useful in cases of a Line Feed is not
required at the end of ASCII messages.
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ChangeAsciiInputDelimiterResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Change ascii input delimiter.
The character “CHAR” passed in the request data field becomes the end of
message delimiter for future messages (replacing the default LF
character). This function is useful in cases of a Line Feed is not
required at the end of ASCII messages.
sub_function_code = 3
class pymodbus.pdu.diag_message.ClearCountersRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Clear ll counters and the diagnostic register.
Also, counters are cleared upon power-up
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ClearCountersResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Clear ll counters and the diagnostic register.
Also, counters are cleared upon power-up
sub_function_code = 10
class pymodbus.pdu.diag_message.ClearOverrunCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest




    

Clear the overrun error counter and reset the error flag.
An error flag should be cleared, but nothing else in the
specification mentions is, so it is ignored.
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ClearOverrunCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Clear the overrun error counter and reset the error flag.
sub_function_code = 20
class pymodbus.pdu.diag_message.DiagnosticStatusRequest(slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
This is a base class for all of the diagnostic request functions.
decode(data)
Decode a diagnostic request.
Parameters:
data – The data to decode into the function code
get_response_pdu_size()
Get response pdu size.
Func_code (1 byte) + Sub function code (2 byte) + Data (2 * N bytes)
:return:
class pymodbus.pdu.diag_message.DiagnosticStatusResponse(slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Diagnostic status.
This is a base class for all of the diagnostic response functions
It works by performing all of the encoding and decoding of variable
data and lets the higher classes define what extra data to append
and how to execute a request
decode(data)
Decode diagnostic response.
Parameters:
data – The data to decode into the function code
class pymodbus.pdu.diag_message.DiagnosticStatusSimpleRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusRequest
Return diagnostic status.
A large majority of the diagnostic functions are simple
status request functions.  They work by sending 0x0000
as data and their function code and they are returned
2 bytes of data.
If a function inherits this, they only need to implement
the execute method
async execute(*args)
Raise if not implemented.
class pymodbus.pdu.diag_message.DiagnosticStatusSimpleResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusResponse
Diagnostic status.
A large majority of the diagnostic functions are simple
status request functions.  They work by sending 0x0000
as data and their function code and they are returned
2 bytes of data.
class pymodbus.pdu.diag_message.ForceListenOnlyModeRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Forces the addressed remote device to its Listen Only Mode for MODBUS communications.
This isolates it from the other devices on the network,
allowing them to continue communicating without interruption from the
addressed remote device. No response is returned.
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ForceListenOnlyModeResponse(slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusResponse
Forces the addressed remote device to its Listen Only Mode for MODBUS communications.
This isolates it from the other devices on the network,
allowing them to continue communicating without interruption from the
addressed remote device. No response is returned.
This does not send a response
should_respond = False
class pymodbus.pdu.diag_message.GetClearModbusPlusRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Get/Clear modbus plus request.
In addition to the Function code (08) and Subfunction code
(00 15 hex) in the query, a two-byte Operation field is used
to specify either a “Get Statistics” or a “Clear Statistics”
operation.  The two operations are exclusive - the “Get”
operation cannot clear the statistics, and the “Clear”
operation does not return statistics prior to clearing
them. Statistics are also cleared on power-up of the slave
device.
encode()
Encode a diagnostic response.
we encode the data set in self.message
Returns:
The encoded packet
get_response_pdu_size()
Return a series of 54 16-bit words (108 bytes) in the data field of the response.
This function differs from the usual two-byte length of the data field.
The data contains the statistics for the Modbus Plus peer processor in the slave device.
Func_code (1 byte) + Sub function code (2 byte) + Operation (2 byte) + Data (108 bytes)
:return:




    

class pymodbus.pdu.diag_message.GetClearModbusPlusResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return a series of 54 16-bit words (108 bytes) in the data field of the response.
This function differs from the usual two-byte length of the data field.
The data contains the statistics for the Modbus Plus peer processor in the slave device.
sub_function_code = 21
class pymodbus.pdu.diag_message.RestartCommunicationsOptionRequest(toggle=False, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusRequest
Restart communication.
The remote device serial line port must be initialized and restarted, and
all of its communications event counters are cleared. If the port is
currently in Listen Only Mode, no response is returned. This function is
the only one that brings the port out of Listen Only Mode. If the port is
not currently in Listen Only Mode, a normal response is returned. This
occurs before the restart is executed.
async execute(*_args)
Clear event log and restart.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.RestartCommunicationsOptionResponse(toggle=False, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusResponse
Restart Communication.
The remote device serial line port must be initialized and restarted, and
all of its communications event counters are cleared. If the port is
currently in Listen Only Mode, no response is returned. This function is
the only one that brings the port out of Listen Only Mode. If the port is
not currently in Listen Only Mode, a normal response is returned. This
occurs before the restart is executed.
sub_function_code = 1
class pymodbus.pdu.diag_message.ReturnBusCommunicationErrorCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return bus comm. count.
The response data field returns the quantity of CRC errors encountered
by the remote device since its last restart, clear counter operation, or
power-up
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnBusCommunicationErrorCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return bus comm. error.
The response data field returns the quantity of CRC errors encountered
by the remote device since its last restart, clear counter operation, or
power-up
sub_function_code = 12
class pymodbus.pdu.diag_message.ReturnBusExceptionErrorCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return bus exception.
The response data field returns the quantity of modbus exception
responses returned by the remote device since its last restart,
clear counters operation, or power-up
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnBusExceptionErrorCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return bus exception.
The response data field returns the quantity of modbus exception
responses returned by the remote device since its last restart,
clear counters operation, or power-up
sub_function_code = 13
class pymodbus.pdu.diag_message.ReturnBusMessageCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return bus message count.
The response data field returns the quantity of messages that the
remote device has detected on the communications systems since its last
restart, clear counters operation, or power-up
async execute(*args)
Execute the diagnostic request on the given device.




    

Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnBusMessageCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return bus message count.
The response data field returns the quantity of messages that the
remote device has detected on the communications systems since its last
restart, clear counters operation, or power-up
sub_function_code = 11
class pymodbus.pdu.diag_message.ReturnDiagnosticRegisterRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
The contents of the remote device’s 16-bit diagnostic register are returned in the response.
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnDiagnosticRegisterResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return diagnostic register.
The contents of the remote device’s 16-bit diagnostic register are
returned in the response
sub_function_code = 2
class pymodbus.pdu.diag_message.ReturnIopOverrunCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return IopOverrun.
An IOP overrun is caused by data characters arriving at the port
faster than they can be stored, or by the loss of a character due
to a hardware malfunction.  This function is specific to the 884.
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnIopOverrunCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return Iop overrun count.
The response data field returns the quantity of messages
addressed to the slave that it could not handle due to an 884
IOP overrun condition, since its last restart, clear counters
operation, or power-up.
sub_function_code = 19
class pymodbus.pdu.diag_message.ReturnQueryDataRequest(message=b'\x00\x00', slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusRequest
Return query data.
The data passed in the request data field is to be returned (looped back)
in the response. The entire response message should be identical to the
request.
async execute(*_args)
Execute the loopback request (builds the response).
Returns:
The populated loopback response message
class pymodbus.pdu.diag_message.ReturnQueryDataResponse(message=b'\x00\x00', slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusResponse
Return query data.
The data passed in the request data field is to be returned (looped back)
in the response. The entire response message should be identical to the
request.
sub_function_code = 0
class pymodbus.pdu.diag_message.ReturnSlaveBusCharacterOverrunCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return slave character overrun.
The response data field returns the quantity of messages addressed to the
remote device that it could not handle due to a character overrun condition,
since its last restart, clear counters operation, or power-up. A character
overrun is caused by data characters arriving at the port faster than they
can be stored, or by the loss of a character due to a hardware malfunction.
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnSlaveBusCharacterOverrunCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse




    

Return the quantity of messages addressed to the remote device unhandled due to a character overrun.
Since its last restart, clear counters operation, or power-up. A character
overrun is caused by data characters arriving at the port faster than they
can be stored, or by the loss of a character due to a hardware malfunction.
sub_function_code = 18
class pymodbus.pdu.diag_message.ReturnSlaveBusyCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return slave busy count.
The response data field returns the quantity of messages addressed to the
remote device for which it returned a Slave Device Busy exception response,
since its last restart, clear counters operation, or power-up.
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnSlaveBusyCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return slave busy count.
The response data field returns the quantity of messages addressed to the
remote device for which it returned a Slave Device Busy exception response,
since its last restart, clear counters operation, or power-up.
sub_function_code = 17
class pymodbus.pdu.diag_message.ReturnSlaveMessageCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return slave message count.
The response data field returns the quantity of messages addressed to the
remote device, or broadcast, that the remote device has processed since
its last restart, clear counters operation, or power-up
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnSlaveMessageCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return slave message count.
The response data field returns the quantity of messages addressed to the
remote device, or broadcast, that the remote device has processed since
its last restart, clear counters operation, or power-up
sub_function_code = 14
class pymodbus.pdu.diag_message.ReturnSlaveNAKCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return slave NAK count.
The response data field returns the quantity of messages addressed to the
remote device for which it returned a Negative Acknowledge (NAK) exception
response, since its last restart, clear counters operation, or power-up.
Exception responses are described and listed in section 7 .
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnSlaveNAKCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse
Return slave NAK.
The response data field returns the quantity of messages addressed to the
remote device for which it returned a Negative Acknowledge (NAK) exception
response, since its last restart, clear counters operation, or power-up.
Exception responses are described and listed in section 7.
sub_function_code = 16
class pymodbus.pdu.diag_message.ReturnSlaveNoResponseCountRequest(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleRequest
Return slave no response.
The response data field returns the quantity of messages addressed to the
remote device, or broadcast, that the remote device has processed since
its last restart, clear counters operation, or power-up
async execute(*args)
Execute the diagnostic request on the given device.
Returns:
The initialized response message
class pymodbus.pdu.diag_message.ReturnSlaveNoResponseCountResponse(data=0, slave=1, transaction=0, skip_encode=False)
Bases: DiagnosticStatusSimpleResponse




    

Return slave no response.
The response data field returns the quantity of messages addressed to the
remote device, or broadcast, that the remote device has processed since
its last restart, clear counters operation, or power-up
sub_function_code = 15
class pymodbus.pdu.file_message.FileRecord(reference_type=6, file_number=0, record_number=0, record_data='', record_length=None, response_length=None)
Bases: object
Represents a file record and its relevant data.
class pymodbus.pdu.file_message.ReadFifoQueueRequest(address=0, slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
Read fifo queue request.
This function code allows to read the contents of a First-In-First-Out
(FIFO) queue of register in a remote device. The function returns a
count of the registers in the queue, followed by the queued data.
Up to 32 registers can be read: the count, plus up to 31 queued data
registers.
The queue count register is returned first, followed by the queued data
registers.  The function reads the queue contents, but does not clear
them.
decode(data)
Decode the incoming request.
Parameters:
data – The data to decode into the address
class pymodbus.pdu.file_message.ReadFifoQueueResponse(values=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Read Fifo queue response.
In a normal response, the byte count shows the quantity of bytes to
follow, including the queue count bytes and value register bytes
(but not including the error check field).  The queue count is the
quantity of data registers in the queue (not including the count register).
If the queue count exceeds 31, an exception response is returned with an
error code of 03 (Illegal Data Value).
classmethod calculateRtuFrameSize(buffer)
Calculate the size of the message.
Parameters:
buffer – A buffer containing the data that have been received.
Returns:
The number of bytes in the response.
class pymodbus.pdu.file_message.ReadFileRecordRequest(records=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
Read file record request.
This function code is used to perform a file record read. All request
data lengths are provided in terms of number of bytes and all record
lengths are provided in terms of registers.
A file is an organization of records. Each file contains 10000 records,
addressed 0000 to 9999 decimal or 0x0000 to 0x270f. For example, record
12 is addressed as 12. The function can read multiple groups of
references. The groups can be separating (non-contiguous), but the
references within each group must be sequential. Each group is defined
in a separate “sub-request” field that contains seven bytes:
The reference type: 1 byte (must be 0x06)
The file number: 2 bytes
The starting record number within the file: 2 bytes
The length of the record to be read: 2 bytes
The quantity of registers to be read, combined with all other fields
in the expected response, must not exceed the allowable length of the
MODBUS PDU: 235 bytes.
decode(data)
Decode the incoming request.
Parameters:
data – The data to decode into the address
class pymodbus.pdu.file_message.ReadFileRecordResponse(records=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Read file record response.
The normal response is a series of “sub-responses,” one for each
“sub-request.” The byte count field is the total combined count of
bytes in all “sub-responses.” In addition, each “sub-response”
contains a field that shows its own byte count.
decode(data)
Decode the response.
Parameters:
data – The packet data to decode
class pymodbus.pdu.file_message.WriteFileRecordRequest(records=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
Write file record request.
This function code is used to perform a file record write. All
request data lengths are provided in terms of number of bytes
and all record lengths are provided in terms of the number of 16
bit words.
decode(data)
Decode the incoming request.
Parameters:
data – The data to decode into the address
class pymodbus.pdu.file_message.WriteFileRecordResponse(records=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
The normal response is an echo of the request.
decode(data)
Decode the incoming request.
Parameters:
data – The data to decode into the address
class pymodbus.pdu.mei_message.ReadDeviceInformationRequest(read_code=None, object_id=0, slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest




    

Read device information.
This function code allows reading the identification and additional
information relative to the physical and functional description of a
remote device, only.
The Read Device Identification interface is modeled as an address space
composed of a set of addressable data elements. The data elements are
called objects and an object Id identifies them.
decode(data)
Decode data part of the message.
Parameters:
data – The incoming data
class pymodbus.pdu.mei_message.ReadDeviceInformationResponse(read_code=None, information=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Read device information response.
classmethod calculateRtuFrameSize(buffer)
Calculate the size of the message.
Parameters:
buffer – A buffer containing the data that have been received.
Returns:
The number of bytes in the response.
class pymodbus.pdu.other_message.GetCommEventCounterRequest(slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
This function code is used to get a status word.
And an event count from the remote device’s communication event counter.
By fetching the current count before and after a series of messages, a
client can determine whether the messages were handled normally by the
remote device.
The device’s event counter is incremented once  for each successful
message completion. It is not incremented for exception responses,
poll commands, or fetch event counter commands.
The event counter can be reset by means of the Diagnostics function
(code 08), with a subfunction of Restart Communications Option
(code 00 01) or Clear Counters and Diagnostic Register (code 00 0A).
decode(data)
Decode data part of the message.
Parameters:
data – The incoming data
async execute(_context=None)
Run a read exception status request against the store.
Returns:
The populated response
class pymodbus.pdu.other_message.GetCommEventCounterResponse(count=0, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Get comm event counter response.
The normal response contains a two-byte status word, and a two-byte
event count. The status word will be all ones (FF FF hex) if a
previously-issued program command is still being processed by the
remote device (a busy condition exists). Otherwise, the status word
will be all zeros.
decode(data)
Decode a the response.
Parameters:
data – The packet data to decode
class pymodbus.pdu.other_message.GetCommEventLogRequest(slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
This function code is used to get a status word.
Event count, message count, and a field of event bytes from the remote device.
The status word and event counts are identical  to that returned by
the Get Communications Event Counter function (11, 0B hex).
The message counter contains the quantity of  messages processed by the
remote device since its last restart, clear counters operation, or
power-up.  This count is identical to that returned by the Diagnostic
function (code 08), sub-function Return Bus Message Count (code 11,
0B hex).
The event bytes field contains 0-64 bytes, with each byte corresponding
to the status of one MODBUS send or receive operation for the remote
device.  The remote device enters the events into the field in
chronological order.  Byte 0 is the most recent event. Each new byte
flushes the oldest byte from the field.
decode(data)
Decode data part of the message.
Parameters:
data – The incoming data
async execute(_context=None)
Run a read exception status request against the store.
Returns:
The populated response
class pymodbus.pdu.other_message.GetCommEventLogResponse(status=True, message_count=0, event_count=0, events=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Get Comm event log response.
The normal response contains a two-byte status word field,
a two-byte event count field, a two-byte message count field,
and a field containing 0-64 bytes of events. A byte count
field defines the total length of the data in these four field
decode(data)
Decode a the response.
Parameters:
data – The packet data to decode
class pymodbus.pdu.other_message.ReadExceptionStatusRequest(slave=None, transaction=0, skip_encode=0)
Bases: ModbusRequest
This function code is used to read the contents of eight Exception Status outputs in a remote device.
The function provides a simple method for
accessing this information, because the Exception Output references are
known (no output reference is needed in the function).
decode(data)
Decode data part of the message.
Parameters:
data – The incoming data
async execute(_context=None)
Run a read exception status request against the store.
Returns:
The populated response
class pymodbus.pdu.other_message.ReadExceptionStatusResponse(status=0, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse




    

The normal response contains the status of the eight Exception Status outputs.
The outputs are packed into one data byte, with one bit
per output. The status of the lowest output reference is contained
in the least significant bit of the byte.  The contents of the eight
Exception Status outputs are device specific.
decode(data)
Decode a the response.
Parameters:
data – The packet data to decode
class pymodbus.pdu.other_message.ReportSlaveIdRequest(slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
This function code is used to read the description of the type.
The current status, and other information specific to a remote device.
decode(data)
Decode data part of the message.
Parameters:
data – The incoming data
class pymodbus.pdu.other_message.ReportSlaveIdResponse(identifier=b'\x00', status=True, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Show response.
The data contents are specific to each type of device.
decode(data)
Decode a the response.
Since the identifier is device dependent, we just return the
raw value that a user can decode to whatever it should be.
Parameters:
data – The packet data to decode
class pymodbus.pdu.pdu.ExceptionResponse(function_code, exception_code=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Base class for a modbus exception PDU.
ExceptionOffset = 128
class pymodbus.pdu.pdu.IllegalFunctionRequest(function_code, slave, transaction, xskip_encode)
Bases: ModbusRequest
Define the Modbus slave exception type “Illegal Function”.
This exception code is returned if the slave:
- does not implement the function code **or**
- is not in a state that allows it to process the function
class pymodbus.pdu.pdu.ModbusExceptions
Bases: object
An enumeration of the valid modbus exceptions.
Acknowledge = 5
class pymodbus.pdu.pdu.ModbusPDU(slave, transaction, skip_encode)
Bases: object
Base class for all Modbus messages.
transaction_id
This value is used to uniquely identify a request
response pair.  It can be implemented as a simple counter
slave_id
This is used to route the request to the correct child. In
the TCP modbus, it is used for routing (or not used at all. However,
for the serial versions, it is used to specify which child to perform
the requests against. The value 0x00 represents the broadcast address
(also 0xff).
skip_encode
This is used when the message payload has already been encoded.
Generally this will occur when the PayloadBuilder is being used
to create a complicated message. By setting this to True, the
request will pass the currently encoded message through instead
of encoding it again.
class pymodbus.pdu.pdu.ModbusRequest(slave, transaction, skip_encode)
Bases: ModbusPDU
Base class for a modbus request PDU.
doException(exception)
Build an error response based on the function.
Parameters:
exception – The exception to return
Raises:
An exception response
class pymodbus.pdu.pdu.ModbusResponse(slave, transaction, skip_encode)
Bases: ModbusPDU
Base class for a modbus response PDU.
should_respond
A flag that indicates if this response returns a result back
to the client issuing the request
class pymodbus.pdu.register_read_message.ReadHoldingRegistersRequest(address=None, count=None, slave=1, transaction=0, skip_encode=0)
Bases: ReadRegistersRequestBase
Read holding registers.
This function code is used to read the contents of a contiguous block
of holding registers in a remote device. The Request PDU specifies the
starting register address and the number of registers. In the PDU
Registers are addressed starting at zero. Therefore registers numbered
1-16 are addressed as 0-15.
async execute(context)
Run a read holding request against a datastore.
Parameters:
context – The datastore to request from
Returns:
An initialized ReadHoldingRegistersResponse
class pymodbus.pdu.register_read_message.ReadHoldingRegistersResponse(values=None, slave=None, transaction=0, skip_encode=0)
Bases: ReadRegistersResponseBase




    

Read holding registers.
This function code is used to read the contents of a contiguous block
of holding registers in a remote device. The Request PDU specifies the
starting register address and the number of registers. In the PDU
Registers are addressed starting at zero. Therefore registers numbered
1-16 are addressed as 0-15.
The requested registers can be found in the .registers list.
function_code = 3
class pymodbus.pdu.register_read_message.ReadInputRegistersRequest(address=None, count=None, slave=1, transaction=0, skip_encode=0)
Bases: ReadRegistersRequestBase
Read input registers.
This function code is used to read from 1 to approx. 125 contiguous
input registers in a remote device. The Request PDU specifies the
starting register address and the number of registers. In the PDU
Registers are addressed starting at zero. Therefore input registers
numbered 1-16 are addressed as 0-15.
async execute(context)
Run a read input request against a datastore.
Parameters:
context – The datastore to request from
Returns:
An initialized ReadInputRegistersResponse
class pymodbus.pdu.register_read_message.ReadInputRegistersResponse(values=None, slave=None, transaction=0, skip_encode=0)
Bases: ReadRegistersResponseBase
Read/write input registers.
This function code is used to read from 1 to approx. 125 contiguous
input registers in a remote device. The Request PDU specifies the
starting register address and the number of registers. In the PDU
Registers are addressed starting at zero. Therefore input registers
numbered 1-16 are addressed as 0-15.
The requested registers can be found in the .registers list.
function_code = 4
class pymodbus.pdu.register_read_message.ReadRegistersRequestBase(address, count, slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
Base class for reading a modbus register.
decode(data)
Decode a register request packet.
Parameters:
data – The request to decode
class pymodbus.pdu.register_read_message.ReadRegistersResponseBase(values, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
Base class for responding to a modbus register read.
The requested registers can be found in the .registers list.
decode(data)
Decode a register response packet.
Parameters:
data – The request to decode
class pymodbus.pdu.register_read_message.ReadWriteMultipleRegistersRequest(read_address=0, read_count=0, write_address=0, write_registers=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
Read/write multiple registers.
This function code performs a combination of one read operation and one
write operation in a single MODBUS transaction. The write
operation is performed before the read.
Holding registers are addressed starting at zero. Therefore holding
registers 1-16 are addressed in the PDU as 0-15.
The request specifies the starting address and number of holding
registers to be read as well as the starting address, number of holding
registers, and the data to be written. The byte count specifies the
number of bytes to follow in the write data field.”
decode(data)
Decode the register request packet.
Parameters:
data – The request to decode
get_response_pdu_size()
Get response pdu size.
Func_code (1 byte) + Byte Count(1 byte) + 2 * Quantity of Coils (n Bytes)
:return:
class pymodbus.pdu.register_read_message.ReadWriteMultipleRegistersResponse(values=None, slave=None, transaction=0, skip_encode=0)
Bases: ReadHoldingRegistersResponse
Read/write multiple registers.
The normal response contains the data from the group of registers that
were read. The byte count field specifies the quantity of bytes to
follow in the read data field.
The requested registers can be found in the .registers list.
function_code = 23
class pymodbus.pdu.register_write_message.MaskWriteRegisterRequest(address=0, and_mask=65535, or_mask=0, slave=1, transaction=0, skip_encode=False)
Bases: ModbusRequest
This function code is used to modify the contents.
Of a specified holding register using a combination of an AND mask,
an OR mask, and the register’s current contents.
The function can be used to set or clear individual bits in the register.
decode(data)
Decode the incoming request.
Parameters:
data – The data to decode into the address
class pymodbus.pdu.register_write_message.MaskWriteRegisterResponse(address=0, and_mask=65535, or_mask=0, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
The normal response is an echo of the request.
The response is returned after the register has been written.
decode(data)
Decode a the response.
Parameters:
data – The packet data to decode
class pymodbus.pdu.register_write_message.WriteMultipleRegistersRequest(address=None, values=None, slave=None, transaction=0, skip_encode=0)
Bases: ModbusRequest
This function code is used to write a block.
Of contiguous registers (1 to approx. 120 registers) in a remote device.
The requested written values are specified in the request data field.
Data is packed as two bytes per register.
decode(data)
Decode a write single register packet packet request.
Parameters:
data – The request to decode
get_response_pdu_size()
Get response pdu size.
Func_code (1 byte) + Starting Address (2 byte) + Quantity of Registers  (2 Bytes)
:return:
class pymodbus.pdu.register_write_message.WriteMultipleRegistersResponse(address=None, count=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
The normal response returns the function code.
Starting address, and quantity of registers written.
decode(data)
Decode a write single register packet packet request.
Parameters:
data – The request to decode
class pymodbus.pdu.register_write_message.WriteSingleRegisterRequest(address=None, value=None, slave=None, transaction=0, skip_encode=0)
Bases: ModbusRequest
This function code is used to write a single holding register in a remote device.
The Request PDU specifies the address of the register to
be written. Registers are addressed starting at zero. Therefore register
numbered 1 is addressed as 0.
decode(data)
Decode a write single register packet packet request.
Parameters:
data – The request to decode
get_response_pdu_size()
Get response pdu size.
Func_code (1 byte) + Register Address(2 byte) + Register Value (2 bytes)
:return:
class pymodbus.pdu.register_write_message.WriteSingleRegisterResponse(address=None, value=None, slave=1, transaction=0, skip_encode=False)
Bases: ModbusResponse
The normal response is an echo of the request.
Returned after the register contents have been written.
decode(data)
Decode a write single register packet packet request.
Parameters:
data – The request to decode
get_response_pdu_size()
Get response pdu size.
Func_code (1 byte) + Starting Address (2 byte) + And_mask (2 Bytes) + OrMask (2 Bytes)
:return: