{
  "id": "brainelectronics/micropython-modbus",
  "name": "micropython-modbus",
  "prettyName": "micropython-modbus",
  "description": "MicroPython Modbus RTU Slave/Master and TCP Server/Slave library",
  "version": "",
  "author": "brainelectronics",
  "license": "GPL-3.0",
  "tags": [
    "library",
    "micropython",
    "micropython-esp32",
    "modbus",
    "modbus-master",
    "modbus-rtu",
    "modbus-slave",
    "modbus-tcp",
    "python3"
  ],
  "status": "VALID",
  "official": false,
  "source": "https://github.com/brainelectronics/micropython-modbus",
  "updatedAt": "2026-08-20T07:00:04.487Z",
  "page": "https://checkmim.com/packages/brainelectronics+micropython-modbus",
  "createdAt": "2025-05-27T04:28:56.218Z",
  "submittedBy": "oliverr",
  "install": {
    "mpremote": "mpremote mip install github:brainelectronics/micropython-modbus",
    "mip": "import mip; mip.install(\"github:brainelectronics/micropython-modbus\")"
  },
  "readme": "# MicroPython Modbus library\n\n[![Downloads](https://pepy.tech/badge/micropython-modbus)](https://pepy.tech/project/micropython-modbus)\n![Release](https://img.shields.io/github/v/release/brainelectronics/micropython-modbus?include_prereleases&color=success)\n![MicroPython](https://img.shields.io/badge/micropython-Ok-green.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/brainelectronics/micropython-modbus/actions/workflows/release.yml/badge.svg)](https://github.com/brainelectronics/micropython-modbus/actions/workflows/release.yml)\n[![Test Python package](https://github.com/brainelectronics/micropython-modbus/actions/workflows/test.yml/badge.svg)](https://github.com/brainelectronics/micropython-modbus/actions/workflows/test.yml)\n[![Documentation Status](https://readthedocs.org/projects/micropython-modbus/badge/?version=latest)](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📚 The latest documentation is available at\n[MicroPython Modbus ReadTheDocs][ref-rtd-micropython-modbus] 📚\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 | Description |\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"
}