minimalmodbus

2.1.1 verified Fri May 01 auth: no python

Easy-to-use Modbus RTU and Modbus ASCII implementation for Python. Version 2.1.1 supports Python >=3.8. Released semi-regularly, with a focus on simplicity and reliability for talking to Modbus devices over serial ports.

pip install minimalmodbus

Common errors

error ValueError: The slaveaddress 0 cannot be used. ↓

cause Slave address must be between 1 and 247. Address 0 is reserved for broadcast.

fix

Use a slave address in range 1-247.

error serial.serialutil.SerialException: [Errno 2] could not open port /dev/ttyUSB0: [Errno 2] No such file or directory: '/dev/ttyUSB0' ↓

cause Serial port does not exist or is not accessible.

fix

Check the correct port name (e.g., /dev/ttyUSB0, COM3). On Linux, ensure user has dialout group permissions.

Warnings

breaking In version 2.0.0, the 'minimalmodbus' module was restructured. The 'Instrument' class now requires explicit serial configuration. Old code using positional arguments for baudrate, parity etc. must be updated. ↓

fix Set serial parameters via the instrument.serial attribute after creation.

gotcha Modbus addresses are often 1-based in documentation but minimalmodbus uses 0-based register addresses. For example, holding register 40001 in Modbus maps to register address 0 in the library. ↓

fix Subtract 1 from usual Modbus addresses.

gotcha The library does not support Modbus TCP natively; it is serial-only. Users often try to pass a hostname and port, which fails. ↓

fix Use pymodbus for Modbus TCP, or use a serial-to-TCP converter.

Imports

Instrument

wrong

import minimalmodbus; inst = minimalmodbus.Instrument(...)

correct

from minimalmodbus import Instrument

Wrong usage is uncommon but direct import is standard.

Quickstart

Quick example reading a Modbus register.

import minimalmodbus
import serial

instrument = minimalmodbus.Instrument('/dev/ttyUSB0', 1)  # port, slave address
instrument.serial.baudrate = 9600
instrument.serial.bytesize = 8
instrument.serial.parity = serial.PARITY_NONE
instrument.serial.stopbits = 1
instrument.serial.timeout = 0.5

# Read temperature (register 0, signed 16-bit)
temperature = instrument.read_register(0, 0, signed=True)
print(temperature)