Skip to content

Local Modbus Troubleshooting

Jump to bottom
Veldkornet edited this page Sep 3, 2026 · 2 revisions

🔍 Local Modbus — Troubleshooting

For the Local Modbus (RS485) transport only — see Local Modbus RS485 for setup. Cloud problems are on Troubleshooting.

The usual failure isn't a crash — it's a device that connects but reads wrong: it comes up as the wrong inverter type, or every sensor sits at 0. This page is about pinning down why, using a small read‑only script.

Is this you?

Symptom Likely meaning
Device type is Hybrid Inverter but you have a HALO (HYX‑MS3000AC), or vice‑versa The family was mis‑detected, so the wrong register map is being used
The Modbus service device is connected, but the inverter device's sensors are all 0, serial number 0, firmware 0 Same thing — the client is reading a map the device doesn't answer
Setup fails with "Nothing answered on the bus" or "could not reach the Modbus device" Wiring, slave address, baud rate, or framing — the bus never came up

Background: how the family is chosen

At setup the integration reads one signature register per family and looks at what comes back:

Family Register Expected
Micro ESS (HALO) input 4100 a power on/off state (0 or 1)
Hybrid Inverter input 0 a communication‑protocol version (a positive number)

HALO is checked first. The two documents' address ranges don't overlap (hybrid tops out at 3121, HALO starts at 4000), so normally only one answers — and a HALO whose battery/BMS is offline still answers input 4100, which is why detection keys off that rather than a BMS register.

Detection only runs when the Modbus device is added or reconfigured — never on an integration update or a Home Assistant restart. If you set the device up on an older version and then upgraded, the family stored back then is still in use. Remove and re‑add the Modbus device (or use its Reconfigure option) to re‑run detection on the current version.

The family‑check script

tools/hyxi_family_check.py reads those two registers plus some surrounding context, replays the detection rule, and tells you which family it would land on and why. It is read‑only — every request is a register read, there is no code path that writes.

It needs only Python 3.9+ (no pip install), so it runs from a PC on the same network or from Home Assistant's Advanced SSH & Web Terminal add‑on.

# grab it
wget https://raw.githubusercontent.com/Veldkornet/ha-hyxi-cloud/main/tools/hyxi_family_check.py

# run it against your gateway  (host, then optional port and unit id)
python3 hyxi_family_check.py 192.168.1.50 502 1 --expect halo

Pass --expect halo or --expect hybrid (the family you think it is) and the report ends with a MATCH / MISMATCH line. Only a TCP gateway is supported here; for a direct USB adapter use tools/modbus_probe.py detect from a repo checkout instead.

Copy the whole REPORT section it prints into your issue.

Reading the report

The verdict block is the part that matters:

VERDICT (framer 'socket'):

  halo    signature  input 4100  [power on/off state]: value 1 (0x0001)
  hybrid  signature  input 0     [communication protocol version]: exception -- IllegalDataAddress

  -> the integration would detect this device as: HALO
     because input register 4100 answered with 1, a plausible power on/off state
What you see What it means What to do
Verdict matches your device, but HA still shows the wrong type Stored family is stale — detection ran on an older version Remove & re‑add the Modbus device, or Reconfigure it
HALO and you have a HALO, or HYBRID and you have a hybrid Detection is correct; if sensors are still 0, re‑add the device so the stored family updates Remove & re‑add
input 4100 shows malformed / raw bytes: … 01 04 00 and the verdict is HYBRID A hybrid answers the HALO signature with an empty frame — expected, and the verdict is right Nothing
HYBRID but you have a HALO, and input 4100 shows an exception or no reply This HALO isn't answering input 4100 — unusual Post the whole report on the issue
UNIDENTIFIED — reachable but neither signature plausible Something is on the bus but it isn't a HALO or a hybrid at this address Check the slave / unit id (--unit)
could not open a TCP connection Wrong IP or port, or the gateway is down / firewalled Use the gateway's IP and port, not the inverter's
could not talk to a Modbus device on either framing TCP is fine, the RS485 side is not See below

Older releases checked the hybrid register first and keyed the HALO check off the BMS state‑of‑charge (input 4980). A HALO with an offline battery answered nothing there but did answer input 0, so it came up as a Hybrid Inverter with every sensor at 0. If that's you, update and re‑add the device.

"Nothing answered on the bus"

TCP to the gateway works, but nothing behind it replies. In rough order of likelihood:

  1. Wrong slave / unit id. Try --unit 1 … up to 247. Hybrid's address is in register 3121, HALO's in 4004.
  2. A and B (D+ / D−) swapped. Very common. It can't be detected over Modbus — it looks identical to silence. On an idle bus, a multimeter across A–B reads about +2 to +5 V DC; a negative reading means the pair is reversed. Nothing is damaged by getting it wrong — just swap them.
  3. Baud rate mismatch in the gateway's own web page. Every HYXI inverter uses 115200 bps, 8 data bits, no parity, 1 stop bit.
  4. A and B not actually on the gateway's A/B terminals, or the wrong RJ45 pins at the inverter — see the pinout tables on Local Modbus RS485.
  5. Wrong wire framing, if you forced one with --framer. Drop the flag and it tries both.
  6. Inverter RS485 port not enabled, or the inverter asleep (HALO/hybrid can stop answering at night).

See also

Clone this wiki locally