modbus-sim 0.1.0__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. modbus_sim-0.2.1/CHANGELOG.md +51 -0
  2. {modbus_sim-0.1.0/src/modbus_sim.egg-info → modbus_sim-0.2.1}/PKG-INFO +107 -11
  3. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/README.md +106 -10
  4. modbus_sim-0.2.1/examples/real-devices.yaml +9 -0
  5. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/pyproject.toml +1 -1
  6. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/__init__.py +1 -1
  7. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/datatypes.py +2 -2
  8. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/device.py +1 -1
  9. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/faults.py +3 -0
  10. modbus_sim-0.2.1/src/modbus_sim/models.py +719 -0
  11. modbus_sim-0.2.1/src/modbus_sim/profiles/eastron-sdm630.yaml +233 -0
  12. modbus_sim-0.2.1/src/modbus_sim/profiles/omron-e5cc.yaml +81 -0
  13. modbus_sim-0.2.1/src/modbus_sim/profiles/sunspec-inverter.yaml +136 -0
  14. {modbus_sim-0.1.0 → modbus_sim-0.2.1/src/modbus_sim.egg-info}/PKG-INFO +107 -11
  15. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/SOURCES.txt +5 -0
  16. modbus_sim-0.2.1/tests/test_device_profiles.py +269 -0
  17. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_profile.py +2 -1
  18. modbus_sim-0.1.0/CHANGELOG.md +0 -24
  19. modbus_sim-0.1.0/src/modbus_sim/models.py +0 -431
  20. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/LICENSE +0 -0
  21. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/MANIFEST.in +0 -0
  22. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/examples/plant.yaml +0 -0
  23. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/examples/test_example.py +0 -0
  24. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/setup.cfg +0 -0
  25. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/__main__.py +0 -0
  26. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/bench.py +0 -0
  27. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/cli.py +0 -0
  28. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/client.py +0 -0
  29. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/control.py +0 -0
  30. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/frame.py +0 -0
  31. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/profile.py +0 -0
  32. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/profiles/energy-meter.yaml +0 -0
  33. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/profiles/temperature-controller.yaml +0 -0
  34. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/profiles/vfd.yaml +0 -0
  35. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/pytest_plugin.py +0 -0
  36. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/server.py +0 -0
  37. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/signals.py +0 -0
  38. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/dependency_links.txt +0 -0
  39. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/entry_points.txt +0 -0
  40. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/requires.txt +0 -0
  41. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/top_level.txt +0 -0
  42. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/conftest.py +0 -0
  43. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_cli.py +0 -0
  44. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_datatypes.py +0 -0
  45. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_device.py +0 -0
  46. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_frame.py +0 -0
  47. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_models.py +0 -0
  48. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_plugin.py +0 -0
  49. {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_server.py +0 -0
@@ -0,0 +1,51 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## 0.2.1 - 2026-11-05
8
+
9
+ - Docker image on `ghcr.io/steitec/modbus-sim`: runs the profiles after real
10
+ devices on Modbus TCP, with the control channel for fault injection
11
+
12
+ ## 0.2.0 - 2026-11-01
13
+
14
+ - Profiles after the published register maps of real devices:
15
+ `eastron-sdm630` (Eastron SDM630 protocol V1.5, float32 ABCD, input and set-up
16
+ registers), `omron-e5cc` (Omron E5CC two-byte mode with status words, operation
17
+ commands and the communications-writing enable) and `sunspec-inverter` (SunSpec models 1 and
18
+ 103 with scale factors)
19
+ - New model `pv_inverter`: day curve, SunSpec operating states and event bits,
20
+ faults `grid_loss`, `ground_fault`, `over_temp`
21
+ - `energy_meter` model: apparent and reactive power per phase, phase angles,
22
+ averages, neutral current, per-phase import/export/total kWh and kvarh, kVAh,
23
+ Ah, demand values with maxima; parameters `pf_sign` and `demand_period`
24
+ - `temperature_controller` model: operation command register, an optional
25
+ write enable (`comms_write`) and the Omron E5@C status words
26
+ - A model can refuse a write with exception 04 instead of 03 (the E5CC answers
27
+ 04, operation error, while communications writing is off)
28
+ - Browser demo at https://modbus-sim.steitec.net (`web/`): the three real-device
29
+ profiles in Pyodide with a Modbus terminal that shows the TCP frames, live device
30
+ fronts and fault buttons; example bench `examples/real-devices.yaml`
31
+ - Fixed: the word order table named Eastron among CDAB devices; Eastron meters
32
+ send the most significant register first (ABCD)
33
+
34
+ ## 0.1.0 - 2026-10-31
35
+
36
+ - Modbus TCP, RTU over TCP, and RTU on a serial port (pyserial) or a virtual
37
+ serial port (pty, Linux/macOS); several devices by unit ID behind one server,
38
+ RTU broadcast
39
+ - Function codes 01-08 (08: sub-function 00), 15, 16, 22, 23 and 43/14 (device
40
+ identification) with the exceptions of the specification
41
+ - YAML profiles: points with type (16/32/64-bit integers, floats, strings, bits),
42
+ word order (ABCD/CDAB/BADC/DCBA), scale, access, limits, signal sources
43
+ - Bundled devices with behaviour: `energy-meter`, `temperature-controller`, `vfd`
44
+ - Bench files for several devices with per-device overrides
45
+ - Fault injection (`no_response`, `delay`, `exception`, `busy`, `drop_connection`,
46
+ `bad_crc`, `wrong_transaction`, `wrong_unit`, `truncate`, `freeze`, `drift`, `trip`,
47
+ `sensor_break`, `phase_loss`) through a JSON control channel and the CLI
48
+ - Command line (`serve`, `profiles`, `map`, `read`, `write`, `ident`, `inject`, `clear`,
49
+ `get`, `set`, `list`) and a small Python client
50
+ - pytest plugin with the `modbus_bench` and `modbus_bench_factory` fixtures
51
+ - Test suite cross-checks the simulator against pymodbus
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: modbus-sim
3
- Version: 0.1.0
3
+ Version: 0.2.1
4
4
  Summary: Simulated Modbus devices with behaviour and fault injection: energy meter, temperature controller, VFD over Modbus TCP and RTU
5
5
  Author: Ralf Steinert
6
6
  License-Expression: MIT
@@ -42,17 +42,25 @@ Dynamic: license-file
42
42
  # modbus-sim
43
43
 
44
44
  [![CI](https://github.com/steitec/modbus-sim/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/steitec/modbus-sim/actions/workflows/ci.yml)
45
- [![PyPI](https://img.shields.io/pypi/v/modbus-sim)](https://pypi.org/project/modbus-sim/)
46
- [![Python](https://img.shields.io/pypi/pyversions/modbus-sim)](https://pypi.org/project/modbus-sim/)
47
- [![License](https://img.shields.io/pypi/l/modbus-sim)](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
45
+ [![PyPI](https://img.shields.io/pypi/v/modbus-sim?v=0.2.1)](https://pypi.org/project/modbus-sim/)
46
+ [![Python](https://img.shields.io/pypi/pyversions/modbus-sim?v=0.2.1)](https://pypi.org/project/modbus-sim/)
47
+ [![License](https://img.shields.io/pypi/l/modbus-sim?v=0.2.1)](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
48
+ [![Demo](https://img.shields.io/badge/demo-live%20in%20your%20browser-2ea44f)](https://modbus-sim.steitec.net)
48
49
 
49
50
  Simulated Modbus devices that **behave**: an energy meter whose counters count,
50
51
  a temperature controller that heats towards its setpoint, a frequency converter
51
- that ramps up when you set the run bit and trips when you tell it to. They speak
52
+ that ramps up when you set the run bit and trips when you tell it to. Three
53
+ profiles follow the published register maps of real devices: an Eastron SDM630
54
+ energy meter, an Omron E5CC temperature controller and a SunSpec PV inverter.
55
+ **[Try them in your browser](https://modbus-sim.steitec.net)**, no install needed.
56
+ They speak
52
57
  Modbus TCP, RTU over TCP and RTU on a serial line or a virtual serial port, so
53
58
  you can develop and test SCADA links, data loggers, gateways, Node-RED flows or
54
59
  your own Modbus code without the hardware, also in CI.
55
60
 
61
+ Walkthroughs, CI recipes and troubleshooting are in the
62
+ [wiki](https://github.com/steitec/modbus-sim/wiki); this README is the reference.
63
+
56
64
  ```console
57
65
  $ modbus-sim serve --bench examples/plant.yaml &
58
66
  modbus-sim: 3 devices (units 1, 2, 3) on modbus tcp 127.0.0.1:5020, control on :5021
@@ -137,6 +145,37 @@ such as com0com.
137
145
  | `energy-meter` | three-phase meter: voltages, currents, powers, power factor, frequency, energy import/export | float32 in **CDAB** word order, Wh counters as uint64, reset coil |
138
146
  | `temperature-controller` | PI controller heating a first-order process; run/stop, auto/manual, alarm limits | int16 scaled by 0.1; sensor break reads 3276.7 (0x7FFF) |
139
147
  | `vfd` | frequency converter: control word, speed reference, accel/decel ramps, status word, current, voltage, rpm, run hours | trip is latched until a fault reset (rising edge) and a new run edge |
148
+ | `eastron-sdm630` | Eastron SDM630 three-phase meter: the full input register map of protocol V1.5 (volts, amps, powers, power factor, phase angle, THD, demand, per-phase import/export kWh and kvarh) and the set-up holding registers | float32 in **ABCD**, input registers 30001 ff.; unlisted addresses read 0 |
149
+ | `omron-e5cc` | Omron E5CC temperature controller in two-byte mode: PV, status, set point, MV, manual MV, operation commands (run/stop, auto/manual, write mode) | writes answer exception 04 until **communications writing** is switched on with operation command 0x0001 |
150
+ | `sunspec-inverter` | three-phase PV inverter with the SunSpec map that SMA, Fronius, SolarEdge and others publish: model 1 (common) + model 103, on a day curve | "SunS" at 40000, integer + scale-factor registers, SunSpec states and event bits |
151
+
152
+ ### Profiles after real devices
153
+
154
+ `eastron-sdm630`, `omron-e5cc` and `sunspec-inverter` are built from public
155
+ documentation, so code written against them should work against the real
156
+ device's register map:
157
+
158
+ | profile | source | simplified |
159
+ |---|---|---|
160
+ | `eastron-sdm630` | Eastron "SDM630 Modbus Protocol" V1.5 | odd register counts and requests over 80 registers are accepted; THD is constant with noise; demand is an exponential average; set-up registers are stored only (no password, restart or register-order switching); a `reset_energy` coil is added |
161
+ | `omron-e5cc` | Omron "E5@C Communications Manual" (H175), sections 3-2, 4 and 5 | two-byte mode only; status sets only the bits the model knows (input error, control output, write mode, run/stop, communications writing, auto/manual); no heater current, alarm values or status 2; commands other than communications writing, run/stop, auto/manual and write mode are accepted without effect |
162
+ | `sunspec-inverter` | SunSpec model definitions (github.com/sunspec/models) | fixed scale factors; no control models (120-127); generic manufacturer "steitec" |
163
+
164
+ Each was checked against a third-party client: `sdm_modbus` reads the
165
+ simulated SDM630, and the SunSpec Alliance's `pysunspec2` scans and decodes
166
+ the inverter. steitec is not affiliated with Eastron, Omron or the SunSpec
167
+ Alliance; product names identify the documented register maps only. Firmware
168
+ versions of real devices differ, so check your device's documentation.
169
+
170
+ ```console
171
+ $ modbus-sim serve omron-e5cc &
172
+ $ modbus-sim write holding 0x2103 100 --scale 0.1 # refused: exception 04
173
+ $ modbus-sim write holding 0 0x0001 # communications writing on
174
+ $ modbus-sim write holding 0x2103 100 --scale 0.1 # set point 100.0 degC
175
+ $ modbus-sim serve sunspec-inverter --port 5030 \
176
+ --control-port 5031 &
177
+ $ modbus-sim read holding 40000 -c 2 -t string --port 5030
178
+ ```
140
179
 
141
180
  `modbus-sim map PROFILE` prints the complete register map, with the 0-based
142
181
  protocol address and the conventional reference (`400001` = holding
@@ -192,8 +231,9 @@ points:
192
231
  - **min/max**: written values outside are exception 03
193
232
  - **sources**: `constant` (value), `ramp` (start, stop, period), `sine`
194
233
  (offset, amplitude, period), `noise` (sigma); a list is added up
195
- - **model**: the three bundled profiles bind points to a model with
196
- `model: <variable>`; `model_params` tune it (`time_scale` speeds any model up)
234
+ - **model**: the bundled profiles bind points to a model (`energy_meter`,
235
+ `temperature_controller`, `vfd`, `pv_inverter`) with `model: <variable>`;
236
+ `model_params` tune it (`time_scale` speeds any model up)
197
237
  - **bits**: names for the bits of a uint16 register (shown by `map`)
198
238
 
199
239
  A point named `exception_status` provides the byte returned by function 07.
@@ -232,7 +272,8 @@ the bench file.
232
272
  Anything else answers exception 01. Exceptions follow the specification:
233
273
  02 for unmapped or read-only addresses and for writes that would change only
234
274
  part of a 32/64-bit value, 03 for bad quantities, byte counts and values
235
- outside `min`/`max`.
275
+ outside `min`/`max`, 04 where a device refuses a write in its present state
276
+ (`omron-e5cc` with communications writing off).
236
277
 
237
278
  **Unit IDs.** On Modbus TCP an unknown unit answers exception 0x0B (gateway
238
279
  target failed to respond); a single device also answers unit 0 and 255. On
@@ -260,7 +301,10 @@ clear DEVICE [FAULT]`:
260
301
  | `drift` | point, per_second | a numeric point runs away |
261
302
  | `trip` | code=1 | `vfd`: fault trip, coasts to stop, latched until reset |
262
303
  | `sensor_break` | | `temperature-controller`: PV reads 3276.7, output off, alarm |
263
- | `phase_loss` | phase | `energy-meter`: that phase reads 0 V, 0 A |
304
+ | `phase_loss` | phase | `energy-meter`, `eastron-sdm630`: that phase reads 0 V, 0 A |
305
+ | `grid_loss` | | `sunspec-inverter`: state 7 (fault), event bit 4, AC values 0 |
306
+ | `ground_fault` | | `sunspec-inverter`: state 7 (fault), event bit 0 |
307
+ | `over_temp` | | `sunspec-inverter`: state 5 (throttled) at half power, event bit 7 |
264
308
 
265
309
  ## Control channel
266
310
 
@@ -279,6 +323,55 @@ only, no authentication). It takes one JSON object per line:
279
323
  set `null`); the CLI has the same as `modbus-sim set`, `get` and `list`.
280
324
  `--no-control` turns the channel off.
281
325
 
326
+ ## Docker
327
+
328
+ For clients that are not written in Python: the image runs the three profiles
329
+ after real devices behind one Modbus TCP port (`eastron-sdm630` as `meter` on
330
+ unit 1, `omron-e5cc` as `controller` on unit 2, `sunspec-inverter` as `inverter`
331
+ on unit 3).
332
+
333
+ ```bash
334
+ docker run --rm --name sim -p 5020:5020 -p 127.0.0.1:5021:5021 ghcr.io/steitec/modbus-sim
335
+ ```
336
+
337
+ The control channel has no authentication, hence `127.0.0.1:` in front of it.
338
+ It listens on all interfaces inside the container, so anything on the same
339
+ Docker network can reach it; use `serve ... --no-control` where that matters.
340
+ Inject a fault without installing anything, or send the
341
+ [JSON lines](#control-channel) to port 5021 from your own test code:
342
+
343
+ ```bash
344
+ docker exec sim modbus-sim inject inverter grid_loss
345
+ docker exec sim modbus-sim clear inverter
346
+ ```
347
+
348
+ Your client insists on port 502, or you have your own bench file:
349
+
350
+ ```bash
351
+ docker run --rm -p 502:5020 ghcr.io/steitec/modbus-sim
352
+ docker run --rm -p 5020:5020 -v "$PWD/bench.yaml":/bench/bench.yaml ghcr.io/steitec/modbus-sim
353
+ ```
354
+
355
+ Other arguments replace the default command. Keep `--host 0.0.0.0`, or the port
356
+ is only reachable from inside the container:
357
+
358
+ ```bash
359
+ docker run --rm -p 5020:5020 ghcr.io/steitec/modbus-sim serve vfd --host 0.0.0.0 --rtu-over-tcp
360
+ ```
361
+
362
+ As a service container in GitHub Actions:
363
+
364
+ ```yaml
365
+ services:
366
+ modbus:
367
+ image: ghcr.io/steitec/modbus-sim
368
+ ports:
369
+ - 5020:5020
370
+ - 127.0.0.1:5021:5021
371
+ ```
372
+
373
+ The image has no RTU on a serial port; use Modbus TCP or RTU over TCP.
374
+
282
375
  ## Python client
283
376
 
284
377
  A minimal master is included, mainly for trying things out and for tests:
@@ -323,8 +416,11 @@ starts. See [examples/test_example.py](examples/test_example.py).
323
416
 
324
417
  - For development and testing; not a certified or conformance-tested Modbus
325
418
  implementation.
326
- - The bundled profiles are invented devices with plausible register maps, not
327
- copies of real products. Models are plausible, not physically accurate.
419
+ - `energy-meter`, `temperature-controller` and `vfd` are invented devices with
420
+ plausible register maps. The profiles after real devices follow the
421
+ published register maps but not every behaviour of the device (see
422
+ [Profiles after real devices](#profiles-after-real-devices)). Models are
423
+ plausible, not physically accurate.
328
424
  - No Modbus ASCII, no Modbus/TCP Security (TLS), no function codes 11, 12, 17,
329
425
  20, 21, 24; diagnostics only sub-function 00.
330
426
  - RTU framing finds the end of a request from its function code, and the
@@ -6,17 +6,25 @@
6
6
  # modbus-sim
7
7
 
8
8
  [![CI](https://github.com/steitec/modbus-sim/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/steitec/modbus-sim/actions/workflows/ci.yml)
9
- [![PyPI](https://img.shields.io/pypi/v/modbus-sim)](https://pypi.org/project/modbus-sim/)
10
- [![Python](https://img.shields.io/pypi/pyversions/modbus-sim)](https://pypi.org/project/modbus-sim/)
11
- [![License](https://img.shields.io/pypi/l/modbus-sim)](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
9
+ [![PyPI](https://img.shields.io/pypi/v/modbus-sim?v=0.2.1)](https://pypi.org/project/modbus-sim/)
10
+ [![Python](https://img.shields.io/pypi/pyversions/modbus-sim?v=0.2.1)](https://pypi.org/project/modbus-sim/)
11
+ [![License](https://img.shields.io/pypi/l/modbus-sim?v=0.2.1)](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
12
+ [![Demo](https://img.shields.io/badge/demo-live%20in%20your%20browser-2ea44f)](https://modbus-sim.steitec.net)
12
13
 
13
14
  Simulated Modbus devices that **behave**: an energy meter whose counters count,
14
15
  a temperature controller that heats towards its setpoint, a frequency converter
15
- that ramps up when you set the run bit and trips when you tell it to. They speak
16
+ that ramps up when you set the run bit and trips when you tell it to. Three
17
+ profiles follow the published register maps of real devices: an Eastron SDM630
18
+ energy meter, an Omron E5CC temperature controller and a SunSpec PV inverter.
19
+ **[Try them in your browser](https://modbus-sim.steitec.net)**, no install needed.
20
+ They speak
16
21
  Modbus TCP, RTU over TCP and RTU on a serial line or a virtual serial port, so
17
22
  you can develop and test SCADA links, data loggers, gateways, Node-RED flows or
18
23
  your own Modbus code without the hardware, also in CI.
19
24
 
25
+ Walkthroughs, CI recipes and troubleshooting are in the
26
+ [wiki](https://github.com/steitec/modbus-sim/wiki); this README is the reference.
27
+
20
28
  ```console
21
29
  $ modbus-sim serve --bench examples/plant.yaml &
22
30
  modbus-sim: 3 devices (units 1, 2, 3) on modbus tcp 127.0.0.1:5020, control on :5021
@@ -101,6 +109,37 @@ such as com0com.
101
109
  | `energy-meter` | three-phase meter: voltages, currents, powers, power factor, frequency, energy import/export | float32 in **CDAB** word order, Wh counters as uint64, reset coil |
102
110
  | `temperature-controller` | PI controller heating a first-order process; run/stop, auto/manual, alarm limits | int16 scaled by 0.1; sensor break reads 3276.7 (0x7FFF) |
103
111
  | `vfd` | frequency converter: control word, speed reference, accel/decel ramps, status word, current, voltage, rpm, run hours | trip is latched until a fault reset (rising edge) and a new run edge |
112
+ | `eastron-sdm630` | Eastron SDM630 three-phase meter: the full input register map of protocol V1.5 (volts, amps, powers, power factor, phase angle, THD, demand, per-phase import/export kWh and kvarh) and the set-up holding registers | float32 in **ABCD**, input registers 30001 ff.; unlisted addresses read 0 |
113
+ | `omron-e5cc` | Omron E5CC temperature controller in two-byte mode: PV, status, set point, MV, manual MV, operation commands (run/stop, auto/manual, write mode) | writes answer exception 04 until **communications writing** is switched on with operation command 0x0001 |
114
+ | `sunspec-inverter` | three-phase PV inverter with the SunSpec map that SMA, Fronius, SolarEdge and others publish: model 1 (common) + model 103, on a day curve | "SunS" at 40000, integer + scale-factor registers, SunSpec states and event bits |
115
+
116
+ ### Profiles after real devices
117
+
118
+ `eastron-sdm630`, `omron-e5cc` and `sunspec-inverter` are built from public
119
+ documentation, so code written against them should work against the real
120
+ device's register map:
121
+
122
+ | profile | source | simplified |
123
+ |---|---|---|
124
+ | `eastron-sdm630` | Eastron "SDM630 Modbus Protocol" V1.5 | odd register counts and requests over 80 registers are accepted; THD is constant with noise; demand is an exponential average; set-up registers are stored only (no password, restart or register-order switching); a `reset_energy` coil is added |
125
+ | `omron-e5cc` | Omron "E5@C Communications Manual" (H175), sections 3-2, 4 and 5 | two-byte mode only; status sets only the bits the model knows (input error, control output, write mode, run/stop, communications writing, auto/manual); no heater current, alarm values or status 2; commands other than communications writing, run/stop, auto/manual and write mode are accepted without effect |
126
+ | `sunspec-inverter` | SunSpec model definitions (github.com/sunspec/models) | fixed scale factors; no control models (120-127); generic manufacturer "steitec" |
127
+
128
+ Each was checked against a third-party client: `sdm_modbus` reads the
129
+ simulated SDM630, and the SunSpec Alliance's `pysunspec2` scans and decodes
130
+ the inverter. steitec is not affiliated with Eastron, Omron or the SunSpec
131
+ Alliance; product names identify the documented register maps only. Firmware
132
+ versions of real devices differ, so check your device's documentation.
133
+
134
+ ```console
135
+ $ modbus-sim serve omron-e5cc &
136
+ $ modbus-sim write holding 0x2103 100 --scale 0.1 # refused: exception 04
137
+ $ modbus-sim write holding 0 0x0001 # communications writing on
138
+ $ modbus-sim write holding 0x2103 100 --scale 0.1 # set point 100.0 degC
139
+ $ modbus-sim serve sunspec-inverter --port 5030 \
140
+ --control-port 5031 &
141
+ $ modbus-sim read holding 40000 -c 2 -t string --port 5030
142
+ ```
104
143
 
105
144
  `modbus-sim map PROFILE` prints the complete register map, with the 0-based
106
145
  protocol address and the conventional reference (`400001` = holding
@@ -156,8 +195,9 @@ points:
156
195
  - **min/max**: written values outside are exception 03
157
196
  - **sources**: `constant` (value), `ramp` (start, stop, period), `sine`
158
197
  (offset, amplitude, period), `noise` (sigma); a list is added up
159
- - **model**: the three bundled profiles bind points to a model with
160
- `model: <variable>`; `model_params` tune it (`time_scale` speeds any model up)
198
+ - **model**: the bundled profiles bind points to a model (`energy_meter`,
199
+ `temperature_controller`, `vfd`, `pv_inverter`) with `model: <variable>`;
200
+ `model_params` tune it (`time_scale` speeds any model up)
161
201
  - **bits**: names for the bits of a uint16 register (shown by `map`)
162
202
 
163
203
  A point named `exception_status` provides the byte returned by function 07.
@@ -196,7 +236,8 @@ the bench file.
196
236
  Anything else answers exception 01. Exceptions follow the specification:
197
237
  02 for unmapped or read-only addresses and for writes that would change only
198
238
  part of a 32/64-bit value, 03 for bad quantities, byte counts and values
199
- outside `min`/`max`.
239
+ outside `min`/`max`, 04 where a device refuses a write in its present state
240
+ (`omron-e5cc` with communications writing off).
200
241
 
201
242
  **Unit IDs.** On Modbus TCP an unknown unit answers exception 0x0B (gateway
202
243
  target failed to respond); a single device also answers unit 0 and 255. On
@@ -224,7 +265,10 @@ clear DEVICE [FAULT]`:
224
265
  | `drift` | point, per_second | a numeric point runs away |
225
266
  | `trip` | code=1 | `vfd`: fault trip, coasts to stop, latched until reset |
226
267
  | `sensor_break` | | `temperature-controller`: PV reads 3276.7, output off, alarm |
227
- | `phase_loss` | phase | `energy-meter`: that phase reads 0 V, 0 A |
268
+ | `phase_loss` | phase | `energy-meter`, `eastron-sdm630`: that phase reads 0 V, 0 A |
269
+ | `grid_loss` | | `sunspec-inverter`: state 7 (fault), event bit 4, AC values 0 |
270
+ | `ground_fault` | | `sunspec-inverter`: state 7 (fault), event bit 0 |
271
+ | `over_temp` | | `sunspec-inverter`: state 5 (throttled) at half power, event bit 7 |
228
272
 
229
273
  ## Control channel
230
274
 
@@ -243,6 +287,55 @@ only, no authentication). It takes one JSON object per line:
243
287
  set `null`); the CLI has the same as `modbus-sim set`, `get` and `list`.
244
288
  `--no-control` turns the channel off.
245
289
 
290
+ ## Docker
291
+
292
+ For clients that are not written in Python: the image runs the three profiles
293
+ after real devices behind one Modbus TCP port (`eastron-sdm630` as `meter` on
294
+ unit 1, `omron-e5cc` as `controller` on unit 2, `sunspec-inverter` as `inverter`
295
+ on unit 3).
296
+
297
+ ```bash
298
+ docker run --rm --name sim -p 5020:5020 -p 127.0.0.1:5021:5021 ghcr.io/steitec/modbus-sim
299
+ ```
300
+
301
+ The control channel has no authentication, hence `127.0.0.1:` in front of it.
302
+ It listens on all interfaces inside the container, so anything on the same
303
+ Docker network can reach it; use `serve ... --no-control` where that matters.
304
+ Inject a fault without installing anything, or send the
305
+ [JSON lines](#control-channel) to port 5021 from your own test code:
306
+
307
+ ```bash
308
+ docker exec sim modbus-sim inject inverter grid_loss
309
+ docker exec sim modbus-sim clear inverter
310
+ ```
311
+
312
+ Your client insists on port 502, or you have your own bench file:
313
+
314
+ ```bash
315
+ docker run --rm -p 502:5020 ghcr.io/steitec/modbus-sim
316
+ docker run --rm -p 5020:5020 -v "$PWD/bench.yaml":/bench/bench.yaml ghcr.io/steitec/modbus-sim
317
+ ```
318
+
319
+ Other arguments replace the default command. Keep `--host 0.0.0.0`, or the port
320
+ is only reachable from inside the container:
321
+
322
+ ```bash
323
+ docker run --rm -p 5020:5020 ghcr.io/steitec/modbus-sim serve vfd --host 0.0.0.0 --rtu-over-tcp
324
+ ```
325
+
326
+ As a service container in GitHub Actions:
327
+
328
+ ```yaml
329
+ services:
330
+ modbus:
331
+ image: ghcr.io/steitec/modbus-sim
332
+ ports:
333
+ - 5020:5020
334
+ - 127.0.0.1:5021:5021
335
+ ```
336
+
337
+ The image has no RTU on a serial port; use Modbus TCP or RTU over TCP.
338
+
246
339
  ## Python client
247
340
 
248
341
  A minimal master is included, mainly for trying things out and for tests:
@@ -287,8 +380,11 @@ starts. See [examples/test_example.py](examples/test_example.py).
287
380
 
288
381
  - For development and testing; not a certified or conformance-tested Modbus
289
382
  implementation.
290
- - The bundled profiles are invented devices with plausible register maps, not
291
- copies of real products. Models are plausible, not physically accurate.
383
+ - `energy-meter`, `temperature-controller` and `vfd` are invented devices with
384
+ plausible register maps. The profiles after real devices follow the
385
+ published register maps but not every behaviour of the device (see
386
+ [Profiles after real devices](#profiles-after-real-devices)). Models are
387
+ plausible, not physically accurate.
292
388
  - No Modbus ASCII, no Modbus/TCP Security (TLS), no function codes 11, 12, 17,
293
389
  20, 21, 24; diagnostics only sub-function 00.
294
390
  - RTU framing finds the end of a request from its function code, and the
@@ -0,0 +1,9 @@
1
+ # The three profiles after real register maps behind one Modbus TCP gateway, as on
2
+ # the browser demo (https://modbus-sim.steitec.net). Run with
3
+ # modbus-sim serve --bench examples/real-devices.yaml
4
+ devices:
5
+ - {profile: eastron-sdm630, unit: 1, name: meter}
6
+ - {profile: omron-e5cc, unit: 2, name: controller,
7
+ model_params: {time_scale: 10}} # heats ten times faster than real time
8
+ - {profile: sunspec-inverter, unit: 3, name: inverter,
9
+ model_params: {time_scale: 120}} # a day in 12 minutes
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "modbus-sim"
7
- version = "0.1.0"
7
+ version = "0.2.1"
8
8
  description = "Simulated Modbus devices with behaviour and fault injection: energy meter, temperature controller, VFD over Modbus TCP and RTU"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  """Simulated Modbus devices (energy meter, temperature controller, frequency converter)
2
2
  with behaviour and fault injection, over Modbus TCP, RTU over TCP and serial RTU."""
3
- __version__ = "0.1.0"
3
+ __version__ = "0.2.1"
4
4
 
5
5
  from .bench import Bench, BenchError
6
6
  from .client import ModbusClient, ModbusError
@@ -6,8 +6,8 @@ bytes are A B C D:
6
6
  ===== =============== ================================================
7
7
  order registers seen in
8
8
  ===== =============== ================================================
9
- ABCD [AB, CD] the Modbus default (big endian), most PLCs
10
- CDAB [CD, AB] word-swapped: many energy meters, Schneider, Eastron
9
+ ABCD [AB, CD] the Modbus default (big endian), most PLCs, Eastron
10
+ CDAB [CD, AB] word-swapped: many energy meters, Schneider
11
11
  BADC [BA, DC] byte-swapped
12
12
  DCBA [DC, BA] little endian
13
13
  ===== =============== ================================================
@@ -114,7 +114,7 @@ class Point:
114
114
  try:
115
115
  self.device.model.set(self.spec.model, value)
116
116
  except ModelError as exc:
117
- raise ModbusException(frame.ILLEGAL_DATA_VALUE, str(exc)) from None
117
+ raise ModbusException(exc.code, str(exc)) from None
118
118
  elif self.signal is not None:
119
119
  self.override = value # a written value holds until the control channel resets it
120
120
  else:
@@ -19,6 +19,9 @@ drift point, per_second a numeric point runs away
19
19
  trip code=1 vfd: fault trip, latched until reset
20
20
  sensor_break - temperature controller: sensor broken
21
21
  phase_loss phase (1-3) energy meter: phase lost
22
+ grid_loss - PV inverter: grid gone, state fault
23
+ ground_fault - PV inverter: ground fault, state fault
24
+ over_temp - PV inverter: throttled to half power
22
25
  ================= ================================== ==========================================
23
26
 
24
27
  ``count`` faults wear off after that many requests to the device; the others stay