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

modbus_sim-0.2.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/).
+
+## 0.2.0 - 2026-11-01
+
+- Profiles after the published register maps of real devices:
+  `eastron-sdm630` (Eastron SDM630 protocol V1.5, float32 ABCD, input and set-up
+  registers), `omron-e5cc` (Omron E5CC two-byte mode with status words, operation
+  commands and the communications-writing enable) and `sunspec-inverter` (SunSpec models 1 and
+  103 with scale factors)
+- New model `pv_inverter`: day curve, SunSpec operating states and event bits,
+  faults `grid_loss`, `ground_fault`, `over_temp`
+- `energy_meter` model: apparent and reactive power per phase, phase angles,
+  averages, neutral current, per-phase import/export/total kWh and kvarh, kVAh,
+  Ah, demand values with maxima; parameters `pf_sign` and `demand_period`
+- `temperature_controller` model: operation command register, an optional
+  write enable (`comms_write`) and the Omron E5@C status words
+- A model can refuse a write with exception 04 instead of 03 (the E5CC answers
+  04, operation error, while communications writing is off)
+- Browser demo at https://modbus-sim.steitec.net (`web/`): the three real-device
+  profiles in Pyodide with a Modbus terminal that shows the TCP frames, live device
+  fronts and fault buttons; example bench `examples/real-devices.yaml`
+- Fixed: the word order table named Eastron among CDAB devices; Eastron meters
+  send the most significant register first (ABCD)
+
+## 0.1.0 - 2026-10-31
+
+- Modbus TCP, RTU over TCP, and RTU on a serial port (pyserial) or a virtual
+  serial port (pty, Linux/macOS); several devices by unit ID behind one server,
+  RTU broadcast
+- Function codes 01-08 (08: sub-function 00), 15, 16, 22, 23 and 43/14 (device
+  identification) with the exceptions of the specification
+- YAML profiles: points with type (16/32/64-bit integers, floats, strings, bits),
+  word order (ABCD/CDAB/BADC/DCBA), scale, access, limits, signal sources
+- Bundled devices with behaviour: `energy-meter`, `temperature-controller`, `vfd`
+- Bench files for several devices with per-device overrides
+- Fault injection (`no_response`, `delay`, `exception`, `busy`, `drop_connection`,
+  `bad_crc`, `wrong_transaction`, `wrong_unit`, `truncate`, `freeze`, `drift`, `trip`,
+  `sensor_break`, `phase_loss`) through a JSON control channel and the CLI
+- Command line (`serve`, `profiles`, `map`, `read`, `write`, `ident`, `inject`, `clear`,
+  `get`, `set`, `list`) and a small Python client
+- pytest plugin with the `modbus_bench` and `modbus_bench_factory` fixtures
+- Test suite cross-checks the simulator against pymodbus

{modbus_sim-0.1.0/src/modbus_sim.egg-info → modbus_sim-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modbus-sim
-Version: 0.1.0
+Version: 0.2.0
 Summary: Simulated Modbus devices with behaviour and fault injection: energy meter, temperature controller, VFD over Modbus TCP and RTU
 Author: Ralf Steinert
 License-Expression: MIT
@@ -42,13 +42,17 @@ Dynamic: license-file
 # modbus-sim
 
 [![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)
-[![PyPI](https://img.shields.io/pypi/v/modbus-sim)](https://pypi.org/project/modbus-sim/)
-[![Python](https://img.shields.io/pypi/pyversions/modbus-sim)](https://pypi.org/project/modbus-sim/)
-[![License](https://img.shields.io/pypi/l/modbus-sim)](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/modbus-sim?v=0.2.0)](https://pypi.org/project/modbus-sim/)
+[![Python](https://img.shields.io/pypi/pyversions/modbus-sim?v=0.2.0)](https://pypi.org/project/modbus-sim/)
+[![License](https://img.shields.io/pypi/l/modbus-sim?v=0.2.0)](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
 
 Simulated Modbus devices that **behave**: an energy meter whose counters count,
 a temperature controller that heats towards its setpoint, a frequency converter
-that ramps up when you set the run bit and trips when you tell it to. They speak
+that ramps up when you set the run bit and trips when you tell it to. Three
+profiles follow the published register maps of real devices: an Eastron SDM630
+energy meter, an Omron E5CC temperature controller and a SunSpec PV inverter.
+**[Try them in your browser](https://modbus-sim.steitec.net)**, no install needed.
+They speak
 Modbus TCP, RTU over TCP and RTU on a serial line or a virtual serial port, so
 you can develop and test SCADA links, data loggers, gateways, Node-RED flows or
 your own Modbus code without the hardware, also in CI.
@@ -137,6 +141,37 @@ such as com0com.
 | `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 |
 | `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) |
 | `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 |
+| `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 |
+| `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 |
+| `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 |
+
+### Profiles after real devices
+
+`eastron-sdm630`, `omron-e5cc` and `sunspec-inverter` are built from public
+documentation, so code written against them should work against the real
+device's register map:
+
+| profile | source | simplified |
+|---|---|---|
+| `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 |
+| `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 |
+| `sunspec-inverter` | SunSpec model definitions (github.com/sunspec/models) | fixed scale factors; no control models (120-127); generic manufacturer "steitec" |
+
+Each was checked against a third-party client: `sdm_modbus` reads the
+simulated SDM630, and the SunSpec Alliance's `pysunspec2` scans and decodes
+the inverter. steitec is not affiliated with Eastron, Omron or the SunSpec
+Alliance; product names identify the documented register maps only. Firmware
+versions of real devices differ, so check your device's documentation.
+
+```console
+$ modbus-sim serve omron-e5cc &
+$ modbus-sim write holding 0x2103 100 --scale 0.1     # refused: exception 04
+$ modbus-sim write holding 0 0x0001                   # communications writing on
+$ modbus-sim write holding 0x2103 100 --scale 0.1     # set point 100.0 degC
+$ modbus-sim serve sunspec-inverter --port 5030 \
+    --control-port 5031 &
+$ modbus-sim read holding 40000 -c 2 -t string --port 5030
+```
 
 `modbus-sim map PROFILE` prints the complete register map, with the 0-based
 protocol address and the conventional reference (`400001` = holding
@@ -192,8 +227,9 @@ points:
 - **min/max**: written values outside are exception 03
 - **sources**: `constant` (value), `ramp` (start, stop, period), `sine`
   (offset, amplitude, period), `noise` (sigma); a list is added up
-- **model**: the three bundled profiles bind points to a model with
-  `model: <variable>`; `model_params` tune it (`time_scale` speeds any model up)
+- **model**: the bundled profiles bind points to a model (`energy_meter`,
+  `temperature_controller`, `vfd`, `pv_inverter`) with `model: <variable>`;
+  `model_params` tune it (`time_scale` speeds any model up)
 - **bits**: names for the bits of a uint16 register (shown by `map`)
 
 A point named `exception_status` provides the byte returned by function 07.
@@ -232,7 +268,8 @@ the bench file.
 Anything else answers exception 01. Exceptions follow the specification:
 02 for unmapped or read-only addresses and for writes that would change only
 part of a 32/64-bit value, 03 for bad quantities, byte counts and values
-outside `min`/`max`.
+outside `min`/`max`, 04 where a device refuses a write in its present state
+(`omron-e5cc` with communications writing off).
 
 **Unit IDs.** On Modbus TCP an unknown unit answers exception 0x0B (gateway
 target failed to respond); a single device also answers unit 0 and 255. On
@@ -260,7 +297,10 @@ clear DEVICE [FAULT]`:
 | `drift` | point, per_second | a numeric point runs away |
 | `trip` | code=1 | `vfd`: fault trip, coasts to stop, latched until reset |
 | `sensor_break` | | `temperature-controller`: PV reads 3276.7, output off, alarm |
-| `phase_loss` | phase | `energy-meter`: that phase reads 0 V, 0 A |
+| `phase_loss` | phase | `energy-meter`, `eastron-sdm630`: that phase reads 0 V, 0 A |
+| `grid_loss` | | `sunspec-inverter`: state 7 (fault), event bit 4, AC values 0 |
+| `ground_fault` | | `sunspec-inverter`: state 7 (fault), event bit 0 |
+| `over_temp` | | `sunspec-inverter`: state 5 (throttled) at half power, event bit 7 |
 
 ## Control channel
 
@@ -323,8 +363,11 @@ starts. See [examples/test_example.py](examples/test_example.py).
 
 - For development and testing; not a certified or conformance-tested Modbus
   implementation.
-- The bundled profiles are invented devices with plausible register maps, not
-  copies of real products. Models are plausible, not physically accurate.
+- `energy-meter`, `temperature-controller` and `vfd` are invented devices with
+  plausible register maps. The profiles after real devices follow the
+  published register maps but not every behaviour of the device (see
+  [Profiles after real devices](#profiles-after-real-devices)). Models are
+  plausible, not physically accurate.
 - No Modbus ASCII, no Modbus/TCP Security (TLS), no function codes 11, 12, 17,
   20, 21, 24; diagnostics only sub-function 00.
 - RTU framing finds the end of a request from its function code, and the

{modbus_sim-0.1.0 → modbus_sim-0.2.0}/README.md

@@ -6,13 +6,17 @@
 # modbus-sim
 
 [![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)
-[![PyPI](https://img.shields.io/pypi/v/modbus-sim)](https://pypi.org/project/modbus-sim/)
-[![Python](https://img.shields.io/pypi/pyversions/modbus-sim)](https://pypi.org/project/modbus-sim/)
-[![License](https://img.shields.io/pypi/l/modbus-sim)](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/modbus-sim?v=0.2.0)](https://pypi.org/project/modbus-sim/)
+[![Python](https://img.shields.io/pypi/pyversions/modbus-sim?v=0.2.0)](https://pypi.org/project/modbus-sim/)
+[![License](https://img.shields.io/pypi/l/modbus-sim?v=0.2.0)](https://github.com/steitec/modbus-sim/blob/main/LICENSE)
 
 Simulated Modbus devices that **behave**: an energy meter whose counters count,
 a temperature controller that heats towards its setpoint, a frequency converter
-that ramps up when you set the run bit and trips when you tell it to. They speak
+that ramps up when you set the run bit and trips when you tell it to. Three
+profiles follow the published register maps of real devices: an Eastron SDM630
+energy meter, an Omron E5CC temperature controller and a SunSpec PV inverter.
+**[Try them in your browser](https://modbus-sim.steitec.net)**, no install needed.
+They speak
 Modbus TCP, RTU over TCP and RTU on a serial line or a virtual serial port, so
 you can develop and test SCADA links, data loggers, gateways, Node-RED flows or
 your own Modbus code without the hardware, also in CI.
@@ -101,6 +105,37 @@ such as com0com.
 | `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 |
 | `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) |
 | `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 |
+| `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 |
+| `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 |
+| `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 |
+
+### Profiles after real devices
+
+`eastron-sdm630`, `omron-e5cc` and `sunspec-inverter` are built from public
+documentation, so code written against them should work against the real
+device's register map:
+
+| profile | source | simplified |
+|---|---|---|
+| `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 |
+| `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 |
+| `sunspec-inverter` | SunSpec model definitions (github.com/sunspec/models) | fixed scale factors; no control models (120-127); generic manufacturer "steitec" |
+
+Each was checked against a third-party client: `sdm_modbus` reads the
+simulated SDM630, and the SunSpec Alliance's `pysunspec2` scans and decodes
+the inverter. steitec is not affiliated with Eastron, Omron or the SunSpec
+Alliance; product names identify the documented register maps only. Firmware
+versions of real devices differ, so check your device's documentation.
+
+```console
+$ modbus-sim serve omron-e5cc &
+$ modbus-sim write holding 0x2103 100 --scale 0.1     # refused: exception 04
+$ modbus-sim write holding 0 0x0001                   # communications writing on
+$ modbus-sim write holding 0x2103 100 --scale 0.1     # set point 100.0 degC
+$ modbus-sim serve sunspec-inverter --port 5030 \
+    --control-port 5031 &
+$ modbus-sim read holding 40000 -c 2 -t string --port 5030
+```
 
 `modbus-sim map PROFILE` prints the complete register map, with the 0-based
 protocol address and the conventional reference (`400001` = holding
@@ -156,8 +191,9 @@ points:
 - **min/max**: written values outside are exception 03
 - **sources**: `constant` (value), `ramp` (start, stop, period), `sine`
   (offset, amplitude, period), `noise` (sigma); a list is added up
-- **model**: the three bundled profiles bind points to a model with
-  `model: <variable>`; `model_params` tune it (`time_scale` speeds any model up)
+- **model**: the bundled profiles bind points to a model (`energy_meter`,
+  `temperature_controller`, `vfd`, `pv_inverter`) with `model: <variable>`;
+  `model_params` tune it (`time_scale` speeds any model up)
 - **bits**: names for the bits of a uint16 register (shown by `map`)
 
 A point named `exception_status` provides the byte returned by function 07.
@@ -196,7 +232,8 @@ the bench file.
 Anything else answers exception 01. Exceptions follow the specification:
 02 for unmapped or read-only addresses and for writes that would change only
 part of a 32/64-bit value, 03 for bad quantities, byte counts and values
-outside `min`/`max`.
+outside `min`/`max`, 04 where a device refuses a write in its present state
+(`omron-e5cc` with communications writing off).
 
 **Unit IDs.** On Modbus TCP an unknown unit answers exception 0x0B (gateway
 target failed to respond); a single device also answers unit 0 and 255. On
@@ -224,7 +261,10 @@ clear DEVICE [FAULT]`:
 | `drift` | point, per_second | a numeric point runs away |
 | `trip` | code=1 | `vfd`: fault trip, coasts to stop, latched until reset |
 | `sensor_break` | | `temperature-controller`: PV reads 3276.7, output off, alarm |
-| `phase_loss` | phase | `energy-meter`: that phase reads 0 V, 0 A |
+| `phase_loss` | phase | `energy-meter`, `eastron-sdm630`: that phase reads 0 V, 0 A |
+| `grid_loss` | | `sunspec-inverter`: state 7 (fault), event bit 4, AC values 0 |
+| `ground_fault` | | `sunspec-inverter`: state 7 (fault), event bit 0 |
+| `over_temp` | | `sunspec-inverter`: state 5 (throttled) at half power, event bit 7 |
 
 ## Control channel
 
@@ -287,8 +327,11 @@ starts. See [examples/test_example.py](examples/test_example.py).
 
 - For development and testing; not a certified or conformance-tested Modbus
   implementation.
-- The bundled profiles are invented devices with plausible register maps, not
-  copies of real products. Models are plausible, not physically accurate.
+- `energy-meter`, `temperature-controller` and `vfd` are invented devices with
+  plausible register maps. The profiles after real devices follow the
+  published register maps but not every behaviour of the device (see
+  [Profiles after real devices](#profiles-after-real-devices)). Models are
+  plausible, not physically accurate.
 - No Modbus ASCII, no Modbus/TCP Security (TLS), no function codes 11, 12, 17,
   20, 21, 24; diagnostics only sub-function 00.
 - RTU framing finds the end of a request from its function code, and the

modbus_sim-0.2.0/examples/real-devices.yaml

@@ -0,0 +1,9 @@
+# The three profiles after real register maps behind one Modbus TCP gateway, as on
+# the browser demo (https://modbus-sim.steitec.net). Run with
+#   modbus-sim serve --bench examples/real-devices.yaml
+devices:
+  - {profile: eastron-sdm630, unit: 1, name: meter}
+  - {profile: omron-e5cc, unit: 2, name: controller,
+     model_params: {time_scale: 10}}          # heats ten times faster than real time
+  - {profile: sunspec-inverter, unit: 3, name: inverter,
+     model_params: {time_scale: 120}}         # a day in 12 minutes

{modbus_sim-0.1.0 → modbus_sim-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "modbus-sim"
-version = "0.1.0"
+version = "0.2.0"
 description = "Simulated Modbus devices with behaviour and fault injection: energy meter, temperature controller, VFD over Modbus TCP and RTU"
 readme = "README.md"
 license = "MIT"

{modbus_sim-0.1.0 → modbus_sim-0.2.0}/src/modbus_sim/__init__.py

@@ -1,6 +1,6 @@
 """Simulated Modbus devices (energy meter, temperature controller, frequency converter)
 with behaviour and fault injection, over Modbus TCP, RTU over TCP and serial RTU."""
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from .bench import Bench, BenchError
 from .client import ModbusClient, ModbusError

{modbus_sim-0.1.0 → modbus_sim-0.2.0}/src/modbus_sim/datatypes.py

@@ -6,8 +6,8 @@ bytes are A B C D:
 =====  ===============  ================================================
 order  registers        seen in
 =====  ===============  ================================================
-ABCD   [AB, CD]         the Modbus default (big endian), most PLCs
-CDAB   [CD, AB]         word-swapped: many energy meters, Schneider, Eastron
+ABCD   [AB, CD]         the Modbus default (big endian), most PLCs, Eastron
+CDAB   [CD, AB]         word-swapped: many energy meters, Schneider
 BADC   [BA, DC]         byte-swapped
 DCBA   [DC, BA]         little endian
 =====  ===============  ================================================

{modbus_sim-0.1.0 → modbus_sim-0.2.0}/src/modbus_sim/device.py

@@ -114,7 +114,7 @@ class Point:
             try:
                 self.device.model.set(self.spec.model, value)
             except ModelError as exc:
-                raise ModbusException(frame.ILLEGAL_DATA_VALUE, str(exc)) from None
+                raise ModbusException(exc.code, str(exc)) from None
         elif self.signal is not None:
             self.override = value  # a written value holds until the control channel resets it
         else:

{modbus_sim-0.1.0 → modbus_sim-0.2.0}/src/modbus_sim/faults.py

@@ -19,6 +19,9 @@ drift              point, per_second                   a numeric point runs away
 trip               code=1                              vfd: fault trip, latched until reset
 sensor_break       -                                   temperature controller: sensor broken
 phase_loss         phase (1-3)                         energy meter: phase lost
+grid_loss          -                                   PV inverter: grid gone, state fault
+ground_fault       -                                   PV inverter: ground fault, state fault
+over_temp          -                                   PV inverter: throttled to half power
 =================  ==================================  ==========================================
 
 ``count`` faults wear off after that many requests to the device; the others stay