modbus-connection
A backend-neutral Modbus connection abstraction for Python.
The top-level modbus_connection package provides the abstract
ModbusConnection class, the ModbusUnit
Protocol, and a
small exception hierarchy. Two interchangeable backends implement them:
tmodbus and
pymodbus. The bare install pulls
neither.
One physical Modbus link addresses many units (1–247). Many consumers can share one serialized connection instead of each opening a competing socket. This package is the connection abstraction that makes that sharing possible while keeping the backend swappable.
Install
pip install "modbus-connection[tmodbus]" # tmodbus backend
pip install "modbus-connection[pymodbus]" # pymodbus backend
Example
Model a device once, then construct, update, read, and write it. The optional
modbus_connection.model framework maps a device's registers and coils to typed
attributes and reads the whole device in as few Modbus calls as possible.
import asyncio
from modbus_connection import ModbusTcpParams
from modbus_connection.model import Component, gauge, uint32, coil
from modbus_connection.tmodbus import ModbusConnection
class Meter(Component):
voltage = gauge(0, 0.1, unit="V") # scaled 16-bit register
"""Grid voltage."""
current = gauge(1, 0.1, unit="A")
"""Grid current."""
energy = uint32(2, unit="Wh") # 32-bit over two registers
"""Lifetime energy."""
relay = coil(0, writable=True)
"""Load relay."""
async def main() -> None:
conn = ModbusConnection(ModbusTcpParams(host="192.168.1.50", port=502))
try:
meter = Meter(conn.for_unit(1))
await meter.async_update() # one pooled read per space
print(meter.voltage, meter.current, meter.energy, meter.relay)
await meter.write("relay", True) # write a writable field
finally:
await conn.close()
asyncio.run(main())
Documentation
The website documents the rest: the other transports (UDP, serial, TLS), the
field types and read planning, repeated sub-units, the Device base class for
a device library, the SunSpec field types and model generator, the in-memory
mock backend for tests, and the exception hierarchy.
https://home-assistant-libs.github.io/modbus-connection/
Develop
uv sync --extra tmodbus
uv run pytest
The suite runs both backends against an in-process tmodbus server over TCP,
UDP, RTU-over-TCP, serial and TLS, so it covers real framing and error
responses. Running the pymodbus client against the tmodbus server also checks
the two implementations against each other. tests/conftest.py has the
datastore and the server helpers.
Formatting and linting is ruff and type checking is mypy. CI enforces both. Run them locally with:
uv run mypy
Install the commit hook with prek so code is formatted on commit:
uvx prek install # set up the git hook
uvx prek run --all-files # format + lint everything now
1 maintainer
Metadata
1 maintainer
Release files for modbus-connection 4.12.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| modbus_connection-4.12.3.tar.gz | 278.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| modbus_connection-4.12.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 364.9 kB
Release files / modbus_connection-4.12.3.tar.gz
| Download URL | modbus_connection-4.12.3.tar.gz |
|---|---|
| Size | 278.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
252213d5dac1fc7b2aadcb7fd105cf3657f6432225ae42c9c15eb84d62b9fb6d
|
|
BLAKE2b-256 checksum How to use checksums |
d513f7338f692f4ca5c9d5206e47d7ac4fdf358e45fc28445b7d223a08342151
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / modbus_connection-4.12.3-py3-none-any.whl
| Download URL | modbus_connection-4.12.3-py3-none-any.whl |
|---|---|
| Size | 86.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3389426f0e71867e84cf74300439e268a4aa7bfefe798a608d04994e1483b9e6
|
|
BLAKE2b-256 checksum How to use checksums |
ff5b70976163d4b17ac645d3fb576a515ae08170bffc274b3e114178839d45a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency log
