modbus-connection
A small, backend-neutral Modbus connection abstraction.
The top-level modbus_connection package provides the abstract
ModbusConnection, the ModbusUnit
Protocol, and a
tiny 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 a single, internally-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
Everything else — the other transports (UDP, serial, TLS), the full field-type and read-planning reference, repeated sub-units, the SunSpec field types and model generator, the in-memory mock backend for tests, and the exception hierarchy — lives on the website:
https://home-assistant-libs.github.io/modbus-connection/
Develop
uv sync --extra tmodbus
uv run pytest
The suite runs both backends against a real in-process Modbus server (tmodbus's,
over TCP, UDP, RTU-over-TCP, serial and TLS) rather than against mocks, so it
covers actual framing and error responses — and running the pymodbus client
against the tmodbus server checks the two implementations against each other.
tests/conftest.py has the datastore and the server helpers.
Formatting/linting is ruff and type-checking is mypy, both enforced in CI. 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
Release files for modbus-connection 4.9.0
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.9.0.tar.gz | 254.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| modbus_connection-4.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 332.1 kB
Release files / modbus_connection-4.9.0.tar.gz
| Download URL | modbus_connection-4.9.0.tar.gz |
|---|---|
| Size | 254.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7bd24e7e4581c38f5c827ef66a91aeb3234a540286ed0ea47ae41e4c1b79cc11
|
|
BLAKE2b-256 checksum How to use checksums |
8806ae0c97b9b41156051a4a76bb752ce380b0a2d6582e34b5712b962a53ffac
|
| 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 Aug 24, 2026.
Transparency logRelease files / modbus_connection-4.9.0-py3-none-any.whl
| Download URL | modbus_connection-4.9.0-py3-none-any.whl |
|---|---|
| Size | 77.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fccd39f324dac67ecbe8dbb84656d2805a0b042d851054acb9a4ceb3198e4408
|
|
BLAKE2b-256 checksum How to use checksums |
f844b7eb388d88e2fc84d8c580d98c503adfffd793dec841d79db3519151dce2
|
| 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 Aug 24, 2026.
Transparency log
