Repository navigation
Local Modbus RS485
In Development. Telemetry, diagnostics, and settings reads work reliably over both supported families.
As an alternative to the HYXI Cloud API, the integration can talk directly to one inverter over RS485 Modbus:
- No developer account, no Access/Secret Key, no internet dependency.
- Polls far faster than the cloud allows.
- Gives access to some settings the cloud API doesn't expose control for.
- Trade-off: only one device (no multi-device discovery, no real-time push, no remote access away from your LAN).
| Family | Models | Register map source |
|---|---|---|
| Hybrid Inverter | HYX-H(5~12)K-HT (incl. H10K-HT), HYX-H(15~25)K-HT, HYX-H(6~15)K-HTA, HYX-H(6~15)K-HTAC | HYXIPower RS485_MODBUS RTU Hybrid Inverter Protocol, V4.1 |
| Micro ESS (HALO) | HYX-MS3000AC | HYXIPower Micro Storage RS485 MODBUS protocol, V1.0 |
Both maps cover live telemetry (grid/off-grid power, PV strings, battery/BMS detail, energy counters) and — once you enable Device Control & Protection — the mode buttons (Idle / Charge / Discharge / Self-Consume), Charge/Discharge Power numbers, the Battery Dispatch Control switch, and a slice of hardware settings (feed-in power limit, SOC setpoints, anti-starvation, plus power on/off/restart buttons on Hybrid) as number and switch entities. The settings block is re-read hourly, and a Refresh Settings button forces an immediate re-read after you change something from the HYXI app or another Modbus master. See Device Control for the full per-family control list, and Local Energy Manager — which runs over Modbus too, including on a HALO.
Every register's provenance — which vendor document it came from, what's confirmed against real hardware vs. inferred, and known caveats — is tracked in docs/modbus-provenance.md in the repo. That file is the source of truth if a value looks wrong; this page is just the setup guide.
| Family | Connector | Pins | Serial settings |
|---|---|---|---|
| Hybrid Inverter | Inverter's COM port (RJ45) | PIN5 = RS485 A (white/blue), PIN6 = RS485 B (green); other pins unused | 115200bps, no parity, 8 data bits, 1 stop bit |
| Micro ESS (HALO) | RJ45 in a circular weatherproof housing (not in HYXI's protocol document) | PIN7 = RS485 A (white/brown), PIN8 = RS485 B (brown); other pins unused (from HYXI, not in the protocol document — see below) | 115200bps, no parity, 8 data bits, 1 stop bit |
Both families also require a minimum gap between messages before the next one — Hybrid: >500ms, HALO: >200ms — which the integration applies automatically once it detects your family, so it's nothing you need to configure, but it's worth knowing if you're troubleshooting timeouts on a slower adapter.
From HYXI's RS485_MODBUS RTU Hybrid Inverter Protocol V4.1. Note that pins 5 and 6 are not a single twisted pair in a T568B cable (the blue pair is 4/5, the green pair is 3/6), so for anything beyond a short run, land one dedicated twisted pair on pins 5 and 6 rather than using a straight patch cable as-is.
HALO's pinout isn't in HYXI's own protocol document — that gives only the serial parameters above, no pin numbers, no connector type. The PIN7/8 assignment comes from issue #662 and a matching Home Assistant community post, from the contributor who supplied the HALO protocol document itself, relaying HYXI's answers. HYXI has given it twice: first as "PIN7 = A, PIN8 = B … white-brown and brown", then — on a re-confirmation request — as "from right to left, first pin 485B then 485A, other pins idle", which is the same pair counted from the other end. So A on the white-brown wire, B on the brown wire, nothing else connected; the port is a normal RJ45 inside a circular weatherproof shell, so the T568B colours apply. Many HALO owners now run the integration over Modbus day to day. Don't assume the HALO matches the Hybrid's PIN5/6 layout. Getting A/B backwards won't damage anything — if the bus doesn't enumerate, swap them.
You don't need to know your exact inverter family or wire framing ahead of time — the integration probes the bus during setup and detects both automatically.
- Wire your RS485 adapter to the inverter per the table above.
- Go to Settings > Devices & Services > Add Integration > HYXI.
- Choose Local Modbus (RS485, no account) as the transport.
- Choose your connection type:
- Serial port — a USB RS485 adapter plugged directly into the Home Assistant host. Enter the device path and baud rate.
- Modbus TCP gateway — an RS485-to-Ethernet adapter. See Configuring a TCP gateway below.
- Enter the slave address (unit ID) — 1 is the usual default.
- Submit. The integration probes the bus, identifies the family, and creates the matching entities.
If you're using an RS485-to-Ethernet gateway rather than a USB adapter, its serial side needs to match the table above — 115200bps, no parity, 8 data bits, 1 stop bit for either family. Beyond that:
- Protocol/mode — either works, and both are detected automatically: a gateway that speaks native Modbus-TCP/MBAP framing and translates to RTU on the wire (e.g. Waveshare's "Modbus TCP to RTU") is tried first, then a transparent/passthrough gateway that just tunnels raw RTU frames over TCP (e.g. Waveshare's "Protocol: None"). You don't need to know which yours is, but if your gateway lets you pick, the MBAP-translating mode gets identified fastest.
- Port — 502 is the Modbus-TCP default; use whatever the gateway is actually configured to.
- Slave/unit ID — must match the inverter's own Modbus address, not an address you invent for the gateway. Both families default to 1: Hybrid's address lives in register 3121, HALO's in register 4004 — change it on the inverter/HALO itself first if you need something else.
- Battery control is local-only. HYXI's cloud doesn't forward battery commands sent with owners' API keys (see Device Control). Over local Modbus that restriction doesn't apply: both the HALO and the Hybrid get the mode buttons (Idle/Charge/Discharge/Self-Consume) and charge/discharge power numbers — on the HALO driven by the register map's VPP dispatch block — plus the Local Energy Manager.
- Battery Dispatch Control releases the battery — except on a restart. Turning the switch off, disabling Device Control, or deleting the entry hands the battery back to the inverter's own work mode. A Home Assistant shutdown or restart does not — whatever mode was last set stays active until HA comes back and takes over again.
-
Some writes are still being validated against hardware. Reads are reliable on both families; the control writes are documented but not all confirmed on a live unit.
docs/modbus-provenance.mdtracks what's confirmed vs. inferred, including whether clearing dispatch cleanly resumes the configured work mode on a real HALO.
- Wrong device type, sensors stuck at zero, or the bus won't come up — Local Modbus Troubleshooting has a read-only diagnostic script and a checklist.
-
docs/modbus-provenance.md— per-register provenance: which document each value came from, confirmed vs. inferred, wiring/pinout detail, and known caveats. - Available Sensors and Local Energy Manager for what you get once it's connected.