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: 2012-09-08 23:32:11 +0200 (Sat, 08 Sep 2012) $, which was $Revision: 166 $.

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)

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 /com3 (Windows).
• slaveaddress (int): Slave address in the range 1 to 247 (use decimal numbers, not hex).

serial = None

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

Attributes:

• port (str): Serial port name.

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

• baudrate (int): Baudrate in Baud.

  • Defaults to BAUDRATE.

• parity (probably int): Parity. See the pySerial module for documentation.

  • Defaults to PARITY.

• bytesize (int): Bytesize in bits.

  • Defaults to BYTESIZE.

• stopbits (int): The number of stopbits.

  • Defaults to STOPBITS.

• timeout (float): Timeout value in seconds.

  • Defaults to TIMEOUT.

address = None

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

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 .

read_bit(registeraddress, functioncode=2)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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