Yanked

This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Consider using release 4.8.1 instead.
Reason given by maintainers: introduced a change in pooling behavior

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). Sharing a single, internally-serialized connection across many consumers is strictly better than 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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

modbus_connection-4.5.0.tar.gz (247.6 kB view details)

Uploaded Aug 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

modbus_connection-4.5.0-py3-none-any.whl (75.9 kB view details)

Uploaded Aug 11, 2026 Python 3

File details

Details for the file modbus_connection-4.5.0.tar.gz.

File metadata

Download URL: modbus_connection-4.5.0.tar.gz
Upload date: Aug 11, 2026
Size: 247.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for modbus_connection-4.5.0.tar.gz
Algorithm	Hash digest
SHA256	`e49c96ce86978e515e94e5f73b9343ec597b8228279ececcb17a18c2f088adbd`
MD5	`e0a0d7cb5df4655c6a96f41a35d528bd`
BLAKE2b-256	`a9582cfb6f901d91ec3d60400e4927b288372f4528baa5d1312d85eadb88d834`

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_connection-4.5.0.tar.gz:

Publisher: publish.yml on home-assistant-libs/modbus-connection

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: modbus_connection-4.5.0.tar.gz
- Subject digest: e49c96ce86978e515e94e5f73b9343ec597b8228279ececcb17a18c2f088adbd
- Sigstore transparency entry: 2426218978
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: home-assistant-libs/modbus-connection@ef782c0b51ebf48dcc8ab7b47065ec7140ef6c63
- Branch / Tag: refs/tags/4.5.0
- Owner: https://github.com/home-assistant-libs
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@ef782c0b51ebf48dcc8ab7b47065ec7140ef6c63
- Trigger Event: release