Add modbus_connection integration

[balloob]

This proposal is based on expansive research covering Modbus libraries, Home Assistant integrations and configurations for the Home Assistant Modbus integration.

1. Context

Modbus is a client/server protocol: the devices are servers, and a single client polls them. A network has room for just one polling client: strictly so on serial RTU, and effectively so on the TCP gateways that bridge to it. Two Home Assistant integrations that both want to talk to devices on the same Modbus network are out of luck, because there is no second client slot, so they collide.

The only way to share a Modbus network is to put one central client in front of it and route every integration's requests through it. Today the only way to do it is using YAML to configure the existing Modbus integration. GitHub is full of examples. These could all become integrations if we had a central point to share the Modbus network: modbus_connection is that central point.

2. What modbus_connection is

The integration's interface to other integrations is a single function that returns a ModbusUnit. In pseudo-code, to show how that interface works:

async def async_get_unit(hass, connection_id, unit_id) -> ModbusUnit:
    # connection_id is a modbus_connection config entry; verify it is connected
    # return the unit

(Pseudo-code: it illustrates the interface, not the final implementation.) If the connection isn't loaded yet or has gone away, it raises ConnectionNotReady, which consumers turn into ConfigEntryNotReady.

Where do those connections come from? The integration lets a user create Modbus connections from the UI, via a config flow. A connection on its own does nothing. It is just a managed, shared client to a Modbus network, sitting ready for integrations to lease units from.

One config entry is one connection. The config flow collects only transport:

• Network: host and port, plus a framing choice between native Modbus TCP and RTU-over-TCP (what transparent serial-to-Ethernet gateways speak).
• Serial: port, baudrate, parity, and so on.

It validates by actually opening the link, then holds the live connection for the entry's lifetime. On a drop it reloads to recreate, and on unload it closes.

3. The modbus-connection library

To allow connection objects to be shared between modbus_connection (the integration that owns the connection) and the device libraries that integrations use to talk to their hardware, we created a new generic, non-HA-specific Modbus helper library called modbus-connection. Both sides speak its ModbusConnection and ModbusUnit types, so a connection opened by the integration can be handed straight to a device library that knows nothing about Home Assistant, like trovis-modbus.

It was crafted together with the Home Assistant Modbus community (Modbus under Projects on Discord), including community members making integrations for Stiebel Eltron, Trovis, Huawei, and Fronius, and the author of tmodbus, who reviewed the design and are happy with the result. It gives us connection sharing and a clean, backend-neutral abstraction (pymodbus or tmodbus behind one Protocol).

4. How an integration consumes a connection

A Modbus network is divided into units, where a unit is a distinct device on the network, addressed by its unit ID. An integration that wants to talk to a device does so through that device's unit.

A consumer integration:

1. In its config flow, picks a modbus_connection entry (ConfigEntrySelector({"integration": "modbus_connection"})) and a unit ID, and declares "dependencies": ["modbus_connection"] in its manifest.
2. In setup, asks for its unit and hands it to its device library:

from homeassistant.components.modbus_connection import async_get_unit, ConnectionNotReady
from trovis_modbus import Trovis557x   # device library, built on the ModbusUnit model

async def async_setup_entry(hass, entry):
    try:
        unit = await async_get_unit(hass, entry.data[CONF_CONNECTION], entry.data[CONF_UNIT_ID])
    except ConnectionNotReady as err:
        raise ConfigEntryNotReady from err

    device = Trovis557x(unit)        # the library consumes the unit
    await device.async_update()      # reads and decodes through it
    
    unit.on_connection_lost(lambda: reload_config_entry(entry))

    ...

What this means for the consumer:

• One call, one object. async_get_unit returns a ModbusUnit, the handle for one device. No connection object and no lifecycle to manage.
• ConnectionNotReady to ConfigEntryNotReady. If the connection isn't ready, the consumer re-raises ConfigEntryNotReady and HA retries with backoff.

5. Guarantees and constraints

• Serialized for you. Every request across every unit on a connection runs behind one lock. A consumer never coordinates with the other integrations on the link; it just awaits its call.
• Raw I/O, decoded by the device library. ModbusUnit exposes raw register and coil reads/writes (returning list[int] or list[bool]) and the full Modbus function-code set, with no typed or scaled helpers. Decoding lives in the device library (for example trovis-modbus), which consumes our ModbusUnit model.
• Typed errors, always raised. ModbusConnectionError, ModbusTimeoutError, and ModbusExceptionError (with .exception_code), all under ModbusError. Calls raise on failure; they never return None or swallow errors.
• Transient, with no silent self-heal. On a drop the connection fires on_connection_lost. This will reload the config entry. If the connection is back, the config entry will set up normally. If modbus_connection indicates the connection as being unavailable, we raise ConfigEntryNotReady and setup will automatically be retried.

6. Renaming the legacy modbus integration to "Manual Modbus"

This proposal leaves the existing YAML modbus integration untouched; sharing connections with it is out of scope. The blocker is structural: it is YAML-configured and binds register-reading tightly to the connection, so a connection can't be lifted out cleanly. Importing only the connection wouldn't help, because its entities would still live in YAML and still need their own way to read registers, which would mean rebuilding the entire generic register-to-entity builder (every platform, with addresses, data types, scaling, swaps) in the UI. That is near-impossible to do properly.

Most users of the Modbus integration are not familiar with Modbus and instead copy and paste Modbus YAML configuration from GitHub. I would want all such cases to become integrations.

The future direction I want to propose is to rename it to "Manual Modbus" and let it become a consumer of shared connections too, keeping the roll-your-own register-to-entity workflow for power users, now riding on the same managed connections. This mirrors Zigbee's history: the old zigbee integration let you wire up your own devices, and zha arrived later as the actual Zigbee smart-home spec. Likewise, modbus_connection plus purpose-built integrations is the "real" path; a renamed Manual Modbus would be the do-it-yourself path layered on top.

[balloob]

Edit: more i think about it, less is like this idea. Final thoughts in comment #1418 (reply in thread)

An alternative worth considering: instead of a separate modbus_connection integration, make the existing modbus integration config-entry based, with the hub/connection as the config entry.

Connections are config entries, created via the UI or imported from YAML. Import maps onto an existing config entry by transport identity (serial port, or host/port combo), so it's idempotent and never creates duplicates.

Entities are not imported. Manual entities stay in YAML for now and bind to the connection. No need to build config flows for every platform's large schema, and the recent PLATFORM_SCHEMAS groundwork keeps UI/subentry entities open as a later step.

Every connection is a config entry, whether UI-created or YAML-imported, so any of them is referenceable by other integrations via a ConfigEntrySelector plus unit id, which hands back a backend-neutral connection object. This is the same consumer pattern as the original proposal.
r integrations depend on.

Upside: one modbus domain instead of two, existing YAML connections migrate transparently to config entries, and the legacy DIY YAML workflow for entities is preserved.

Credit to @ThyMYthOS for pursuing this idea in home-assistant/core#174931

[Tom-Bom-badil]

I like this approach. Reusing the existing modbus domain as the central connection layer feels cleaner than introducing a second domain, and it preserves the current YAML workflow while still giving native integrations a shared, backend-neutral connection object.

The only tricky part I see is defining transport identity robustly enough to avoid both duplicates and accidentally merging distinct connections. But conceptually this sounds like a promising migration path.

Regardless of the technical approach, I think one of the biggest challenges will be convincing maintainers to adopt the shared modbus layer instead of importing backend libraries directly. As @farmio stated elsewhere, even among the existing Modbus-based integrations in core, only 3 currently depend on today’s modbus - and that does not even include all the custom/community integrations out there. So this is probably as much an adoption and documentation challenge as a technical one.

/tom

[ThyMYthOS]

Next steps

• https://github.com/ThyMYthOS/home-assistant-core/tree/modbus/lifecycle
• https://github.com/ThyMYthOS/home-assistant-core/tree/modbus/devices

[balloob]

The downside of this approach is the sheer number of features that have been added to this integration, including raw write_coil / write_register actions and struct unpacking. We don't want to pollute modbus-connection with all the legacy baggage that this integration brings.

[balloob]

Thinking about it more, its the low level access that we give users out if the box, which is a wild footgun, that i would love to keep separate.

I much prefer yaml config for modbus to consume connections from a standalone modbus connection integration