From 43c4c287a0568147cf7a2e3e811453cc959205f0 Mon Sep 17 00:00:00 2001 From: Jonas Bengtsson Date: Sat, 3 Oct 2026 19:17:53 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=A7=20WIP?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 20 ++++ docs/spec/software-spec.md | 202 ++++++++++++++++++++++++++++++++++++- 2 files changed, 217 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f89ef24..86c968a 100644 --- a/README.md +++ b/README.md @@ -241,6 +241,26 @@ requirement ID for each item in parentheses. internal errors keep the full traceback for debugging (NFR-6.4 operational goal). +### Requested — multi-vendor & multi-protocol (spec §13 + §14, not yet scheduled) + +- [ ] Multi-vendor device profiles (spec §13): extract the per-device + facts (function codes/limits, connection limit, address maps, + mirrors, config/watchdog/statistics blocks, trace annotations) + into a device profile; other WAGO 750 Modbus couplers and other + brands' Modbus TCP I/O heads become data + a profile module + (FR-13.2.1–13.2.7); scenario engine, DSL, plugins and reports + stay device-agnostic; `device:` key in node config with the + 750-362 as default; validate rejects unknown devices and + cross-brand module mixes cleanly. +- [ ] Additional fieldbus protocols (spec §14): protocol bindings for + ABB AC800M-style benches — PROFINET IO device simulation (RT + cyclic data exchange, DCP, record data; FR-14.2.2) and COMLI + over TCP as used between AC800M and S800/S900 I/O via + CI51x/CI522 (FR-14.2.3) — reusing the same process image, + scenario engine and reporting (FR-14.2.1, FR-14.2.4); per- + protocol tracing, diagnostics and fault injection (FR-14.2.5– + 14.2.6); scoping questions to answer before planning (§14.3). + ### Framework gaps (spec §4 — Scenario & Macro Engine) - [ ] State machines: `states:` with entry actions, transitions on diff --git a/docs/spec/software-spec.md b/docs/spec/software-spec.md index 10aac07..13a67d0 100644 --- a/docs/spec/software-spec.md +++ b/docs/spec/software-spec.md @@ -5,9 +5,9 @@ | | | |---|---| | Project | `wago-modbustcp-simulator-py` | -| Version | 1.3 (Draft for review) | +| Version | 1.4 (Draft for review) | | Date | 2026-10-03 | -| Status | Framework phase; module addressing implemented (FR-4.3.11); service/container deployment implemented (§12); plain-text request tracing implemented (NFR-6.4); clean CLI error handling implemented (NFR-6.5 CLI part); long-duration simulation (§8), bench mode (§9), web UI (§10) and runtime device configuration (§11) requested | +| Status | Framework phase; module addressing implemented (FR-4.3.11); service/container deployment implemented (§12); plain-text request tracing implemented (NFR-6.4); clean CLI error handling implemented (NFR-6.5 CLI part); long-duration simulation (§8), bench mode (§9), web UI (§10), runtime device configuration (§11), multi-vendor device profiles (§13) and additional fieldbus protocols PROFINET/COMLI (§14) requested | | Target device simulated | WAGO 750-362 / 750-362/0000-0001 FC Modbus TCP (G4) bus coupler | | Reference documents | `docs/m07500362_xxxxxxxx_0en.pdf` (750-362 Modbus TCP manual), Modbus TCP specification (modbus.org) | @@ -1129,7 +1129,196 @@ connected PLC sees a controlled fieldbus-node failure rather than a --- -## 13. Roadmap (post-framework) +## 13. Feature Request — Multi-Vendor Device Profiles + +> **Status: requested 2026-10-03, not yet planned into a roadmap phase.** +> Simulate additional Modbus TCP bus couplers — other WAGO 750 couplers +> and other brands' Modbus TCP I/O heads — reusing the existing protocol +> stack. This section captures the requirements; it does not commit to +> a schedule. + +### 13.1 Motivation + +FAT benches test more than one controller and fieldbus family. Today +the simulator is single-device: the 750-362 register map, limits, +watchdog, and statistics are hard-coded across the protocol stack +(`pdu.py` limits, `datastore.py` address dispatch, `server.py` +connection limit and process-area predicate, `registers.py`, +`watchdog.py`, `stats.py`, `trace.py` annotations). The transport layer +(`mbap.py`), PDU codecs, server skeleton, scenario engine, DSL, +plugins, and reporting are protocol-generic and directly reusable. + +A second Modbus TCP device multiplies the value of the bench without a +protocol rewrite: the deltas between Modbus TCP devices are — address +maps, configuration areas, watchdog presence/semantics, statistics +blocks, connection limits, and module catalogs with image-layout +rules. These are exactly the facts the device manual provides. + +### 13.2 Requirements + +- FR-13.2.1: **Device profile abstraction**: extract the per-device + facts into a profile concept covering: supported function codes and + per-FC limits, max concurrent connections, idle-timeout behavior, + process-image address map (reads and writes), read-back mirror rules, + configuration/diagnostic register areas and semantics, watchdog + (presence, register layout, modes), statistics block layout, and + identity/description registers. The 750-362 becomes the first + profile; its behavior must be unchanged after the refactor (the + existing test suite is the regression gate). +- FR-13.2.2: **Scenario-engine independence**: the scenario engine, + DSL, plugins, and reports must remain device-agnostic — they interact + with a node only through the channel model (`ModuleType` / + `Channel` / `ChannelLocation`) and the datastore's set/read surface. + Scenarios must not require changes when a profile is added. +- FR-13.2.3: **Per-vendor module catalogs**: catalogs keyed by brand; + each entry defines word/bit widths and channels. A node config + selects brand + module list; validation must reject cross-brand + module mixes within one node (e.g., a WAGO 750-430 in an ABB S800 + station). New catalogs are data-only additions (no engine changes). +- FR-13.2.4: **Process-image layout rules per brand**: layout becomes + a profile parameter (word-first + byte-packed bit modules is the + WAGO §7.3.2.1 rule; other brands may pack differently — e.g., + byte-per-channel images). The channel model and alias addressing + (FR-4.3.11 module-based and pool-based schemes) must keep working on + top of any layout. +- FR-13.2.5: **Config registers / watchdog / statistics as pluggable + blocks**: implementations following the existing + `registers.py`/`watchdog.py`/`stats.py` pattern, one set per + profile. Devices lacking a Modbus watchdog or statistics block + expose nothing (or an illegal-address exception) there — that is a + device fact, not a simulator limitation. +- FR-13.2.6: **Trace annotations per profile**: `trace.py` address + annotations (currently 750-362 Tables 119–122) must come from the + active profile so verbose tracing stays meaningful for every device. +- FR-13.2.7: **Profile selection**: node config gains a `device:` key + (e.g. `device: wago-750-362`, the default for backward + compatibility); CLI/`WAGO_SIM_NODE` paths unchanged. `wago-sim + validate` must report unknown devices and cross-brand module mixes + as clean errors. + +### 13.3 Candidate devices (informative, non-binding) + +- WAGO 750 Modbus TCP family beyond the 362 (352/363/860…): same + register-map family — profile effort is mainly constants and + identity registers. +- Other vendors' Modbus TCP I/O heads / controllers (e.g., Phoenix + Contact Inline, Beckhoff BK/BC series): a profile written against + the vendor manual; effort dominated by the address map and + configuration-register semantics. + +### 13.4 Acceptance criteria (draft) + +1. The 750-362 profile passes the full existing test suite unchanged + after the profile extraction. +2. A second profile (from §13.3) serves a PLC master that reads/writes + its documented process image; identity/description registers match + the vendor manual; the same scenario DSL drives its channels without + modification. +3. Scenarios written for one device run unchanged against another + device with equivalent channel configuration. +4. `wago-sim validate` reports unknown device keys and cross-brand + module mixes with clean one-line errors. + +--- + +## 14. Feature Request — Additional Fieldbus Protocols (PROFINET, COMLI) + +> **Status: requested 2026-10-03, not yet planned into a roadmap phase.** +> Extend the simulator beyond Modbus TCP, motivated by ABB AC800M/800xA +> systems and their distributed I/O: PROFINET IO (AC800M PN controllers +> with S800 I/O via CI840-class interface modules) and COMLI (ABB's +> protocol between AC800M controllers and S800/S900 I/O via CI51x/CI522 +> communication interfaces, TCP-encapsulated). + +### 14.1 Motivation + +An AC800M FAT bench talks to its distributed I/O over the protocol the +controller is actually configured for. Simulating the I/O side of +those protocols lets the same scenario engine, datasets (§8), bench +mode (§9), and reporting drive FAT benches for ABB controllers, not +only Modbus TCP masters. + +The architecture separates cleanly along the same seams the +multi-vendor profiles (§13) expose: the scenario engine couples to a +node only through the channel model and the datastore's set/read +surface; a new protocol is a new transport + protocol layer binding to +the same process-image core. + +### 14.2 Requirements + +- FR-14.2.1: **Protocol abstraction**: a protocol binding defines how + the field-side process image is exposed to a master: wire protocol, + address/identifier model, cyclic vs. transactional access, and the + device's diagnostics/alarm model. The simulator core (process image, + scenario engine, plugins, reports) stays protocol-independent. +- FR-14.2.2: **PROFINET IO device simulation** (candidate; scope to be + defined against AC800M PN-controller configuration): simulate the + device side of PROFINET IO — DCP identify/boot, cyclic RT I/O data + exchange for a configured module list, and enough record/identification + data for the IO controller to bring the device into data exchange. + Scope note: a full PROFINET stack is a major undertaking; a + realistic first target is an Ethernet-level RT simulation of one + S800-style station profile with a fixed module list, driven by the + existing deterministic clock and scenario engine. +- FR-14.2.3: **COMLI device simulation** (candidate; scope to be + defined against AC800M/CI51x/CI522 documentation): simulate the + I/O-side endpoint of ABB COMLI over TCP as used between AC800M and + S800/S900 I/O through CI communication interfaces — the + register/point addressing model, cyclic polling, and the diagnostics + responses the CI interface expects. COMLI's request/response + register semantics map naturally onto the datastore's set/read + surface. +- FR-14.2.4: **Shared scenario engine**: scenarios, aliases, macros, + assertions, plugins, and datasets (§8) work unchanged against + protocol bindings; only the channel/identifier model of the target + I/O system is expressed in the node config (module list with + brand-specific article numbers). A scenario must not name wire-level + addresses; alias resolution stays per-device via FR-4.3.11/FR-13.2.4. +- FR-14.2.5: **Trace and diagnostics parity**: per-protocol verbose + tracing equivalent to the Modbus plain-text trace (NFR-6.4): + PROFINET RT frames and COMLI requests decoded in readable form with + device-level annotations; protocol error counters analogous to the + Modbus statistics block. +- FR-14.2.6: **Fault-injection parity** (per protocol): for PROFINET — + frame loss/corruption, device pull/plug, subslot mismatch, + communication/watchdog timeouts (the PN equivalent of the Modbus + watchdog §3.4); for COMLI — request timeouts, malformed messages, + CI-interface failure simulation. These must be scriptable from + scenarios like the Modbus fault paths (§3.6). +- FR-14.2.7: **Deployment parity**: protocol servers run under the + same service/container model (§12): env-var configuration, graceful + shutdown; one container may host multiple protocol bindings for a + node (a station reachable via different protocols in different bench + setups). + +### 14.3 Scoping questions (answer before planning) + +1. PROFINET: full device stack vs. targeted RT simulation of one + station profile? Which controller-side tooling (e.g., ABB Compact + Builder) must accept the simulated device? +2. COMLI: exact CI51x/CI522 variants in scope; is TCP encapsulation + sufficient, or is the serial CI variant also needed? +3. Are both protocols needed, or is one the realistic FAT target? + (COMLI is far smaller in scope; PROFINET conformance is the larger + effort by an order of magnitude.) +4. Which I/O module families per protocol (S800 modules via + PROFINET/COMLI interfaces; WAGO 750 modules over Modbus as today)? + +### 14.4 Acceptance criteria (draft) + +1. An AC800M controller (or a protocol-level test master representing + one) establishes data exchange with the simulated I/O station and + reads/writes the documented process data. +2. The existing scenario DSL drives input changes and observes output + reactions through the new protocol binding, unchanged. +3. Verbose tracing shows per-protocol decoded traffic with device + annotations; fault-injection steps behave like the Modbus + equivalents. +4. The 750-362 Modbus behavior is unaffected (regression suite green). + +--- + +## 15. Roadmap (post-framework) | Phase | Feature | |---|---| @@ -1138,11 +1327,14 @@ connected PLC sees a controlled fieldbus-node failure rather than a | 4 | FAT report generator (HTML/PDF), scenario comparison, template library per project type | | 5 | Multi-node orchestration (several couplers in one FAT bench), UDP variant, WBM simulation; **web UI (§10)**; **runtime device configuration (§11)**: module hot-configuration with image rebuild, DIP-switch emulation, WBM-equivalent pages, device-state persistence | | 6 | CI integration: run scenarios headless, export JUnit XML | +| ? | **Multi-vendor device profiles (§13)** and **additional fieldbus protocols PROFINET/COMLI (§14)** — not yet scheduled; phase assignment after §13.3/§14.3 scoping | --- -## 14. References +## 16. References - WAGO 750-362 manual `m07500362_xxxxxxxx_0en.pdf`, sections 7.2–7.3 (process image), 11.2 (Modbus), 12.2 (module data architecture) - WAGO I/O System 750 system description `m075xxxxx_xxxxxxxx_0en.pdf` -- MODBUS Application Protocol Specification V1.1b3 / MODBUS TCP specification (modbus.org) \ No newline at end of file +- MODBUS Application Protocol Specification V1.1b3 / MODBUS TCP specification (modbus.org) +- ABB CI51x/CI522 communication interface and S800/S900 I/O documentation (COMLI) +- PROFINET specification (PI, profibus.com) — if PROFINET scope is confirmed \ No newline at end of file