Test Modbus with QModMaster Before Home Assistant
If your Home Assistant Modbus integration shows “unavailable” sensors, stop editing YAML for a minute. Prove the physical link works first with QModMaster — a free, open-source (LGPLv3) Modbus master simulator from the upstream project. This “verify with QModMaster first” workflow is exactly what IXON’s official support documentation recommends before configuring Modbus variables in IXON Cloud, and the same trick shows up in Home Assistant integration troubleshooting guides — for example the Sungrow SHx inverter integration’s help page tells users to check the connection with QModMaster before touching the integration config.
The Idea in One Paragraph
QModMaster talks to your device directly — no YAML, no integration layers, no polling engines. If QModMaster can read a register, your wiring, serial parameters, and device settings are correct, and whatever is broken lives in your Home Assistant configuration. If QModMaster can’t read either, the problem is below Home Assistant entirely: wiring, baud rate, parity, termination, or the wrong IP/port on a gateway. One test splits your debugging space in half.
Why Vendors Recommend This
IXON (official support documentation). Their Modbus troubleshooting article states: “Before configuring Modbus variables in IXON Cloud, it is best to determine if the variables can be read out by a Modbus master simulator tool.” It also warns: “Reading out the addresses should not give an error. If it does, make sure to resolve this before configuring the Modbus variables in IXON Cloud.” QModMaster is one of the two tools they name, and their walkthrough uses it step by step — Options > Modbus TCP, IP address and port, Unit ID (which IXON calls “Slave ID”), Connect, Function Code, Start Address, Scan. Read the IXON article.
Sungrow SHx Home Assistant integration. Its troubleshooting help page, Check #3: “If you are using Windows you can check if the Modbus connection generally works using QModMaster” — mapping Slave IP, TCP port, and Unit ID straight onto the values the integration needs. Read the help page.
The 4-Step Workflow
- 1. Connect in QModMaster. Options → Modbus TCP: enter the device or gateway IP and port (usually 502). For a direct serial adapter, Options → Modbus RTU instead (COM port, baud, parity, stop bits). Set the Unit ID — note that IXON’s docs call this field “Slave ID”; it is the same thing. Press Connect.
- 2. Read one known register. Set the Function Code (Read Input Registers 0x04 or Read Holding Registers 0x03 — your device manual decides), a Start Address you know exists, and Number of Registers = 1–4 to start. Press Scan. Values back = the link is good.
- 3. Write down the exact working parameters. Every field that made the read succeed: connection type, IP/port or COM settings, Unit ID, function code, start address, register count. These numbers are now proven facts, not guesses.
- 4. Carry them into Home Assistant verbatim. Use the mapping table below — translate each QModMaster field to its HA key and you remove an entire class of config errors.
QModMaster Field → Home Assistant Config Mapping
| QModMaster field | Home Assistant modbus key | Rule |
|---|---|---|
| Modbus TCP: IP address | host | Copy exactly (your gateway’s LAN IP). |
| Modbus TCP: port | port | Usually 502. |
| Unit ID | slave | Same number. Different tools name this differently — IXON calls it “Slave ID”. |
| Start Address | address | 0-based, like QModMaster. Copy the exact number that returned valid data. |
| Function code 04 (Read Input Registers) | input_type: input | Must match, or you read garbage. |
| Function code 03 (Read Holding Registers) | input_type: holding | Must match, or you read garbage. |
| Number of Registers → value width | data_type | 1 register = uint16/int16; 2 registers = uint32/float32. |
The golden rule: the Start Address and Function Code that returned real data in QModMaster are the numbers you put in HA. Don’t “correct” for 1-based vs 0-based conventions afterwards — you already resolved that empirically the moment the Scan succeeded. Fill the table from your verified QModMaster values, not from memory.
Three Traps When QModMaster Works but HA Doesn’t
- Slave / Unit ID mismatch. QModMaster’s Unit ID field and HA’s
slave:key must hold the same number. It is the single most common YAML mistake, and QModMaster proves the correct value in seconds — check this first. - Wrong
input_type. FC04 reads needinput_type: input; FC03 needsinput_type: holding. Mix them up and you get errors or nonsense values from a link that is actually fine. - Too-aggressive polling. HA hammers the bus with retries and tight scan intervals; some inverters and gateways simply stop answering. If QModMaster reads fine but HA logs “No response received after N retries”, loosen
scan_interval, raise the timeout, and read fewer registers per request.
FAQ
Why not debug directly in Home Assistant?
HA’s Modbus integration gives you one error for ten possible causes. QModMaster isolates the hardware link from the YAML config in minutes — that is the whole point of the workflow vendors recommend.
Do I need QModMaster on the same machine as Home Assistant?
No — but test from the same network path. If HA reaches the device through a TCP gateway, point QModMaster at that same gateway IP so you validate the real path, not a different one.
Which function code should I use?
Your device manual decides. Most inverters and energy meters expose live values as Input Registers (FC04) and settings as Holding Registers (FC03). When in doubt, try reading both in QModMaster and see which returns sane data.
An address worked in QModMaster but HA reads the wrong value.
You almost certainly miscopied something in translation. Re-check the mapping table: same Unit ID, same Start Address number, FC04 → input_type: input, FC03 → input_type: holding, and the right data_type for the value width.
