API for MinimalModbus

MinimalModbus: A Python driver for the Modbus RTU protocol via serial port (via RS485 or RS232).

This Python file was changed (committed) at $Date: 2014-06-22 01:29:19 +0200 (Sun, 22 Jun 2014) $, which was $Revision: 200 $.

minimalmodbus.BAUDRATE = 19200

Default value for the baudrate in Baud (int).

minimalmodbus.PARITY = 'N'

Default value for the parity. See the pySerial module for documentation. Defaults to serial.PARITY_NONE

minimalmodbus.BYTESIZE = 8

Default value for the bytesize (int).

minimalmodbus.STOPBITS = 1

Default value for the number of stopbits (int).

minimalmodbus.TIMEOUT = 0.05

Default value for the timeout value in seconds (float).

minimalmodbus.CLOSE_PORT_AFTER_EACH_CALL = False

Default value for port closure setting.

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

Instrument class for talking to instruments (slaves) via the Modbus RTU protocol (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).
  • mode (str): Mode selection. Can be MODE_RTU or MODE_ASCII!
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).

New in version 0.6.

debug = None

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

close_port_after_each_call = None

If this is True, the serial port will be closed after each call. Defaults to CLOSE_PORT_AFTER_EACH_CALL. To change it, set the value minimalmodbus.CLOSE_PORT_AFTER_EACH_CALL=True .

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.

New in version 0.5.

read_bit(registeraddress, functioncode=2)[source]

Read one bit from the slave.

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:
ValueError, TypeError, IOError
write_bit(registeraddress, value, functioncode=5)[source]

Write one bit to the slave.

Args:
  • registeraddress (int): The slave register address (use decimal numbers, not hex).
  • value (int): 0 or 1
  • functioncode (int): Modbus function code. Can be 5 or 15.
Returns:
None
Raises:
ValueError, TypeError, IOError
read_register(registeraddress, numberOfDecimals=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).
  • numberOfDecimals (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.

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

Similarly numberOfDecimals=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:
ValueError, TypeError, IOError
write_register(registeraddress, value, numberOfDecimals=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).
  • numberOfDecimals (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.

To store for example value=77.0, use numberOfDecimals=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 numberOfDecimals=2 will multiply value by 100 before sending it to the slave register.

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:
ValueError, TypeError, IOError
read_long(registeraddress, functioncode=3, signed=False)[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.
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:
ValueError, TypeError, IOError
write_long(registeraddress, value, signed=False)[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.
Returns:
None
Raises:
ValueError, TypeError, IOError
read_float(registeraddress, functioncode=3, numberOfRegisters=2)[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 . Make sure to test that it makes sense for your instrument. It is pretty straight-forward to change this code if some other byte order is required by anyone (see support section).

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • functioncode (int): Modbus function code. Can be 3 or 4.
  • numberOfRegisters (int): The number of registers allocated for the float. Can be 2 or 4.
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:
ValueError, TypeError, IOError
write_float(registeraddress, value, numberOfRegisters=2)[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
  • numberOfRegisters (int): The number of registers allocated for the float. Can be 2 or 4.
Returns:
None
Raises:
ValueError, TypeError, IOError
read_string(registeraddress, numberOfRegisters=16, functioncode=3)[source]

Read a string from the slave.

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).

Args:
  • registeraddress (int): The slave register start address (use decimal numbers, not hex).
  • numberOfRegisters (int): The number of registers allocated for the string.
  • functioncode (int): Modbus function code. Can be 3 or 4.
Returns:
The string (str).
Raises:
ValueError, TypeError, IOError
write_string(registeraddress, textstring, numberOfRegisters=16)[source]

Write a string to the slave.

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).

Uses Modbus function code 16.

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

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

Returns:
None
Raises:
ValueError, TypeError, IOError
read_registers(registeraddress, numberOfRegisters, 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).
  • numberOfRegisters (int): The number of registers to read.
  • functioncode (int): Modbus function code. Can be 3 or 4.

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).
Raises:
ValueError, TypeError, 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.

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

Returns:
None
Raises:
ValueError, TypeError, IOError

Previous topic

Documentation for MinimalModbus

Next topic

API for the Eurotherm3500 example driver

This Page

Get MinimalModbus at SourceForge.net. Fast, secure and Free Open Source software downloads