Skip to content
modbus-connection

modbus-connection

A backend-neutral Modbus connection abstraction with a typed device-modelling framework on top of it.
Get startedView on GitHub

modbus-connection provides a connection abstraction and an optional device-modelling framework.

The connection abstraction is the abstract ModbusConnection class and the ModbusUnit Protocol. Your code types against these instead of a specific Modbus library. Two interchangeable backends implement them: tmodbus and pymodbus.

The device-modelling framework, modbus_connection.model, maps a device’s registers and coils to typed Python attributes. It reads the whole device, or one sub-system, in as few Modbus calls as possible.

The package imports no Modbus library at the top level and nothing from Home Assistant. You can build a device library once and let the consumer choose the backend.

Example

Section titled “Example”

Model a device once. Then construct, update, read, and write it:

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())

Connections and units

Section titled “Connections and units”

ModbusConnection

The link to a Modbus network, shared by every unit on it. The owner constructs it from a backend-neutral parameter object, and only the owner tears it down with close(). The first request connects on demand. A dropped link is re-established.

ModbusUnit

One device on that link, from connection.for_unit(unit_id). It carries the read and write operations for that unit id and holds no state. A device library receives a unit handle, never the connection.

The backend serializes requests on one connection, so concurrent unit calls cannot interleave. Many consumers can share one connection instead of each opening a competing socket. This abstraction makes that sharing possible while keeping the backend swappable.

Read more about connections and units.

Explore the docs

Section titled “Explore the docs”
Connections and unitsConnection ownership, lifecycle, and per-unit handles.
Device modellingMap registers and coils to typed attributes with Component and the built-in fields.
Built-in fieldsEvery generic field type: integers, gauges, floats, strings, enums, and coils.
SunSpecPoint types pre-wired with their unimplemented sentinels and scale-factor registers.
Building a libraryStructure a device library around components and one typed device object.
Home AssistantTurn Home Assistant Modbus YAML into components, and build an integration.