# homeassistant-solax-modbus reads a solar inverter over RS485 and puts it in Home Assistant

> This HACS custom integration polls SolaX-style inverters over Modbus RTU and TCP and exposes the readings as Home Assistant entities, with plugins for Growatt, Sofar, SolaX and several others. Modbus single-master limits mean a multiplexer is often required.

**wills106/homeassistant-solax-modbus** — SolaX Power Modbus custom_component for Home Assistant (Supports some AlphaESS, Growatt, Sofar, Solinteg, Solis, SRNE, Swatten)

- Repository: https://github.com/wills106/homeassistant-solax-modbus
- Stars: 528 · Forks: 234
- Language: Python
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/wills106-homeassistant-solax-modbus

## It polls the inverter directly, with no vendor cloud in the loop

homeassistant-solax-modbus is a custom_component for Home Assistant that talks to solar inverters over Modbus RS485 or TCP. The description calls it a universal solar inverter integration, and the point of the whole thing is that the data comes from the inverter itself rather than from a vendor's cloud API.

That distinction matters more than it first appears. A cloud-connected integration gives you whatever the vendor chooses to expose, on the vendor's schedule, subject to the vendor's account and firmware. A Modbus integration gives you the register map of the device, which is a much larger and more precise surface, and it works on a local network with no vendor account. The cost is that you need physical hardware to talk to, and that the protocol is a low-level industrial one.

The project requires Home Assistant 2025.1.0 or newer, and the minimum version is declared in hacs.json rather than left implicit. It is distributed through HACS, with a HACS default badge in the README, and the documentation lives on Read the Docs with separate installation instructions, a general FAQ, a Sofar FAQ and a SolaX FAQ.

The declared dependencies are two, and they tell you what the transport is. pymodbus at 3.8.3 or newer handles the Modbus protocol itself, and tmodbus with the async-serial extra at 0.5.0 or newer provides the asynchronous serial layer. That is the difference between the two topologies in the topic tags: modbus-rtu and modbus-serial for the RS485 adapter, modbus-tcp for a network path.

Python 3.12 or newer is required by the packaging metadata.

## Support is a plugin per vendor, and half the list is still marked WIP

The supported hardware list is organised as collapsible sections per brand, and reading it tells you more about the project's maturity than any badge would.

Ginlong Solis covers RHI-nK-48ES-5G single phase and RHI-3PnK-HVES-5G three phase, with a note that the lowercase n indicates the inverter size, for example 6kW. Growatt covers the SPA AC battery storage, the SPH hybrid, TL-XH in MIN, MOD and MID variants, and the PV-only MAC, MAX, MID and TL-X, with SPF listed as WIP. Sofar Solar covers the HYDxxKTL-3P family through the plugin_sofar plugin, with Azzurro 3.3k-12KTL-V3 and Azzurro ZSS named, and the older HYDxxxxES range through plugin_sofar_old.

SolaX Power itself is the largest section, and it is a mix of complete and unfinished. A1 Hybrid, J1 Hybrid, Solinteg, SRNE and Swatten are all marked WIP. Gen2 Hybrid, Gen3 AC, Hybrid and RetroFit, Gen4 Hybrid and RetroFit, Gen5 Hybrid and the Viessmann HINV6.0-B1 are not marked. Several models are marked with a limited set of entities available, specifically X1 Air, Boost and Mini Gen3 and Gen4, X3 MEGA and FORTH Gen2, and X3 MIC and MIC PRO Gen1 and Gen2.

That limited set of entities is a real distinction, not a footnote. A model that appears in the list but exposes only some values is not equivalent to a fully supported model, and the README does not enumerate which entities are available for which model.

The naming convention tells you the plugin structure. The plugin_sofar and plugin_sofar_old names show that the protocol differences between inverter generations are handled by separate plugin modules rather than by one growing conditional, which is a sane way to handle the vendor register maps that differ between generations.

## Modbus single-master is the constraint that shapes your whole setup

This is the part of the documentation that will decide whether your install works, and it is stated plainly.

Modbus is designed to mostly have a single Master. If you try to connect multiple instances to the inverter, for example this integration and Node-RED, the inverter will either block the second connection or likely result in data collisions. The documentation recommends using a multiplexer in that case, and names a specific one, the tcp-multiplexer project by IngmarStein, saying it has been tested by reading and writing from two instances of Home Assistant at once.

So the failure mode is not a configuration mistake you can fix. The hardware enforces the protocol, and the symptom is either a refused connection or corrupted readings that look plausible. If you already poll the inverter from anything else, this integration will not simply work alongside it.

The workaround is a TCP multiplexer that sits between Home Assistant and the inverter. The documented example is a Docker Compose service, and the port mapping and command line are what make it work:

```yaml
services:
  modbus-proxy:
    image: ghcr.io/ingmarstein/tcp-multiplexer
    container_name: modbus_proxy
    ports:
      - "5020:5020"
    command: [ "server", "-t", "192.168.123.123:502", "-l", "5020", "-p", "modbus", "-v" ]
    restart: unless-stopped
```

The server mode listens locally and forwards to a target, the -t flag is the inverter or data logger address, -l is the local port, -p is the protocol and -v is verbose. The server address is the inverter or data logger, and you then point the integration at the machine running the proxy and port 5020 in this example.

Note that 502 is the standard Modbus port, which is why the proxy cannot also bind it on the same host, and why the local port is 5020.

## The adapter is the part most likely to be wrong

The README makes one instruction bold and links to a documentation page for it: check the docs for compatible RS485 adaptors. The topic tags list rs485 alongside modbus-rtu, modbus-serial and modbus-tcp, and the adapter type is the single most common reason a Modbus integration does not see its device.

The reason is structural. A USB-to-serial adapter is a serial port, not a Modbus bus. RS485 is a differential physical layer, so you need an adapter with an RS485 transceiver, and the bus is a daisy chain with a termination resistor at each end. A plain USB-to-TTL adapter will not talk to an inverter even if the protocol above it is Modbus, because the electrical layer is wrong.

There is also a second trap in the same family, the one the documentation's separate page on compatible adaptors exists to address. Even among genuine RS485 adapters, some ship with a driver that does not expose the port the way the integration expects, or that needs a specific baud rate and parity configured before the inverter will answer. Since the integration polls on a schedule, an adapter that enumerates late or that reassigns its device node on reconnect will show up as intermittent rather than total failure.

The project treats this as a documentation problem rather than a code problem, which is the correct call, since the hardware is outside its control. It also points at a separate troubleshooting route, with per-vendor FAQ pages for Sofar and SolaX, which is where model-specific register quirks would be documented.

For the record on scale: the integration is described as supporting some AlphaESS, Growatt, Sofar, Solinteg, Solis, SRNE and Swatten hardware, and the topic list also includes qcells, which matches the Qcells Q.VOLT HYB-G3-3P listed under the SolaX Gen4 section.

## The development setup targets a locked Python baseline and runs mypy in strict mode

The repository is set up for contributors, and the tooling tells you what the project values.

The Makefile describes itself as local CI parity for the project, with locked quality and baseline checks and dynamic Home Assistant compatibility tests. The default Python is 3.14, exported through UV_PYTHON, and the setup target runs a locked sync and installs pre-commit hooks:

```bash
	uv sync --locked --all-groups
	uv run pre-commit install
```

The lint target runs the pre-commit hooks across all files, and the mypy target runs mypy in strict mode over the integration and the tests, which is the same as CI:

```bash
	uv run mypy custom_components/solax_modbus tests --strict
```

The strict mode matters. It is a stronger guarantee than most custom integrations offer, and it applies to the tests as well as the source.

The test dependency group is where the compatibility story lives, and it is unusually explicit. There are pinned versions of homeassistant and pytest-homeassistant-custom-component for Python below 3.14 and different pinned versions for 3.14 and above, and the same split applies to pytest-asyncio. The manifest comment explains the split in the uv environments list: current Home Assistant requires Python 3.14.2 or newer, and early 3.14 patches are unsupported, so the constraint is expressed as python_full_version less than 3.14 or greater or equal to 3.14.2.

The lint configuration is also specific. Ruff runs with line-length 150, target-version py312, and a rule set of E, F, W, I, B, UP and G004, where I is import sorting, B and UP are the OSS best-practice rules, and G004 relates to logging f-strings. E501 is explicitly ignored because the formatter handles long lines. The formatter uses double quotes, space indentation, no magic trailing comma skipping and LF line endings.

The dev group also brings in codespell, and its ignore word list is a small archaeology of the domain, containing entries like hass, datas, uint and visability. The full repository is a proper uv-managed project with a uv.lock, and HACS and hassfest validation run in GitHub Actions alongside the local Makefile targets.

## Where this integration is the wrong tool

The first wrong-tool case is a multi-master setup, and that one is structural rather than fixable. If you run this integration, Node-RED and a separate monitoring script all against one inverter, you need the multiplexer, and the multiplexer adds a component that can fail in a way that is hard to diagnose from Home Assistant, since a broken proxy looks like an unresponsive inverter.

The second case is a model marked WIP. A1 Hybrid, J1 Hybrid, Solinteg, SRNE, Swatten and the Growatt SPF are all flagged, and the WIP label means the register map is not complete. An integration that reads a subset of registers can produce plausible-looking but wrong values, which is worse than an outright failure in a monitoring dashboard.

The third case is a user who wants a supported integration rather than a custom component. This is a HACS custom_component, not something in the Home Assistant core repository, so it is not covered by the core support policy, and the answer to a hardware question is a documentation site rather than a vendor.

The alternative approach is a vendor integration or a vendor cloud, and the difference in approach is worth being concrete about. A cloud integration gives you a handful of curated entities with no hardware, no RS485 wiring and no single-master constraint, at the cost of the data leaving your house and being limited to what the vendor publishes. This integration gives you the full register map, on your network, with no account, at the cost of an adapter, wiring and a protocol that assumes one client. If your inverter is already in the vendor's cloud and you only want a couple of charts, the cloud route is less work and fewer failure modes. If you want the raw numbers, or your inverter has been taken off the vendor's platform, the local Modbus route is the only one that works.

There is a middle path too, and it is the one the multiplexer example implies. Some users run the official vendor integration against the vendor cloud and use this one locally, and the multiplexer exists precisely so both can talk to the same device at once. That doubles the entities but keeps each data path independent.

## Conclusion

homeassistant-solax-modbus suits a Home Assistant user with a supported inverter and a Modbus adapter who wants battery, solar and grid figures as entities without a vendor cloud. It does not suit a setup with two integrations or Node-RED talking to the same inverter, since Modbus allows a single master and the second connection will collide. Before adopting, check the compatible RS485 adaptors page for your adapter, confirm the model and plugin combination is marked complete rather than WIP in the supported list, and plan for a multiplexer on port 5020 if anything else already polls the inverter.

## FAQ

### What does the homeassistant-solax-modbus integration support?

It is a Home Assistant custom_component that reads solar inverters over Modbus RS485 and TCP. The README lists support for some AlphaESS, Growatt, Sofar, Solinteg, Solis, SRNE and Swatten hardware, with several models marked WIP.

### What Home Assistant version does homeassistant-solax-modbus need?

Home Assistant 2025.1.0 or newer, with the minimum version declared in hacs.json. The integration is installed through HACS, and the packaging metadata requires Python 3.12 or newer.

### Can I run homeassistant-solax-modbus and Node-RED against the same inverter?

Not directly. Modbus is designed to mostly have a single master, so a second connection is blocked by the inverter or causes data collisions. The documentation recommends a multiplexer, and the server address is then the inverter or data logger with the integration pointed at port 5020 of the proxy host.

### Which RS485 adapter should I use for homeassistant-solax-modbus?

The README makes this a bolded instruction and links to a page on compatible RS485 adaptors in the documentation. The adapter matters because RS485 needs a differential transceiver rather than a plain serial converter, and the choice determines whether the integration can see the inverter at all.

## Sources

- [Issues](https://github.com/wills106/homeassistant-solax-modbus/issues)
- [License: Apache-2.0](https://github.com/wills106/homeassistant-solax-modbus/blob/main/LICENSE)
- [README](https://github.com/wills106/homeassistant-solax-modbus/blob/main/README.md)
- [Releases](https://github.com/wills106/homeassistant-solax-modbus/releases)
- [wills106/homeassistant-solax-modbus on GitHub](https://github.com/wills106/homeassistant-solax-modbus)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wills106-homeassistant-solax-modbus