# MicroPython Modbus library
[](https://pepy.tech/project/micropython-modbus)
[](https://opensource.org/licenses/MIT)
[](https://github.com/brainelectronics/micropython-modbus/actions/workflows/release.yml)
[](https://github.com/brainelectronics/micropython-modbus/actions/workflows/test.yml)
[](https://micropython-modbus.readthedocs.io/en/latest/?badge=latest)
MicroPython ModBus TCP and RTU library supporting client and host mode
---------------
## General
Forked from [Exo Sense Py][ref-sferalabs-exo-sense], based on
[PyCom Modbus][ref-pycom-modbus] and extended with other functionalities to
become a powerfull MicroPython library
📚 The latest documentation is available at
[MicroPython Modbus ReadTheDocs][ref-rtd-micropython-modbus] 📚
<!-- MarkdownTOC -->
- [Quickstart](#quickstart)
- [Install package on board with mip or upip](#install-package-on-board-with-mip-or-upip)
- [Request coil status](#request-coil-status)
- [TCP](#tcp)
- [RTU](#rtu)
- [Install additional MicroPython packages](#install-additional-micropython-packages)
- [Usage](#usage)
- [Supported Modbus functions](#supported-modbus-functions)
- [Credits](#credits)
<!-- /MarkdownTOC -->
## 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](SETUP.md), further details about the usage can be found in
[USAGE](USAGE.md), descriptions for testing can be found in
[TESTING](TESTING.md) and several examples in [EXAMPLES](EXAMPLES.md)
```bash
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
```bash
rshell -p /dev/tty.SLAB_USBtoUART --editor nano
```
Inside the [rshell][ref-remote-upy-shell] open a REPL and execute these
commands inside the REPL
```python
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`
```python
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](#install-package-on-board-with-pip)
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][ref-examples-folder] and in the [USAGE chapter](USAGE.md)
#### TCP
```python
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][ref-latest-tcp-docs-example]
#### RTU
```python
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][ref-latest-rtu-docs-example]
### Install additional MicroPython packages
To use this package with the provided [`boot.py`][ref-package-boot-file] and
[`main.py`][ref-package-boot-file] 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
```python
# 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][ref-github-be-mircopython-modules], the
[INSTALLATION](INSTALLATION.md) and the [SETUP](SETUP.md) guides.
## Usage
See [USAGE](USAGE.md) and [DOCUMENTATION](DOCUMENTATION.md)
## 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][ref-giampiero7] for the initial implementation
of this library.
* **sfera-labs** - *Initial work* - [giampiero7][ref-sferalabs-exo-sense]
* **pycom** - *Initial Modbus work* - [pycom-modbus][ref-pycom-modbus]
* **pfalcon** - *Initial MicroPython unittest module* - [micropython-unittest][ref-pfalcon-unittest]
<!-- Links -->
[ref-sferalabs-exo-sense]: https://github.com/sfera-labs/exo-sense-py-modbus
[ref-pycom-modbus]: https://github.com/pycom/pycom-modbus
[ref-rtd-micropython-modbus]: https://micropython-modbus.readthedocs.io/en/latest/
[ref-remote-upy-shell]: https://github.com/dhylands/rshell
[ref-examples-folder]: https://github.com/brainelectronics/micropython-modbus/tree/develop/examples
[ref-latest-rtu-docs-example]: https://micropython-modbus.readthedocs.io/en/latest/EXAMPLES.html#rtu
[ref-latest-tcp-docs-example]: https://micropython-modbus.readthedocs.io/en/latest/EXAMPLES.html#tcp
[ref-package-boot-file]: https://github.com/brainelectronics/micropython-modbus/blob/c45d6cc334b4adf0e0ffd9152c8f08724e1902d9/boot.py
[ref-package-main-file]: https://github.com/brainelectronics/micropython-modbus/blob/c45d6cc334b4adf0e0ffd9152c8f08724e1902d9/main.py
[ref-github-be-mircopython-modules]: https://github.com/brainelectronics/micropython-modules
[ref-giampiero7]: https://github.com/giampiero7
[ref-pfalcon-unittest]: https://github.com/pfalcon/pycopy-lib/blob/56ebf2110f3caa63a3785d439ce49b11e13c75c0/unittest/unittest.py
Raw data
{
"_id": null,
"home_page": "https://github.com/brainelectronics/micropython-modbus",
"name": "micropython-modbus",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "micropython,modbus,tcp,rtu,client,host,library",
"author": "brainelectronics",
"author_email": "info@brainelectronics.de",
"download_url": "https://files.pythonhosted.org/packages/a4/00/ac6cd7ec350915f14cb0caf8fe590f181b629dcd227adc8682678e5803a8/micropython-modbus-2.3.7.tar.gz",
"platform": null,
"description": "# MicroPython Modbus library\n\n[](https://pepy.tech/project/micropython-modbus)\n\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/brainelectronics/micropython-modbus/actions/workflows/release.yml)\n[](https://github.com/brainelectronics/micropython-modbus/actions/workflows/test.yml)\n[](https://micropython-modbus.readthedocs.io/en/latest/?badge=latest)\n\nMicroPython ModBus TCP and RTU library supporting client and host mode\n\n---------------\n\n## General\n\nForked from [Exo Sense Py][ref-sferalabs-exo-sense], based on\n[PyCom Modbus][ref-pycom-modbus] and extended with other functionalities to\nbecome a powerfull MicroPython library\n\n\ud83d\udcda The latest documentation is available at\n[MicroPython Modbus ReadTheDocs][ref-rtd-micropython-modbus] \ud83d\udcda\n\n<!-- MarkdownTOC -->\n\n- [Quickstart](#quickstart)\n - [Install package on board with mip or upip](#install-package-on-board-with-mip-or-upip)\n - [Request coil status](#request-coil-status)\n - [TCP](#tcp)\n - [RTU](#rtu)\n - [Install additional MicroPython packages](#install-additional-micropython-packages)\n- [Usage](#usage)\n- [Supported Modbus functions](#supported-modbus-functions)\n- [Credits](#credits)\n\n<!-- /MarkdownTOC -->\n\n## Quickstart\n\nThis is a quickstart to install the `micropython-modbus` library on a\nMicroPython board.\n\nA more detailed guide of the development environment can be found in\n[SETUP](SETUP.md), further details about the usage can be found in\n[USAGE](USAGE.md), descriptions for testing can be found in\n[TESTING](TESTING.md) and several examples in [EXAMPLES](EXAMPLES.md)\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\n\npip install 'rshell>=0.0.30,<1.0.0'\npip install 'mpremote>=0.4.0,<1'\n```\n\n### Install package on board with mip or upip\n\n```bash\nrshell -p /dev/tty.SLAB_USBtoUART --editor nano\n```\n\nInside the [rshell][ref-remote-upy-shell] open a REPL and execute these\ncommands inside the REPL\n\n```python\nimport machine\nimport network\nimport time\nimport mip\nstation = network.WLAN(network.STA_IF)\nstation.active(True)\nstation.connect('SSID', 'PASSWORD')\ntime.sleep(1)\nprint('Device connected to network: {}'.format(station.isconnected()))\nmip.install('github:brainelectronics/micropython-modbus')\nprint('Installation completed')\nmachine.soft_reset()\n```\n\nFor MicroPython versions below 1.19.1 use the `upip` package instead of `mip`\n\n```python\nimport machine\nimport network\nimport time\nimport upip\nstation = network.WLAN(network.STA_IF)\nstation.active(True)\nstation.connect('SSID', 'PASSWORD')\ntime.sleep(1)\nprint('Device connected to network: {}'.format(station.isconnected()))\nupip.install('micropython-modbus')\nprint('Installation completed')\nmachine.soft_reset()\n```\n\n### Request coil status\n\nAfter a successful installation of the package and reboot of the system as\ndescribed in the [installation section](#install-package-on-board-with-pip)\nthe following commands can be used to request a coil state of a target/client\ndevice. Further usage examples can be found in the\n[examples folder][ref-examples-folder] and in the [USAGE chapter](USAGE.md)\n\n#### TCP\n\n```python\nfrom ummodbus.tcp import ModbusTCPMaster\n\ntcp_device = ModbusTCPMaster(\n slave_ip='172.24.0.2', # IP address of the target/client/slave device\n slave_port=502, # TCP port of the target/client/slave device\n # timeout=5.0 # optional, timeout in seconds, default 5.0\n)\n\n# address of the target/client/slave device on the bus\nslave_addr = 10\ncoil_address = 123\ncoil_qty = 1\n\ncoil_status = host.read_coils(\n slave_addr=slave_addr,\n starting_addr=coil_address,\n coil_qty=coil_qty)\nprint('Status of coil {}: {}'.format(coil_status, coil_address))\n```\n\nFor further details check the latest\n[MicroPython Modbus TCP documentation example][ref-latest-tcp-docs-example]\n\n#### RTU\n\n```python\nfrom umodbus.serial import Serial as ModbusRTUMaster\n\nhost = ModbusRTUMaster(\n pins=(25, 26), # given as tuple (TX, RX), check MicroPython port specific syntax\n # baudrate=9600, # optional, default 9600\n # data_bits=8, # optional, default 8\n # stop_bits=1, # optional, default 1\n # parity=None, # optional, default None\n # ctrl_pin=12, # optional, control DE/RE\n # uart_id=1 # optional, see port specific documentation\n)\n\n# address of the target/client/slave device on the bus\nslave_addr = 10\ncoil_address = 123\ncoil_qty = 1\n\ncoil_status = host.read_coils(\n slave_addr=slave_addr,\n starting_addr=coil_address,\n coil_qty=coil_qty)\nprint('Status of coil {}: {}'.format(coil_address, coil_status))\n```\n\nFor further details check the latest\n[MicroPython Modbus RTU documentation example][ref-latest-rtu-docs-example]\n\n### Install additional MicroPython packages\n\nTo use this package with the provided [`boot.py`][ref-package-boot-file] and\n[`main.py`][ref-package-boot-file] file, additional modules are required,\nwhich are not part of this repo/package. To install these modules on the\ndevice, connect to a network and install them via `upip` as follows\n\n```python\n# with MicroPython version 1.19.1 or newer\nimport mip\nmip.install('github:brainelectronics/micropython-modules')\n\n# before MicroPython version 1.19.1\nimport upip\nupip.install('micropython-brainelectronics-helpers')\n```\n\nCheck also the README of the\n[brainelectronics MicroPython modules][ref-github-be-mircopython-modules], the\n[INSTALLATION](INSTALLATION.md) and the [SETUP](SETUP.md) guides.\n\n## Usage\n\nSee [USAGE](USAGE.md) and [DOCUMENTATION](DOCUMENTATION.md)\n\n## Supported Modbus functions\n\nRefer to the following table for the list of supported Modbus functions.\n\n| ID |\u00a0Description |\n|----|-------------|\n| 1 | Read coils |\n| 2 | Read discrete inputs |\n| 3 | Read holding registers |\n| 4 | Read input registers |\n| 5 | Write single coil |\n| 6 | Write single register |\n| 15 | Write multiple coils |\n| 16 | Write multiple registers |\n\n## Credits\n\nBig thank you to [giampiero7][ref-giampiero7] for the initial implementation\nof this library.\n\n* **sfera-labs** - *Initial work* - [giampiero7][ref-sferalabs-exo-sense]\n* **pycom** - *Initial Modbus work* - [pycom-modbus][ref-pycom-modbus]\n* **pfalcon** - *Initial MicroPython unittest module* - [micropython-unittest][ref-pfalcon-unittest]\n\n<!-- Links -->\n[ref-sferalabs-exo-sense]: https://github.com/sfera-labs/exo-sense-py-modbus\n[ref-pycom-modbus]: https://github.com/pycom/pycom-modbus\n[ref-rtd-micropython-modbus]: https://micropython-modbus.readthedocs.io/en/latest/\n[ref-remote-upy-shell]: https://github.com/dhylands/rshell\n[ref-examples-folder]: https://github.com/brainelectronics/micropython-modbus/tree/develop/examples\n[ref-latest-rtu-docs-example]: https://micropython-modbus.readthedocs.io/en/latest/EXAMPLES.html#rtu\n[ref-latest-tcp-docs-example]: https://micropython-modbus.readthedocs.io/en/latest/EXAMPLES.html#tcp\n[ref-package-boot-file]: https://github.com/brainelectronics/micropython-modbus/blob/c45d6cc334b4adf0e0ffd9152c8f08724e1902d9/boot.py\n[ref-package-main-file]: https://github.com/brainelectronics/micropython-modbus/blob/c45d6cc334b4adf0e0ffd9152c8f08724e1902d9/main.py\n[ref-github-be-mircopython-modules]: https://github.com/brainelectronics/micropython-modules\n[ref-giampiero7]: https://github.com/giampiero7\n[ref-pfalcon-unittest]: https://github.com/pfalcon/pycopy-lib/blob/56ebf2110f3caa63a3785d439ce49b11e13c75c0/unittest/unittest.py\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MicroPython ModBus TCP and RTU library supporting client and host mode",
"version": "2.3.7",
"project_urls": {
"Bug Reports": "https://github.com/brainelectronics/micropython-modbus/issues",
"Homepage": "https://github.com/brainelectronics/micropython-modbus",
"Source": "https://github.com/brainelectronics/micropython-modbus"
},
"split_keywords": [
"micropython",
"modbus",
"tcp",
"rtu",
"client",
"host",
"library"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a400ac6cd7ec350915f14cb0caf8fe590f181b629dcd227adc8682678e5803a8",
"md5": "382f23d5ceb34b4e568c0064cf03521c",
"sha256": "b9351a66af0ff29dd585900e53827a989dedcb02ec63b1041358165089652271"
},
"downloads": -1,
"filename": "micropython-modbus-2.3.7.tar.gz",
"has_sig": false,
"md5_digest": "382f23d5ceb34b4e568c0064cf03521c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26321,
"upload_time": "2023-07-19T20:58:31",
"upload_time_iso_8601": "2023-07-19T20:58:31.513511Z",
"url": "https://files.pythonhosted.org/packages/a4/00/ac6cd7ec350915f14cb0caf8fe590f181b629dcd227adc8682678e5803a8/micropython-modbus-2.3.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-19 20:58:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "brainelectronics",
"github_project": "micropython-modbus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "esptool",
"specs": []
},
{
"name": "rshell",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.0.30"
]
]
},
{
"name": "mpremote",
"specs": [
[
"<",
"1"
],
[
">=",
"0.4.0"
]
]
}
],
"lcname": "micropython-modbus"
}
JSON
