MicroPython Modbus library

MicroPython ModBus TCP and RTU library supporting client and host mode

---

General

Forked from Exo Sense Py, based on PyCom Modbus and extended with other functionalities to become a powerfull MicroPython library

📚 The latest documentation is available at MicroPython Modbus ReadTheDocs 📚

• Quickstart
  • Install package on board with mip or upip
  • Request coil status
    • TCP
    • RTU
  • Install additional MicroPython packages
• 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, further details about the usage can be found in USAGE, descriptions for testing can be found in TESTING and several examples in EXAMPLES

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 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 and in the USAGE chapter

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

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

Install additional MicroPython packages

To use this package with the provided boot.py and main.py 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, the INSTALLATION and the SETUP guides.

Usage

See USAGE and DOCUMENTATION

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 for the initial implementation of this library.

• sfera-labs - Initial work - giampiero7
• pycom - Initial Modbus work - pycom-modbus
• pfalcon - Initial MicroPython unittest module - micropython-unittest