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.
- modbus_sim-0.2.1/CHANGELOG.md +51 -0
- {modbus_sim-0.1.0/src/modbus_sim.egg-info → modbus_sim-0.2.1}/PKG-INFO +107 -11
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/README.md +106 -10
- modbus_sim-0.2.1/examples/real-devices.yaml +9 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/pyproject.toml +1 -1
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/__init__.py +1 -1
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/datatypes.py +2 -2
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/device.py +1 -1
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/faults.py +3 -0
- modbus_sim-0.2.1/src/modbus_sim/models.py +719 -0
- modbus_sim-0.2.1/src/modbus_sim/profiles/eastron-sdm630.yaml +233 -0
- modbus_sim-0.2.1/src/modbus_sim/profiles/omron-e5cc.yaml +81 -0
- modbus_sim-0.2.1/src/modbus_sim/profiles/sunspec-inverter.yaml +136 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1/src/modbus_sim.egg-info}/PKG-INFO +107 -11
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/SOURCES.txt +5 -0
- modbus_sim-0.2.1/tests/test_device_profiles.py +269 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_profile.py +2 -1
- modbus_sim-0.1.0/CHANGELOG.md +0 -24
- modbus_sim-0.1.0/src/modbus_sim/models.py +0 -431
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/LICENSE +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/MANIFEST.in +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/examples/plant.yaml +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/examples/test_example.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/setup.cfg +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/__main__.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/bench.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/cli.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/client.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/control.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/frame.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/profile.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/profiles/energy-meter.yaml +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/profiles/temperature-controller.yaml +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/profiles/vfd.yaml +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/pytest_plugin.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/server.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim/signals.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/dependency_links.txt +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/entry_points.txt +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/requires.txt +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/src/modbus_sim.egg-info/top_level.txt +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/conftest.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_cli.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_datatypes.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_device.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_frame.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_models.py +0 -0
- {modbus_sim-0.1.0 → modbus_sim-0.2.1}/tests/test_plugin.py +0 -0
- {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
|
|
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
|
[](https://github.com/steitec/modbus-sim/actions/workflows/ci.yml)
|
|
45
|
-
[](https://pypi.org/project/modbus-sim/)
|
|
46
|
-
[](https://pypi.org/project/modbus-sim/)
|
|
47
|
-
[](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
|
|
45
|
+
[](https://pypi.org/project/modbus-sim/)
|
|
46
|
+
[](https://pypi.org/project/modbus-sim/)
|
|
47
|
+
[](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
|
|
48
|
+
[](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.
|
|
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
|
|
196
|
-
`
|
|
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
|
-
-
|
|
327
|
-
|
|
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
|
[](https://github.com/steitec/modbus-sim/actions/workflows/ci.yml)
|
|
9
|
-
[](https://pypi.org/project/modbus-sim/)
|
|
10
|
-
[](https://pypi.org/project/modbus-sim/)
|
|
11
|
-
[](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
|
|
9
|
+
[](https://pypi.org/project/modbus-sim/)
|
|
10
|
+
[](https://pypi.org/project/modbus-sim/)
|
|
11
|
+
[](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
|
|
12
|
+
[](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.
|
|
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
|
|
160
|
-
`
|
|
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
|
-
-
|
|
291
|
-
|
|
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
|
|
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
|
|
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
|
|
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(
|
|
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
|