Internal documentation for MinimalModbus

MinimalModbus: A Python driver for Modbus RTU/ASCII via serial port (via USB, RS485 or RS232).

class minimalmodbus.Instrument(port, slaveaddress, mode='rtu', close_port_after_each_call=False, debug=False)[source]

Instrument class for talking to instruments (slaves).

Uses the Modbus RTU or ASCII protocols (via RS485 or RS232).

Args:
  • port (str): The serial port name, for example /dev/ttyUSB0 (Linux), /dev/tty.usbserial (OS X) or COM4 (Windows).
  • slaveaddress (int): Slave address in the range 1 to 247 (use decimal numbers, not hex). Address 0 is for broadcast, and 248-255 are reserved.
  • mode (str): Mode selection. Can be MODE_RTU or MODE_ASCII.
  • close_port_after_each_call (bool): If the serial port should be closed after each call to the instrument.
  • debug (bool): Set this to True to print the communication details
__init__(port, slaveaddress, mode='rtu', close_port_after_each_call=False, debug=False)[source]

Initialize instrument and open corresponding serial port.

address = None

Slave address (int). Most often set by the constructor (see the class documentation).

mode = None

Slave mode (str), can be MODE_RTU or MODE_ASCII. Most often set by the constructor (see the class documentation).

Changing this will not affect how other instruments use the same serial port.

New in version 0.6.

precalculate_read_size = None

If this is False, the serial port reads until timeout instead of just reading a specific number of bytes. Defaults to True.

Changing this will not affect how other instruments use the same serial port.

New in version 0.5.

debug = None

Set this to True to print the communication details. Defaults to False.

Most often set by the constructor (see the class documentation).

Changing this will not affect how other instruments use the same serial port.

clear_buffers_before_each_transaction = None

If this is True, the serial port read and write buffers are cleared before each request to the instrument, to avoid cumulative byte sync errors across multiple messages. Defaults to True.

Changing this will not affect how other instruments use the same serial port.

New in version 1.0.

close_port_after_each_call = None

If this is True, the serial port will be closed after each call. Defaults to False.

Changing this will not affect how other instruments use the same serial port.

Most often set by the constructor (see the class documentation).

handle_local_echo = None

Set to to True if your RS-485 adaptor has local echo enabled. Then the transmitted message will immeadiately appear at the receive line of the RS-485 adaptor. MinimalModbus will then read and discard this data, before reading the data from the slave. Defaults to False.

Changing this will not affect how other instruments use the same serial port.

New in version 0.7.

serial = None

The serial port object as defined by the pySerial module. Created by the constructor.

Attributes that could be changed after initialisation:

  • port (str): Serial port name.
    • Most often set by the constructor (see the class documentation).
  • baudrate (int): Baudrate in Baud.
    • Defaults to 19200.
  • parity (probably int): Parity. See the pySerial module for documentation.
    • Defaults to serial.PARITY_NONE.
  • bytesize (int): Bytesize in bits.
    • Defaults to 8.
  • stopbits (int): The number of stopbits.
    • Defaults to 1.
  • timeout (float): Read timeout value in seconds.
    • Defaults to 0.05 s.
  • write_timeout (float): Write timeout value in seconds.
    • Defaults to 2.0 s.
__repr__()[source]

Give string representation of the Instrument object.

_print_debug(text)[source]
read_bit(registeraddress, functioncode=2)[source]

Read one bit from the slave (instrument).

This is for a bit that has its individual address in the instrument.

Args:
  • registeraddress (int): The slave register address (use decimal numbers, not hex).
  • functioncode (int): Modbus function code. Can be 1 or 2.
Returns:
The bit value 0 or 1 (int).
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
write_bit(registeraddress, value, functioncode=5)[source]

Write one bit to the slave (instrument).

This is for a bit that has its individual address in the instrument.

Args:
  • registeraddress (int): The slave register address (use decimal numbers, not hex).
  • value (int or bool): 0 or 1, or True or False
  • functioncode (int): Modbus function code. Can be 5 or 15.
Returns:
None
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
read_bits(registeraddress, number_of_bits, functioncode=2)[source]

Read multiple bits from the slave (instrument).

This is for bits that have individual addresses in the instrument.

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • number_of_bits (int): Number of bits to read
  • functioncode (int): Modbus function code. Can be 1 or 2.
Returns:
A list of bit values 0 or 1 (int). The first value in the list is for the bit at the given address.
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
write_bits(registeraddress, values)[source]

Write multiple bits to the slave (instrument).

This is for bits that have individual addresses in the instrument.

Uses Modbus functioncode 15.

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • values (list of int or bool): 0 or 1, or True or False. The first value in the list is for the bit at the given address.
Returns:
None
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
read_register(registeraddress, number_of_decimals=0, functioncode=3, signed=False)[source]

Read an integer from one 16-bit register in the slave, possibly scaling it.

The slave register can hold integer values in the range 0 to 65535 (“Unsigned INT16”).

Args:
  • registeraddress (int): The slave register address (use decimal numbers, not hex).
  • number_of_decimals (int): The number of decimals for content conversion.
  • functioncode (int): Modbus function code. Can be 3 or 4.
  • signed (bool): Whether the data should be interpreted as unsigned or signed.

Note

The parameter number_of_decimals was named numberOfDecimals before MinimalModbus 1.0

If a value of 77.0 is stored internally in the slave register as 770, then use number_of_decimals=1 which will divide the received data by 10 before returning the value.

Similarly number_of_decimals=2 will divide the received data by 100 before returning the value.

Some manufacturers allow negative values for some registers. Instead of an allowed integer range 0 to 65535, a range -32768 to 32767 is allowed. This is implemented as any received value in the upper range (32768 to 65535) is interpreted as negative value (in the range -32768 to -1).

Use the parameter signed=True if reading from a register that can hold negative values. Then upper range data will be automatically converted into negative return values (two’s complement).

signed Data type in slave Alternative name Range
False Unsigned INT16 Unsigned short 0 to 65535
True INT16 Short -32768 to 32767
Returns:
The register data in numerical value (int or float).
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
write_register(registeraddress, value, number_of_decimals=0, functioncode=16, signed=False)[source]

Write an integer to one 16-bit register in the slave, possibly scaling it.

The slave register can hold integer values in the range 0 to 65535 (“Unsigned INT16”).

Args:
  • registeraddress (int): The slave register address (use decimal numbers, not hex).
  • value (int or float): The value to store in the slave register (might be scaled before sending).
  • number_of_decimals (int): The number of decimals for content conversion.
  • functioncode (int): Modbus function code. Can be 6 or 16.
  • signed (bool): Whether the data should be interpreted as unsigned or signed.

Note

The parameter number_of_decimals was named numberOfDecimals before MinimalModbus 1.0

To store for example value=77.0, use number_of_decimals=1 if the slave register will hold it as 770 internally. This will multiply value by 10 before sending it to the slave register.

Similarly number_of_decimals=2 will multiply value by 100 before sending it to the slave register.

As the largest number that can be written to a register is 0xFFFF = 65535, the value and number_of_decimals should max be 65535 when combined. So when using number_of_decimals=3 the maximum value is 65.535.

For discussion on negative values, the range and on alternative names, see read_register().

Use the parameter signed=True if writing to a register that can hold negative values. Then negative input will be automatically converted into upper range data (two’s complement).

Returns:
None
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
read_long(registeraddress, functioncode=3, signed=False, byteorder=0)[source]

Read a long integer (32 bits) from the slave.

Long integers (32 bits = 4 bytes) are stored in two consecutive 16-bit registers in the slave.

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • functioncode (int): Modbus function code. Can be 3 or 4.
  • signed (bool): Whether the data should be interpreted as unsigned or signed.
  • byteorder (int): How multi-register data should be interpreted. Defaults to BYTEORDER_BIG.
signed Data type in slave Alternative name Range
False Unsigned INT32 Unsigned long 0 to 4294967295
True INT32 Long -2147483648 to 2147483647
Returns:
The numerical value (int).
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
write_long(registeraddress, value, signed=False, byteorder=0)[source]

Write a long integer (32 bits) to the slave.

Long integers (32 bits = 4 bytes) are stored in two consecutive 16-bit registers in the slave.

Uses Modbus function code 16.

For discussion on number of bits, number of registers, the range and on alternative names, see read_long().

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • value (int or long): The value to store in the slave.
  • signed (bool): Whether the data should be interpreted as unsigned or signed.
  • byteorder (int): How multi-register data should be interpreted. Defaults to BYTEORDER_BIG.
Returns:
None
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
read_float(registeraddress, functioncode=3, number_of_registers=2, byteorder=0)[source]

Read a floating point number from the slave.

Floats are stored in two or more consecutive 16-bit registers in the slave. The encoding is according to the standard IEEE 754.

There are differences in the byte order used by different manufacturers. A floating point value of 1.0 is encoded (in single precision) as 3f800000 (hex). In this implementation the data will be sent as '\x3f\x80' and '\x00\x00' to two consecutetive registers by default. Make sure to test that it makes sense for your instrument. If not, change the byteorder argument.

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • functioncode (int): Modbus function code. Can be 3 or 4.
  • number_of_registers (int): The number of registers allocated for the float. Can be 2 or 4.
  • byteorder (int): How multi-register data should be interpreted. Defaults to BYTEORDER_BIG.

Note

The parameter number_of_registers was named numberOfRegisters before MinimalModbus 1.0

Type of floating point number in slave Size Registers Range
Single precision (binary32) 32 bits (4 bytes) 2 registers 1.4E-45 to 3.4E38
Double precision (binary64) 64 bits (8 bytes) 4 registers 5E-324 to 1.8E308
Returns:
The numerical value (float).
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
write_float(registeraddress, value, number_of_registers=2, byteorder=0)[source]

Write a floating point number to the slave.

Floats are stored in two or more consecutive 16-bit registers in the slave.

Uses Modbus function code 16.

For discussion on precision, number of registers and on byte order, see read_float().

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • value (float or int): The value to store in the slave
  • number_of_registers (int): The number of registers allocated for the float. Can be 2 or 4.
  • byteorder (int): How multi-register data should be interpreted. Defaults to BYTEORDER_BIG.

Note

The parameter number_of_registers was named numberOfRegisters before MinimalModbus 1.0

Returns:
None
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
read_string(registeraddress, number_of_registers=16, functioncode=3)[source]

Read an ASCII string from the slave.

Each 16-bit register in the slave are interpreted as two characters (each 1 byte = 8 bits). For example 16 consecutive registers can hold 32 characters (32 bytes).

International characters (Unicode/UTF-8) are not supported.

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • number_of_registers (int): The number of registers allocated for the string.
  • functioncode (int): Modbus function code. Can be 3 or 4.

Note

The parameter number_of_registers was named numberOfRegisters before MinimalModbus 1.0

Returns:
The string (str).
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
write_string(registeraddress, textstring, number_of_registers=16)[source]

Write an ASCII string to the slave.

Each 16-bit register in the slave are interpreted as two characters (each 1 byte = 8 bits). For example 16 consecutive registers can hold 32 characters (32 bytes).

Uses Modbus function code 16.

International characters (Unicode/UTF-8) are not supported.

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • textstring (str): The string to store in the slave, must be ASCII.
  • number_of_registers (int): The number of registers allocated for the string.

Note

The parameter number_of_registers was named numberOfRegisters before MinimalModbus 1.0

If the textstring is longer than the 2*number_of_registers, an error is raised. Shorter strings are padded with spaces.

Returns:
None
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
read_registers(registeraddress, number_of_registers, functioncode=3)[source]

Read integers from 16-bit registers in the slave.

The slave registers can hold integer values in the range 0 to 65535 (“Unsigned INT16”).

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • number_of_registers (int): The number of registers to read, max 125 registers.
  • functioncode (int): Modbus function code. Can be 3 or 4.

Note

The parameter number_of_registers was named numberOfRegisters before MinimalModbus 1.0

Any scaling of the register data, or converting it to negative number (two’s complement) must be done manually.

Returns:
The register data (a list of int). The first value in the list is for the register at the given address.
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
write_registers(registeraddress, values)[source]

Write integers to 16-bit registers in the slave.

The slave register can hold integer values in the range 0 to 65535 (“Unsigned INT16”).

Uses Modbus function code 16.

The number of registers that will be written is defined by the length of the values list.

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • values (list of int): The values to store in the slave registers, max 123 values. The first value in the list is for the register at the given address.

Note

The parameter number_of_registers was named numberOfRegisters before MinimalModbus 1.0

Any scaling of the register data, or converting it to negative number (two’s complement) must be done manually.

Returns:
None
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
_generic_command(functioncode, registeraddress, value=None, number_of_decimals=0, number_of_registers=0, number_of_bits=0, signed=False, byteorder=0, payloadformat=None)[source]

Perform generic command for reading and writing registers and bits.

Args:
  • functioncode (int): Modbus function code.
  • registeraddress (int): The register address (use decimal numbers, not hex).
  • value (numerical or string or None or list of int): The value to store in the register. Depends on payloadformat.
  • number_of_decimals (int): The number of decimals for content conversion. Only for a single register.
  • number_of_registers (int): The number of registers to read/write. Only certain values allowed, depends on payloadformat.
  • number_of_bits (int):T he number of registers to read/write.
  • signed (bool): Whether the data should be interpreted as unsigned or signed. Only for a single register or for payloadformat=’long’.
  • byteorder (int): How multi-register data should be interpreted.
  • payloadformat (None or string): Any of the _PAYLOADFORMAT_* values

If a value of 77.0 is stored internally in the slave register as 770, then use number_of_decimals=1 which will divide the received data from the slave by 10 before returning the value. Similarly number_of_decimals=2 will divide the received data by 100 before returning the value. Same functionality is also used when writing data to the slave.

Returns:
The register data in numerical value (int or float), or the bit value 0 or 1 (int), or None.
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)
_perform_command(functioncode, payload_to_slave)[source]

Perform the command having the functioncode.

Args:
  • functioncode (int): The function code for the command to be performed. Can for example be ‘Write register’ = 16.
  • payload_to_slave (str): Data to be transmitted to the slave (will be embedded in slaveaddress, CRC etc)
Returns:
The extracted data payload from the slave (a string). It has been stripped of CRC etc.
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)

Makes use of the _communicate() method. The request is generated with the _embed_payload() function, and the parsing of the response is done with the _extract_payload() function.

_communicate(request, number_of_bytes_to_read)[source]

Talk to the slave via a serial port.

Args:
request (str): The raw request that is to be sent to the slave. number_of_bytes_to_read (int): number of bytes to read
Returns:
The raw data (string) returned from the slave.
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)

Note that the answer might have strange ASCII control signs, which makes it difficult to print it in the promt (messes up a bit). Use repr() to make the string printable (shows ASCII values for control signs.)

Will block until reaching number_of_bytes_to_read or timeout.

If the attribute Instrument.debug is True, the communication details are printed.

If the attribute Instrument.close_port_after_each_call is True the serial port is closed after each call.

Timing:

                Request from master (Master is writing)
                |
                |                             Response from slave (Master is reading)
                |                             |
--------R-------W-----------------------------R-------W-----------------------------
         |     |                               |
         |     |<------- Roundtrip time ------>|
         |     |
      -->|-----|<----- Silent period

The resolution for Python’s time.time() is lower on Windows than on Linux. It is about 16 ms on Windows according to https://stackoverflow.com/questions/157359/accurate-timestamping-in-python-logging

For Python3, the information sent to and from pySerial should be of the type bytes. This is taken care of automatically by MinimalModbus.

_performCommand(functioncode, payload_to_slave)

Perform the command having the functioncode.

Args:
  • functioncode (int): The function code for the command to be performed. Can for example be ‘Write register’ = 16.
  • payload_to_slave (str): Data to be transmitted to the slave (will be embedded in slaveaddress, CRC etc)
Returns:
The extracted data payload from the slave (a string). It has been stripped of CRC etc.
Raises:
TypeError, ValueError, ModbusException, serial.SerialException (inherited from IOError)

Makes use of the _communicate() method. The request is generated with the _embed_payload() function, and the parsing of the response is done with the _extract_payload() function.

__module__ = 'minimalmodbus'
exception minimalmodbus.ModbusException[source]

Base class for Modbus communication exceptions.

Inherits from IOError, which is an alias for OSError in Python3.

__module__ = 'minimalmodbus'
__weakref__

list of weak references to the object (if defined)

exception minimalmodbus.SlaveReportedException[source]

Base class for exceptions that the slave (instrument) reports.

__module__ = 'minimalmodbus'
exception minimalmodbus.SlaveDeviceBusyError[source]

The slave is busy processing some command.

__module__ = 'minimalmodbus'
exception minimalmodbus.NegativeAcknowledgeError[source]

The slave can not fulfil the programming request.

This typically happens when using function code 13 or 14 decimal.

__module__ = 'minimalmodbus'
exception minimalmodbus.IllegalRequestError[source]

The slave has received an illegal request.

__module__ = 'minimalmodbus'
exception minimalmodbus.MasterReportedException[source]

Base class for exceptions that the master (computer) detects.

__module__ = 'minimalmodbus'
exception minimalmodbus.NoResponseError[source]

No response from the slave.

__module__ = 'minimalmodbus'
exception minimalmodbus.LocalEchoError[source]

There is some problem with the local echo.

__module__ = 'minimalmodbus'
exception minimalmodbus.InvalidResponseError[source]

The response does not fulfill the Modbus standad, for example wrong checksum.

__module__ = 'minimalmodbus'
minimalmodbus._create_payload(functioncode, registeraddress, value, number_of_decimals, number_of_registers, number_of_bits, signed, byteorder, payloadformat)[source]

Create the payload.

Error checking should have been done before calling this function.

For argument descriptions, see the _generic_command() method.

minimalmodbus._parse_payload(payload, functioncode, registeraddress, value, number_of_decimals, number_of_registers, number_of_bits, signed, byteorder, payloadformat)[source]
minimalmodbus._embed_payload(slaveaddress, mode, functioncode, payloaddata)[source]

Build a request from the slaveaddress, the function code and the payload data.

Args:
  • slaveaddress (int): The address of the slave.
  • mode (str): The modbus protcol mode (MODE_RTU or MODE_ASCII)
  • functioncode (int): The function code for the command to be performed. Can for example be 16 (Write register).
  • payloaddata (str): The byte string to be sent to the slave.
Returns:
The built (raw) request string for sending to the slave (including CRC etc).
Raises:
ValueError, TypeError.
The resulting request has the format:
  • RTU Mode: slaveaddress byte + functioncode byte + payloaddata + CRC (which is two bytes).
  • ASCII Mode: header (:) + slaveaddress (2 characters) + functioncode (2 characters) + payloaddata + LRC (which is two characters) + footer (CRLF)

The LRC or CRC is calculated from the byte string made up of slaveaddress + functioncode + payloaddata. The header, LRC/CRC, and footer are excluded from the calculation.

minimalmodbus._extract_payload(response, slaveaddress, mode, functioncode)[source]

Extract the payload data part from the slave’s response.

Args:
  • response (str): The raw response byte string from the slave. This is different for RTU and ASCII.
  • slaveaddress (int): The adress of the slave. Used here for error checking only.
  • mode (str): The modbus protcol mode (MODE_RTU or MODE_ASCII)
  • functioncode (int): Used here for error checking only.
Returns:
The payload part of the response string. Conversion from Modbus ASCII has been done if applicable.
Raises:
ValueError, TypeError, ModbusException (or subclasses).

Raises an exception if there is any problem with the received address, the functioncode or the CRC.

The received response should have the format:

  • RTU Mode: slaveaddress byte + functioncode byte + payloaddata + CRC (which is two bytes)
  • ASCII Mode: header (:) + slaveaddress byte + functioncode byte + payloaddata + LRC (which is two characters) + footer (CRLF)

For development purposes, this function can also be used to extract the payload from the request sent TO the slave.

minimalmodbus._predict_response_size(mode, functioncode, payload_to_slave)[source]

Calculate the number of bytes that should be received from the slave.

Args:
  • mode (str): The modbus protcol mode (MODE_RTU or MODE_ASCII)
  • functioncode (int): Modbus function code.
  • payload_to_slave (str): The raw request that is to be sent to the slave (not hex encoded string)
Returns:
The preducted number of bytes (int) in the response.
Raises:
ValueError, TypeError.
minimalmodbus._calculate_minimum_silent_period(baudrate)[source]

Calculate the silent period length between messages.

It should correspond to the time to send 3.5 characters.

Args:
baudrate (numerical): The baudrate for the serial port
Returns:
The number of seconds (float) that should pass between each message on the bus.
Raises:
ValueError, TypeError.
minimalmodbus._num_to_onebyte_string(inputvalue)[source]

Convert a numerical value to a one-byte string.

Args:
inputvalue (int): The value to be converted. Should be >=0 and <=255.
Returns:
A one-byte string created by chr(inputvalue).
Raises:
TypeError, ValueError
minimalmodbus._num_to_twobyte_string(value, number_of_decimals=0, lsb_first=False, signed=False)[source]

Convert a numerical value to a two-byte string, possibly scaling it.

Args:
  • value (float or int): The numerical value to be converted.
  • number_of_decimals (int): Number of decimals, 0 or more, for scaling.
  • lsb_first (bool): Whether the least significant byte should be first in the resulting string.
  • signed (bool): Whether negative values should be accepted.
Returns:
A two-byte string.
Raises:
TypeError, ValueError. Gives DeprecationWarning instead of ValueError for some values in Python 2.6.

Use number_of_decimals=1 to multiply value by 10 before sending it to the slave register. Similarly number_of_decimals=2 will multiply value by 100 before sending it to the slave register.

Use the parameter signed=True if making a bytestring that can hold negative values. Then negative input will be automatically converted into upper range data (two’s complement).

The byte order is controlled by the lsb_first parameter, as seen here:

lsb_first parameter Endianness Description
False (default) Big-endian Most significant byte is sent first
True Little-endian Least significant byte is sent first
For example:
To store for example value=77.0, use number_of_decimals = 1 if the register will hold it as 770 internally. The value 770 (dec) is 0302 (hex), where the most significant byte is 03 (hex) and the least significant byte is 02 (hex). With lsb_first = False, the most significant byte is given first why the resulting string is \x03\x02, which has the length 2.
minimalmodbus._twobyte_string_to_num(bytestring, number_of_decimals=0, signed=False)[source]

Convert a two-byte string to a numerical value, possibly scaling it.

Args:
  • bytestring (str): A string of length 2.
  • number_of_decimals (int): The number of decimals. Defaults to 0.
  • signed (bol): Whether large positive values should be interpreted as negative values.
Returns:
The numerical value (int or float) calculated from the bytestring.
Raises:
TypeError, ValueError

Use the parameter signed=True if converting a bytestring that can hold negative values. Then upper range data will be automatically converted into negative return values (two’s complement).

Use number_of_decimals=1 to divide the received data by 10 before returning the value. Similarly number_of_decimals=2 will divide the received data by 100 before returning the value.

The byte order is big-endian, meaning that the most significant byte is sent first.

For example:
A string \x03\x02 (which has the length 2) corresponds to 0302 (hex) = 770 (dec). If number_of_decimals = 1, then this is converted to 77.0 (float).
minimalmodbus._long_to_bytestring(value, signed=False, number_of_registers=2, byteorder=0)[source]

Convert a long integer to a bytestring.

Long integers (32 bits = 4 bytes) are stored in two consecutive 16-bit registers in the slave.

Args:
  • value (int): The numerical value to be converted.
  • signed (bool): Whether large positive values should be interpreted as negative values.
  • number_of_registers (int): Should be 2. For error checking only.
  • byteorder (int): How multi-register data should be interpreted.
Returns:
A bytestring (4 bytes).
Raises:
TypeError, ValueError
minimalmodbus._bytestring_to_long(bytestring, signed=False, number_of_registers=2, byteorder=0)[source]

Convert a bytestring to a long integer.

Long integers (32 bits = 4 bytes) are stored in two consecutive 16-bit registers in the slave.

Args:
  • bytestring (str): A string of length 4.
  • signed (bol): Whether large positive values should be interpreted as negative values.
  • number_of_registers (int): Should be 2. For error checking only.
  • byteorder (int): How multi-register data should be interpreted.
Returns:
The numerical value (int).
Raises:
ValueError, TypeError
minimalmodbus._float_to_bytestring(value, number_of_registers=2, byteorder=0)[source]

Convert a numerical value to a bytestring.

Floats are stored in two or more consecutive 16-bit registers in the slave. The encoding is according to the standard IEEE 754.

Type of floating point number in slave Size Registers Range
Single precision (binary32) 32 bits (4 bytes) 2 registers 1.4E-45 to 3.4E38
Double precision (binary64) 64 bits (8 bytes) 4 registers 5E-324 to 1.8E308

A floating point value of 1.0 is encoded (in single precision) as 3f800000 (hex). This will give a byte string '\x3f\x80\x00\x00' (big endian).

Args:
  • value (float or int): The numerical value to be converted.
  • number_of_registers (int): Can be 2 or 4.
  • byteorder (int): How multi-register data should be interpreted.
Returns:
A bytestring (4 or 8 bytes).
Raises:
TypeError, ValueError
minimalmodbus._bytestring_to_float(bytestring, number_of_registers=2, byteorder=0)[source]

Convert a four-byte string to a float.

Floats are stored in two or more consecutive 16-bit registers in the slave.

For discussion on precision, number of bits, number of registers, the range, byte order and on alternative names, see minimalmodbus._float_to_bytestring().

Args:
  • bytestring (str): A string of length 4 or 8.
  • number_of_registers (int): Can be 2 or 4.
  • byteorder (int): How multi-register data should be interpreted.
Returns:
A float.
Raises:
TypeError, ValueError
minimalmodbus._textstring_to_bytestring(inputstring, number_of_registers=16)[source]

Convert a text string to a bytestring.

Each 16-bit register in the slave are interpreted as two characters (1 byte = 8 bits). For example 16 consecutive registers can hold 32 characters (32 bytes).

Not much of conversion is done, mostly error checking and string padding. If the inputstring is shorter that the allocated space, it is padded with spaces in the end.

Args:
  • inputstring (str): The string to be stored in the slave. Max 2*number_of_registers characters.
  • number_of_registers (int): The number of registers allocated for the string.
Returns:
A bytestring (str).
Raises:
TypeError, ValueError
minimalmodbus._bytestring_to_textstring(bytestring, number_of_registers=16)[source]

Convert a bytestring to a text string.

Each 16-bit register in the slave are interpreted as two characters (1 byte = 8 bits). For example 16 consecutive registers can hold 32 characters (32 bytes).

Not much of conversion is done, mostly error checking.

Args:
  • bytestring (str): The string from the slave. Length = 2*number_of_registers
  • number_of_registers (int): The number of registers allocated for the string.
Returns:
A the text string (str).
Raises:
TypeError, ValueError
minimalmodbus._valuelist_to_bytestring(valuelist, number_of_registers)[source]

Convert a list of numerical values to a bytestring.

Each element is ‘unsigned INT16’.

Args:
  • valuelist (list of int): The input list. The elements should be in the range 0 to 65535.
  • number_of_registers (int): The number of registers. For error checking. Should equal the number of elements in valuelist.
Returns:
A bytestring (str). Length = 2*number_of_registers
Raises:
TypeError, ValueError
minimalmodbus._bytestring_to_valuelist(bytestring, number_of_registers)[source]

Convert a bytestring to a list of numerical values.

The bytestring is interpreted as ‘unsigned INT16’.

Args:
  • bytestring (str): The string from the slave. Length = 2*number_of_registers
  • number_of_registers (int): The number of registers. For error checking.
Returns:
A list of integers.
Raises:
TypeError, ValueError
minimalmodbus._now()[source]

Return a timestamp for time duration measurements.

Returns a float, that increases with 1.0 per second. The starting point is undefined.

minimalmodbus._pack(formatstring, value)[source]

Pack a value into a bytestring.

Uses the built-in struct Python module.

Args:
  • formatstring (str): String for the packing. See the struct module for details.
  • value (depends on formatstring): The value to be packed
Returns:
A bytestring (str).
Raises:
ValueError

Note that the struct module produces byte buffers for Python3, but bytestrings for Python2. This is compensated for automatically.

minimalmodbus._unpack(formatstring, packed)[source]

Unpack a bytestring into a value.

Uses the built-in struct Python module.

Args:
  • formatstring (str): String for the packing. See the struct module for details.
  • packed (str): The bytestring to be unpacked.
Returns:
A value. The type depends on the formatstring.
Raises:
ValueError

Note that the struct module wants byte buffers for Python3, but bytestrings for Python2. This is compensated for automatically.

minimalmodbus._swap(bytestring)[source]

Swap characters pairwise in a string.

This corresponds to a “byte swap”.

Args:
  • bytestring (str): input. The length should be an even number.

Return the string with characters swapped.

minimalmodbus._hexencode(bytestring, insert_spaces=False)[source]

Convert a byte string to a hex encoded string.

For example ‘J’ will return ‘4A’, and '\x04' will return ‘04’.

Args:
  • bytestring (str): Can be for example 'A\x01B\x45'.
  • insert_spaces (bool): Insert space characters between pair of characters to increase readability.
Returns:
A string of twice the length, with characters in the range ‘0’ to ‘9’ and ‘A’ to ‘F’. The string will be longer if spaces are inserted.
Raises:
TypeError, ValueError
minimalmodbus._hexdecode(hexstring)[source]

Convert a hex encoded string to a byte string.

For example ‘4A’ will return ‘J’, and ‘04’ will return '\x04' (which has length 1).

Args:
  • hexstring (str): Can be for example ‘A3’ or ‘A3B4’. Must be of even length.
  • Allowed characters are ‘0’ to ‘9’, ‘a’ to ‘f’ and ‘A’ to ‘F’ (not space).
Returns:
A string of half the length, with characters corresponding to all 0-255 values for each byte.
Raises:
TypeError, ValueError
minimalmodbus._hexlify(bytestring)[source]

Convert a byte string to a hex encoded string, with spaces for easier reading.

This is just a facade for _hexencode() with insert_spaces = True.

See _hexencode() for details.

minimalmodbus._calculate_number_of_bytes_for_bits(number_of_bits)[source]

Calculate number of full bytes required to house a number of bits.

Args:
  • number_of_bits (str): Number of bits

Error checking should have been done before.

Algorithm from MODBUS APPLICATION PROTOCOL SPECIFICATION V1.1b

minimalmodbus._bit_to_bytestring(value)[source]

Create the bit pattern that is used for writing single bits.

Used for functioncode 5. The same value is sent back in the response from the slave.

This is basically a storage of numerical constants.

Args:
  • value (int): can be 0 or 1
Returns:
The bit pattern (string).
Raises:
TypeError, ValueError
minimalmodbus._bits_to_bytestring(valuelist)[source]

Build a bytestring from a list of bits.

This is used for functioncode 15.

Args:
  • valuelist (list of int): 0 or 1

Returns a bytestring.

minimalmodbus._bytestring_to_bits(bytestring, number_of_bits)[source]

Parse bits from a bytestring.

This is used for parsing the bits in response messages for functioncode 1 and 2.

The first byte in the bytestring contains info on the addressed bit (in LSB in that byte). Second bit from right contains info on the bit on the next address.

Next byte in the bytestring contains data on next 8 bits. Might be padded with zeros toward MSB.

Args:
  • bytestring (str): input string
  • number_of_bits (int): Number of bits to extract

Returns a list of values (0 or 1). The length of the list is equal to number_of_bits.

minimalmodbus._twos_complement(x, bits=16)[source]

Calculate the two’s complement of an integer.

Then also negative values can be represented by an upper range of positive values. See https://en.wikipedia.org/wiki/Two%27s_complement

Args:
  • x (int): input integer.
  • bits (int): number of bits, must be > 0.
Returns:
An int, that represents the two’s complement of the input.

Example for bits=8:

x returns
0 0
1 1
127 127
-128 128
-127 129
-1 255
minimalmodbus._from_twos_complement(x, bits=16)[source]

Calculate the inverse(?) of a two’s complement of an integer.

Args:
  • x (int): input integer.
  • bits (int): number of bits, must be > 0.
Returns:
An int, that represents the inverse(?) of two’s complement of the input.

Example for bits=8:

x returns
0 0
1 1
127 127
128 -128
129 -127
255 -1
minimalmodbus._set_bit_on(x, bit_num)[source]

Set bit ‘bit_num’ to True.

Args:
  • x (int): The value before.
  • bit_num (int): The bit number that should be set to True.
Returns:
The value after setting the bit. This is an integer.
For example:
For x = 4 (dec) = 0100 (bin), setting bit number 0 results in 0101 (bin) = 5 (dec).
minimalmodbus._check_bit(x, bit_num)[source]

Check if bit ‘bit_num’ is set the input integer.

Args:
  • x (int): The input value.
  • bit_num (int): The bit number to be checked
Returns:
True or False
For example:
For x = 4 (dec) = 0100 (bin), checking bit number 2 results in True, and checking bit number 3 results in False.
minimalmodbus._CRC16TABLE = (0, 49345, 49537, 320, 49921, 960, 640, 49729, 50689, 1728, 1920, 51009, 1280, 50625, 50305, 1088, 52225, 3264, 3456, 52545, 3840, 53185, 52865, 3648, 2560, 51905, 52097, 2880, 51457, 2496, 2176, 51265, 55297, 6336, 6528, 55617, 6912, 56257, 55937, 6720, 7680, 57025, 57217, 8000, 56577, 7616, 7296, 56385, 5120, 54465, 54657, 5440, 55041, 6080, 5760, 54849, 53761, 4800, 4992, 54081, 4352, 53697, 53377, 4160, 61441, 12480, 12672, 61761, 13056, 62401, 62081, 12864, 13824, 63169, 63361, 14144, 62721, 13760, 13440, 62529, 15360, 64705, 64897, 15680, 65281, 16320, 16000, 65089, 64001, 15040, 15232, 64321, 14592, 63937, 63617, 14400, 10240, 59585, 59777, 10560, 60161, 11200, 10880, 59969, 60929, 11968, 12160, 61249, 11520, 60865, 60545, 11328, 58369, 9408, 9600, 58689, 9984, 59329, 59009, 9792, 8704, 58049, 58241, 9024, 57601, 8640, 8320, 57409, 40961, 24768, 24960, 41281, 25344, 41921, 41601, 25152, 26112, 42689, 42881, 26432, 42241, 26048, 25728, 42049, 27648, 44225, 44417, 27968, 44801, 28608, 28288, 44609, 43521, 27328, 27520, 43841, 26880, 43457, 43137, 26688, 30720, 47297, 47489, 31040, 47873, 31680, 31360, 47681, 48641, 32448, 32640, 48961, 32000, 48577, 48257, 31808, 46081, 29888, 30080, 46401, 30464, 47041, 46721, 30272, 29184, 45761, 45953, 29504, 45313, 29120, 28800, 45121, 20480, 37057, 37249, 20800, 37633, 21440, 21120, 37441, 38401, 22208, 22400, 38721, 21760, 38337, 38017, 21568, 39937, 23744, 23936, 40257, 24320, 40897, 40577, 24128, 23040, 39617, 39809, 23360, 39169, 22976, 22656, 38977, 34817, 18624, 18816, 35137, 19200, 35777, 35457, 19008, 19968, 36545, 36737, 20288, 36097, 19904, 19584, 35905, 17408, 33985, 34177, 17728, 34561, 18368, 18048, 34369, 33281, 17088, 17280, 33601, 16640, 33217, 32897, 16448)

CRC-16 lookup table with 256 elements.

Built with this code:

poly=0xA001
table = []
for index in range(256):
    data = index << 1
    crc = 0
    for _ in range(8, 0, -1):
        data >>= 1
        if (data ^ crc) & 0x0001:
            crc = (crc >> 1) ^ poly
        else:
            crc >>= 1
    table.append(crc)
output = ''
for i, m in enumerate(table):
    if not i%11:
        output += "\n"
    output += "{:5.0f}, ".format(m)
print output
minimalmodbus._calculate_crc_string(inputstring)[source]

Calculate CRC-16 for Modbus.

Args:
inputstring (str): An arbitrary-length message (without the CRC).
Returns:
A two-byte CRC string, where the least significant byte is first.
minimalmodbus._calculate_lrc_string(inputstring)[source]

Calculate LRC for Modbus.

Args:
inputstring (str): An arbitrary-length message (without the beginning colon and terminating CRLF). It should already be decoded from hex-string.
Returns:
A one-byte LRC bytestring (not encoded to hex-string)

Algorithm from the document ‘MODBUS over serial line specification and implementation guide V1.02’.

The LRC is calculated as 8 bits (one byte).

For example a LRC 0110 0001 (bin) = 61 (hex) = 97 (dec) = ‘a’. This function will then return ‘a’.

In Modbus ASCII mode, this should be transmitted using two characters. This example should be transmitted ‘61’, which is a string of length two. This function does not handle that conversion for transmission.

minimalmodbus._check_mode(mode)[source]

Check that the Modbus mode is valie.

Args:
mode (string): The Modbus mode (MODE_RTU or MODE_ASCII)
Raises:
TypeError, ValueError
minimalmodbus._check_functioncode(functioncode, list_of_allowed_values=None)[source]

Check that the given functioncode is in the list_of_allowed_values.

Also verifies that 1 <= function code <= 127.

Args:
  • functioncode (int): The function code
  • list_of_allowed_values (list of int): Allowed values. Use None to bypass this part of the checking.
Raises:
TypeError, ValueError
minimalmodbus._check_slaveaddress(slaveaddress)[source]

Check that the given slaveaddress is valid.

Args:
slaveaddress (int): The slave address
Raises:
TypeError, ValueError
minimalmodbus._check_registeraddress(registeraddress)[source]

Check that the given registeraddress is valid.

Args:
registeraddress (int): The register address
Raises:
TypeError, ValueError
minimalmodbus._check_response_payload(payload, functioncode, registeraddress, value, number_of_decimals, number_of_registers, number_of_bits, signed, byteorder, payloadformat)[source]
minimalmodbus._check_response_slaveerrorcode(response)[source]

Check if the slave indicates an error.

Args:
  • response (string): Response from the slave

The response is in RTU format, but the checksum might be one or two bytes depending on whether it was sent in RTU or ASCII mode.

Checking of type and length of the response should be done before calling this functions.

Raises:
SlaveReportedException or subclass
minimalmodbus._check_response_bytecount(payload)[source]

Check that the number of bytes as given in the response is correct.

The first byte in the payload indicates the length of the payload (first byte not counted).

Args:
payload (string): The payload
Raises:
TypeError, ValueError, InvalidResponseError
minimalmodbus._check_response_registeraddress(payload, registeraddress)[source]

Check that the start adress as given in the response is correct.

The first two bytes in the payload holds the address value.

Args:
  • payload (string): The payload
  • registeraddress (int): What the register address actually shoud be (use decimal numbers, not hex).
Raises:
TypeError, ValueError, InvalidResponseError
minimalmodbus._check_response_number_of_registers(payload, number_of_registers)[source]

Check that the number of written registers as given in the response is correct.

The bytes 2 and 3 (zero based counting) in the payload holds the value.

Args:
  • payload (string): The payload
  • number_of_registers (int): Number of registers that have been written
Raises:
TypeError, ValueError, InvalidResponseError
minimalmodbus._check_response_writedata(payload, writedata)[source]

Check that the write data as given in the response is correct.

The bytes 2 and 3 (zero based counting) in the payload holds the write data.

Args:
  • payload (string): The payload
  • writedata (string): The data that should have been written. Length should be 2 bytes.
Raises:
TypeError, ValueError, InvalidResponseError
minimalmodbus._check_string(inputstring, description, minlength=0, maxlength=None, force_ascii=False, exception_type=<type 'exceptions.ValueError'>)[source]

Check that the given string is valid.

Args:
  • inputstring (string): The string to be checked
  • description (string): Used in error messages for the checked inputstring
  • minlength (int): Minimum length of the string
  • maxlength (int or None): Maximum length of the string
  • force_ascii (bool): Enforce that the string is ASCII
  • exception_type (Exception): The type of exception to raise for length errors

The force_ascii argument is valid only for Python3, as all strings are ASCII in Python2.

Raises:
TypeError, ValueError or the one given by exception_type

Uses the function _check_int() internally.

minimalmodbus._check_int(inputvalue, minvalue=None, maxvalue=None, description='inputvalue')[source]

Check that the given integer is valid.

Args:
  • inputvalue (int or long): The integer to be checked
  • minvalue (int or long, or None): Minimum value of the integer
  • maxvalue (int or long, or None): Maximum value of the integer
  • description (string): Used in error messages for the checked inputvalue
Raises:
TypeError, ValueError

Note: Can not use the function _check_string(), as that function uses this function internally.

minimalmodbus._check_numerical(inputvalue, minvalue=None, maxvalue=None, description='inputvalue')[source]

Check that the given numerical value is valid.

Args:
  • inputvalue (numerical): The value to be checked.
  • minvalue (numerical): Minimum value Use None to skip this part of the test.
  • maxvalue (numerical): Maximum value. Use None to skip this part of the test.
  • description (string): Used in error messages for the checked inputvalue
Raises:
TypeError, ValueError

Note: Can not use the function _check_string(), as it uses this function internally.

minimalmodbus._check_bool(inputvalue, description='inputvalue')[source]

Check that the given inputvalue is a boolean.

Args:
  • inputvalue (boolean): The value to be checked.
  • description (string): Used in error messages for the checked inputvalue.
Raises:
TypeError, ValueError
minimalmodbus._print_out(inputstring)[source]

Print the inputstring. To make it compatible with Python2 and Python3.

Args:
inputstring (str): The string that should be printed.
Raises:
TypeError
minimalmodbus._get_diagnostic_string()[source]

Generate a diagnostic string, showing the module version, the platform etc.

Returns:
A descriptive string.
minimalmodbus._getDiagnosticString()

Generate a diagnostic string, showing the module version, the platform etc.

Returns:
A descriptive string.