MicroPython Modbus library

Release

MicroPython ModBus TCP and RTU library supporting client and host mode

General

Forked from Exo Sense Py (opens in a new tab), based on PyCom Modbus (opens in a new tab) and extended with other functionalities to become a powerfull MicroPython library

📚 The latest documentation is available at MicroPython Modbus ReadTheDocs (opens in a new tab) 📚

Quickstart
Usage
Supported Modbus functions
Credits

Quickstart

This is a quickstart to install the micropython-modbus library on a MicroPython board.

A more detailed guide of the development environment can be found in SETUP (opens in a new tab), further details about the usage can be found in USAGE (opens in a new tab), descriptions for testing can be found in TESTING (opens in a new tab) and several examples in EXAMPLES (opens in a new tab)

python3 -m venv .venv
source .venv/bin/activate

pip install 'rshell>=0.0.30,<1.0.0'
pip install 'mpremote>=0.4.0,<1'

Install package on board with mip or upip

rshell -p /dev/tty.SLAB_USBtoUART --editor nano

Inside the rshell (opens in a new tab) open a REPL and execute these commands inside the REPL

import machine
import network
import time
import mip
station = network.WLAN(network.STA_IF)
station.active(True)
station.connect('SSID', 'PASSWORD')
time.sleep(1)
print('Device connected to network: {}'.format(station.isconnected()))
mip.install('github:brainelectronics/micropython-modbus')
print('Installation completed')
machine.soft_reset()

For MicroPython versions below 1.19.1 use the upip package instead of mip

import machine
import network
import time
import upip
station = network.WLAN(network.STA_IF)
station.active(True)
station.connect('SSID', 'PASSWORD')
time.sleep(1)
print('Device connected to network: {}'.format(station.isconnected()))
upip.install('micropython-modbus')
print('Installation completed')
machine.soft_reset()

Request coil status

After a successful installation of the package and reboot of the system as described in the installation section the following commands can be used to request a coil state of a target/client device. Further usage examples can be found in the examples folder (opens in a new tab) and in the USAGE chapter (opens in a new tab)

TCP

from ummodbus.tcp import ModbusTCPMaster

tcp_device = ModbusTCPMaster(
    slave_ip='172.24.0.2',  # IP address of the target/client/slave device
    slave_port=502,         # TCP port of the target/client/slave device
    # timeout=5.0           # optional, timeout in seconds, default 5.0
)

# address of the target/client/slave device on the bus
slave_addr = 10
coil_address = 123
coil_qty = 1

coil_status = host.read_coils(
    slave_addr=slave_addr,
    starting_addr=coil_address,
    coil_qty=coil_qty)
print('Status of coil {}: {}'.format(coil_status, coil_address))

For further details check the latest MicroPython Modbus TCP documentation example (opens in a new tab)

RTU

from umodbus.serial import Serial as ModbusRTUMaster

host = ModbusRTUMaster(
    pins=(25, 26),      # given as tuple (TX, RX), check MicroPython port specific syntax
    # baudrate=9600,    # optional, default 9600
    # data_bits=8,      # optional, default 8
    # stop_bits=1,      # optional, default 1
    # parity=None,      # optional, default None
    # ctrl_pin=12,      # optional, control DE/RE
    # uart_id=1         # optional, see port specific documentation
)

# address of the target/client/slave device on the bus
slave_addr = 10
coil_address = 123
coil_qty = 1

coil_status = host.read_coils(
    slave_addr=slave_addr,
    starting_addr=coil_address,
    coil_qty=coil_qty)
print('Status of coil {}: {}'.format(coil_address, coil_status))

For further details check the latest MicroPython Modbus RTU documentation example (opens in a new tab)

Install additional MicroPython packages

To use this package with the provided boot.py (opens in a new tab) and main.py (opens in a new tab) file, additional modules are required, which are not part of this repo/package. To install these modules on the device, connect to a network and install them via upip as follows

# with MicroPython version 1.19.1 or newer
import mip
mip.install('github:brainelectronics/micropython-modules')

# before MicroPython version 1.19.1
import upip
upip.install('micropython-brainelectronics-helpers')

Check also the README of the brainelectronics MicroPython modules (opens in a new tab), the INSTALLATION (opens in a new tab) and the SETUP (opens in a new tab) guides.

Usage

See USAGE (opens in a new tab) and DOCUMENTATION (opens in a new tab)

Supported Modbus functions

Refer to the following table for the list of supported Modbus functions.

ID	Description
1	Read coils
2	Read discrete inputs
3	Read holding registers
4	Read input registers
5	Write single coil
6	Write single register
15	Write multiple coils
16	Write multiple registers

Credits

Big thank you to giampiero7 (opens in a new tab) for the initial implementation of this library.

sfera-labs - Initial work - giampiero7 (opens in a new tab)
pycom - Initial Modbus work - pycom-modbus (opens in a new tab)
pfalcon - Initial MicroPython unittest module - micropython-unittest (opens in a new tab)