Troubleshooting

No answer at all

Connection refused. modbus-sim serve listens on 127.0.0.1:5020 by default. A master on another machine, in a VM or in a Docker container needs --host 0.0.0.0 (and the right port: 5020, not 502). Check with modbus-sim list on the simulator's machine.

Connected, but every request times out.

• Wrong framing: a master that sends RTU frames over TCP (many gateways and some SCADA drivers call it "RTU over TCP" or "encapsulated") needs --rtu-over-tcp; a plain Modbus TCP master needs the default.
• On RTU, an unknown unit ID gets no answer at all — exactly as on a real bus. modbus-sim list shows the unit IDs.
• A fault is still active: modbus-sim list shows the faults per device, modbus-sim clear <device> removes them.

Exception 0x0B (gateway target failed to respond). On Modbus TCP, a unit ID that no device has answers 0x0B, like a gateway. Check the unit ID (pymodbus: device_id=, older versions slave=).

Exception 02 (illegal data address)

• Off by one. Manuals often give 1-based register numbers (30001, 40001); the frame carries the 0-based address. Register 30071 is input 70 (0x46), 40001 is holding 0. modbus-sim map <profile> prints both columns.
• Wrong table. Input registers (function 04) and holding registers (function 03) are separate. The SDM630's measurements are input registers; the E5CC and the SunSpec map use holding registers only.
• A gap in the map. Profiles with gaps: error (the default, and sunspec-inverter) answer 02 for unmapped addresses, so a block read across a gap fails. eastron-sdm630 and omron-e5cc read gaps as 0.
• Read-only. Writing a read-only point answers 02, like many real devices.
• Half a value. A write that would change only one register of a 32- or 64-bit value answers 02.

Exception 03 (illegal data value)

• The value is outside the point's min/max (modbus-sim map shows the limits), or the request quantity is out of range (more than 125 registers in one read, 123 in one write).
• E5CC: a wrong operation command code or related information.

Exception 04 from the E5CC

Communications writing is off. Write 0x0001 to address 0x0000 (function 06) first. See Real-device profiles.

The value is nonsense

Huge or tiny floats (1.65e+24, 1.6e-23). Word order. The same four bytes, decoded with the 16-bit words swapped. The SDM630 sends ABCD (most significant register first); many other meters send CDAB. Try modbus-sim read … -t float32 -o CDAB against the device's profile to see both.

An integer that is ten or a hundred times too big. Scale. The E5CC sends tenths of a degree (1500 = 150.0 °C), SunSpec values need their scale factor register (A × 10^A_SF). --scale 0.1 in the CLI, or your client's equivalent.

65535 / -32768 / 0xFFFFFFFF on a SunSpec device. That is SunSpec's "not implemented" value, not a reading. Treat it as missing.

3276.7 on a temperature. 0x7FFF — the controller's way of saying "input error" (sensor break). The E5CC also sets bit 6 in its status word.

A negative power factor on the SDM630. Correct per Eastron's protocol: negative for inductive loads.

Values do not change, or change too slowly

• Models run on the real clock. A controller with a time constant of minutes heats for minutes; model_params: {time_scale: 10} speeds it up.
• The SunSpec inverter sleeps at night (simulated 20:00–6:00; it starts at noon). With time_scale: 120 a day passes in 12 minutes.
• A freeze fault stops all values; modbus-sim list shows it.

Serial / RTU

• --pty prints the device to open (/dev/pts/N) and only works on Linux and macOS; the name changes on every start.
• Over a pty, baud rate and parity are not simulated: any setting of the master works. On a real serial port (--serial) they must match.
• Windows: use a virtual null-modem pair (com0com) and --serial COMx.
• Unit 0 on RTU is a broadcast: writes reach every device, nobody answers.

Still stuck?

Run the request with the CLI to see the raw registers ([4366 1741]), compare with the profile (modbus-sim map), and if the simulator seems wrong, open an issue with the command, the output and the profile.