# Software Specification

**WAGO Modbus TCP Simulator — Autonomous FAT Testing Framework**

| | |
|---|---|
| Project | `wago-modbustcp-simulator-py` |
| Version | 1.1 (Draft for review) |
| Date | 2026-10-03 |
| Status | Framework phase; module addressing implemented (FR-4.3.11); long-duration simulation (§8), bench mode (§9) and web UI (§10) 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) |

---

## 1. Introduction

### 1.1 Purpose

This document specifies a software system that **simulates a WAGO 750-362 Modbus TCP fieldbus coupler** on a standard PC, to be used as a test bench during **Factory Acceptance Tests (FAT)** of PLC programs.

During FAT the PLC under test is normally wired to a real WAGO I/O node. This simulator replaces the physical node entirely: the PLC (or any Modbus TCP master/SCADA) connects over TCP/IP to the simulator, which responds exactly like a 750-362 coupler — same function codes, same register map, same exception behavior, same timing characteristics.

### 1.2 Problem being solved

FAT of PLC programs requires either:

1. Physical I/O hardware (expensive, must be wired per project, error-prone, single-purpose), or
2. A generic Modbus slave (does not implement the WAGO-specific register map, digital-channel addressing, watchdog, statistics, or module-diagnostics behavior; PLC programs validated against it may fail against a real node).

The simulator provides the **exact WAGO behavior** plus **scriptable, autonomous scenario execution**, so a complete FAT round — including fault cases — can run unattended and produce a machine-verifiable result.

### 1.3 Scope

In scope (v1.0 framework):

- Modbus TCP server (slave) with the 750-362 function-code set.
- WAGO 750-362 register map: process image (words + bits), configuration, diagnostic, constant, and firmware-info registers.
- Virtual I/O node: a configurable list of WAGO 750/753 I/O modules forming the process image.
- **Scenario engine**: scripted macros that observe input states and act on outputs (the automation core).
- Deterministic simulation clock and scheduler.
- CLI runner with configuration files.

Out of scope (v1.0): HTTP/WBM web interface, FTP, SNMP, UDP variant of Modbus, DHCP/BootP provisioning, real-time behavior beyond response latency simulation, and module parameterization (mailbox traffic) beyond process data.

### 1.4 Definitions

| Term | Meaning |
|---|---|
| PII | Process Input Image — data the coupler presents to the master (from input modules) |
| PIO | Process Output Image — data the master writes (to output modules) |
| MBAP | Modbus Application Protocol header (7-byte TCP header) |
| FC | Modbus function code |
| FAT | Factory Acceptance Test |
| Scenario | A scripted, timed sequence of state changes and assertions |
| Macro | A reusable scripted action (e.g., "pulse output 3 for 500 ms") |
| Node | One simulated fieldbus coupler + its I/O module configuration |
| LTS | Long-Time Simulation — continuous (“soak”) mode running hours to weeks of simulated time |
| Dataset | A CSV time-series file driving designated input aliases in continuous mode |
| Wear counter | Engine-maintained per-alias statistic: runtime hours, edge counts, load-hours |
| Degradation model | Time/cycle-dependent transformation of a plant parameter (e.g., pump capacity) |
| Invariant | A condition that must hold every tick throughout a continuous run |
| Episode | One aggregated violation period of an invariant (bounded reporting) |

---

## 2. System Overview

```mermaid
flowchart LR
    subgraph DUT["Devices under test"]
        PLC["PLC 1..n\n(Modbus TCP masters)"]
    end

    subgraph SIM["Simulator (this system)"]
        MB["Modbus TCP Server\n(asyncio, ≤ 15 connections)"]
        DS["Datastore\n(WAGO word & bit maps)"]
        NODE["Virtual WAGO Node\n(module list → process image)"]
        SE["Scenario Engine\n(states → actions)"]
        CLK["Deterministic Clock\n+ Scheduler"]
        LOG["Event Log / Traces"]
    end

    PLC -- "MBAP frames (FC1..FC23)" --> MB
    MB <--> DS
    DS <--> NODE
    SE -- "read inputs / write outputs" --> NODE
    SE <--> CLK
    NODE -- change events --> SE
    LOG -.records.- MB
    LOG -.records.- SE
```

The system is a pure **slave/server**: it never initiates Modbus traffic. Autonomy comes from the **scenario engine**, which drives the *field side* of the virtual node (as if sensors moved and actuators did something), while the PLC drives the *master side* through normal Modbus writes.

---

## 3. Functional Requirements — Modbus Server

### 3.1 Transport & connections

- FR-3.1.1: The server shall listen on TCP port 502 (configurable) and speak Modbus TCP with the standard MBAP header.
- FR-3.1.2: The server shall support **up to 15 concurrent Modbus TCP connections** (per 750-362 spec, §7.3). Connection number 16 shall be refused.
- FR-3.1.3: Idle connections shall be closed after the timeout configured in register `0x1030` (default 600 × 100 ms). Outputs remain in last state (§11.2.5.5).
- FR-3.1.4: Protocol identifier other than 0 in MBAP shall increment the `BadProtocol` statistic and be ignored.
- FR-3.1.5: Unit identifier shall be ignored (accepted, echoed back), as on the real device.

### 3.2 Function codes

The simulator shall implement exactly the 750-362 function set (§11.2.2) and reject all others with exception `0x01` (Illegal Function):

| FC | Function | Limits (R/W) |
|----|----------|--------------|
| 01 | Read Coils | 2000 / — |
| 02 | Read Discrete Inputs | 2000 / — |
| 03 | Read Holding Registers | 125 / — |
| 04 | Read Input Registers | 125 / — |
| 05 | Write Single Coil | — / 1 |
| 06 | Write Single Register | — / 1 |
| 11 | Get Comm Event Count | — |
| 15 | Write Multiple Coils | — / 800 |
| 16 | Write Multiple Registers | — / 100 |
| 22 | Mask Write Register | — / 1 |
| 23 | Read/Write Multiple Registers | 125 / 100 |

Exceeding limits → exception `0x03` (Illegal Data Value) and increment `TooManyRegisters` / `TooManyBits`.

Exception codes (§11.2.3): `0x01` Illegal Function, `0x02` Illegal Data Address, `0x03` Illegal Data Value, `0x04` Slave Device Failure, `0x05` Acknowledge, `0x06` Server Busy, `0x08` Memory Parity Error, `0x0A`/`0x0B` Gateway errors.

### 3.3 Register map (WAGO 750-362)

#### 3.3.1 Word (register) access — reading (FC3/FC4)

| Modbus address (hex) | Area | Behavior |
|---|---|---|
| `0x0000–0x00FF` | Physical input area (1), %IW0–255 | First 256 words of input process image |
| `0x0100–0x01FF` | — | Exception `0x02` |
| `0x0200–0x02FF` | Physical output area (1) | Read-back mirror of `%QW0–255` (outputs written at `0x0000` are readable here, +`0x0200` offset) |
| `0x0300–0x0FFF` | — | Exception `0x02` |
| `0x1000–0x2FFF` | Configuration registers | See §3.5 |
| `0x3000–0x5FFF` | — | Exception `0x02` |
| `0x6000–0x62FB` | Physical input area (2), %IW256–1020 | Additional 764 words |
| `0x62FC–0x6FFF` | — | Exception `0x02` |
| `0x7000–0x72FB` | Physical output area (2), %QW256–1020 | Read-back mirror, +`0x01000` offset from write area (2) |
| `0x72FC–0xFFFF` | — | Exception `0x02` |

#### 3.3.2 Word access — writing (FC6/FC16)

| Modbus address (hex) | Area |
|---|---|
| `0x0000–0x00FF` | Physical output area (1), %QW0–255 |
| `0x0100–0x01FF` | Exception `0x02` |
| `0x0200–0x02FF` | Physical output area (1) (mirror accepted for writing) |
| `0x0300–0x0FFF` | Exception `0x02` |
| `0x1000–0x2FFF` | Configuration registers |
| `0x3000–0x5FFF` | Exception `0x02` |
| `0x6000–0x62FB` | Physical output area (2), %QW256–1020 |
| `0x62FC–0x6FFF` | Exception `0x02` |
| `0x7000–0x72FB` | Physical output area (2) (mirror) |
| `0x72FC–0xFFFF` | Exception `0x02` |

#### 3.3.3 Bit (coil) access — reading (FC1/FC2) & writing (FC5/FC15)

| Modbus address (hex) | Area |
|---|---|
| `0x0000–0x01FF` | Physical input area (1) — first 512 digital inputs (read) |
| `0x0200–0x03FF` | Physical output area (1) — first 512 digital outputs (read mirror + write) |
| `0x0800–0x85F7` | Physical input area (2) — digital inputs 513–2039 |
| `0x9000–0x95F7` | Physical output area (2) — digital outputs 513–2039 |
| all others | Exception `0x02` |

**Digital channel addressing rule** (§11.2.4): bit addresses are **channel numbers** — digital input no. 47 has Modbus address 46 — independent of the physical module layout. Word-oriented modules are laid out first (in physical order, from word 0), then bit-oriented modules are byte-packed in physical order.

#### 3.3.4 Constant registers (FC3/FC4 read-only)

| Addr | Value | Purpose |
|---|---|---|
| `0x2000` | `0x0000` | Zero |
| `0x2001` | `0xFFFF` | Ones |
| `0x2002` | `0x1234` | Byte-order check (Intel format expected) |
| `0x2003` | `0xAAAAl` | Bit mask 1 |
| `0x2004` | `0x5555` | Bit mask 2 |
| `0x2005` | `0x7FFF` | Max positive |
| `0x2006` | `0x8000` | Max negative |
| `0x2007` | `0x3FFF` | Half positive |
| `0x2008` | `0x4000` | Half negative |

#### 3.3.5 Firmware-info registers (read-only)

`0x2010` revision, `0x2011` series code (`0x02EE` = 750), `0x2012` coupler code (`0x0166` = 362), `0x2013`/`0x2014` major/minor, `0x2020` description (16 words), `0x2021` compile time, `0x2022` compile date, `0x2023` firmware loader info, `0x2030–0x2033` connected-module descriptions, `0x2035` process-image settings, `0x2036` diagnostics, `0x2040` software reset (write `0x55AA`/`0xAA55`), `0x2043` factory settings.

### 3.4 Watchdog (§11.2.5.2/3)

The Modbus watchdog shall be simulated:

- `0x1000` timeout value ×100 ms (default `0x0064`), writable only when WD inactive.
- `0x1001`/`0x1002` coding masks (bit *n−1* of the mask = FC *n*; default `0xFFFF`).
- `0x1003` trigger (write nonzero, alternating values), `0x1005` stop (`0xAAAA` then `0x5555`), `0x1008` simple stop (`0xAA55`/`0x55AA`), `0x1007` restart (write `1`).
- `0x1006` status: `0` inactive / `1` active / `2` expired.
- `0x1009` close-socket-on-timeout, `0x100A` type Standard/Alternative, `0x100B` save WD params (remanent).
- On timeout: **all analog outputs → 0, all digital outputs → OFF**; in Standard mode further process-data access is answered with exception `0x04`; WD registers remain accessible; `0x1009 = 1` additionally closes TCP connections.
- Watchdog events shall be visible to the scenario engine (assertions: "WD triggered at t seconds").

### 3.5 Configuration & diagnostic registers

- `0x1022`–`0x1025`: image sizes (analog in/out bits, digital in/out bits) computed from the configured module list.
- `0x1029` (9 words) Modbus TCP statistics: SlaveDeviceFailure, BadProtocol, BadLength, BadFunction, BadAddress, BadData, TooManyRegisters, TooManyBits, ModTcpMessageCounter. Reset by writing `0xAA55`/`0x55AA`.
- `0x102A` active TCP connections.
- `0x1030` Modbus TCP idle timeout (×100 ms).
- `0x1031` MAC-ID (3 words, configurable to emulate a specific device).
- `0x1037` response delay (ms) — the simulator shall actually delay responses, to emulate link latency.
- `0x1038` TOS/DSCP (stored, echoed).
- `0x1050` module diagnosis (3 words): module, channel, diagnosis bits (underrange … collective failure) — scriptable fault injection.
- `0x1020`/`0x1021` LED error code/argument — scenario-settable.
- `0x102B` KBUS reset (write): re-reads the module configuration; process image rebuilt.

### 3.6 Fault injection

FR-3.6.1: The scenario engine shall be able to simulate fieldbus faults:

- KBUS/local-bus failure → `SlaveDeviceFailure` statistic increments and process-data reads may return exception `0x04`.
- Response-delay injection via `0x1037`.
- Connection refusal beyond 15 concurrent connections.
- Illegal-address probing (read/write the exception areas) → correct `0x02` responses (this validates master error handling).

### 3.7 Process data semantics

- Word mapping of digital channels follows the **Intel format** (§7.3.3): channel 1 = bit 0 of the low byte (`D0`), high byte `D1` on top.
- Digital word mapping: `Bit15 … Bit0` = `Byte D1 D0`, bit 0 = lowest channel number.
- Analog modules contribute 16-bit data words (control/status bytes not accessible via Modbus).
- A module list defines the image; the framework computes addresses and exposes them in the log and via module-description registers (`0x2030+`).

---

## 4. Functional Requirements — Scenario & Macro Engine

### 4.1 Concept

A **scenario** is a scripted, time-ordered description of the *world around the PLC*: sensor inputs change over time, actuators respond, and the script asserts on PLC outputs. This is what makes FAT autonomous — no operator needs to toggle signals.

- **State-based**: rules keyed on input/output conditions (`when input 5 turns ON …`).
- **Time-based**: scheduled events (`after 30 s …`).
- **Output actions**: `set`, `reset`, `pulse`, `toggle`, `ramp`, `hold_value` on simulated field outputs (what the PLC sees as its inputs).
- **Input observations**: the engine reads the process output image (what the PLC wrote) with edge detection (rising/falling).
- **Assertions**: expected PLC behavior (output X ON within 2 s after input Y) → FAT verdicts.

### 4.2 Scenario DSL (YAML)

```yaml
name: pump_station_fat
description: "Full FAT round for pump station PLC program"
node: config/pump_node.yaml        # module configuration
timing: { tick: 10ms }              # simulation tick

inputs:                             # named aliases → digital/analog inputs
  start_button:   { type: di, module: 0, channel: 0 }     # DI0.0
  level_sensor:   { type: ai, module: 4, channel: 0, scale: 0.1 }   # AI4.0, mm → counts
  em_stop_ok:     { type: di, module: 0, channel: 3 }     # DI0.3

outputs:                            # named aliases → PLC outputs (read-only for script)
  pump_relay:     { type: do, module: 2, channel: 0 }      # DO2.0
  valve_open:     { type: do, module: 2, channel: 1 }      # DO2.1
  speed_setpoint: { type: ao, module: 5, channel: 0, scale: 0.1 }  # AO5.0

macros:
  pulse_start:                     # reusable macro
    - set: start_button = ON
    - wait: 250ms
    - set: start_button = OFF

states:                            # optional state machine
  idle:
    on: { em_stop_ok: ON }
    goto: running
  running:
    entry: [ ramp: level_sensor, to: 8500, over: 30s ]
    on:  { pump_relay: RISING }
    assert: { valve_open: ON, within: 2s }
    goto: full
  ...

sequence:                          # time-ordered script (or fully state-driven)
  - macro: pulse_start
  - assert: { pump_relay: ON, within: 2s }
  - wait: 5s
  - set: level_sensor = 4200
  - assert: { speed_setpoint: ">= 1000", within: 3s }
  - report: PASS
```

### 4.3 Requirements

- FR-4.3.1: Scenarios shall be defined in YAML (no programming required for standard FAT sequences).
- FR-4.3.2: The engine shall support **state machines** (states, entry actions, transitions on input/output edges or conditions, guards).
- FR-4.3.3: The engine shall support **macros** (reusable action groups, parameterizable).
- FR-4.3.4: Actions on simulated inputs: `set`, `reset`, `pulse`, `toggle`, `ramp` (linear over time), `noise` (± band), `sin`, `hold`.
- FR-4.3.5: Assertions on PLC outputs with timeout → **PASS/FAIL/ERROR verdict per check**, with timestamps; final scenario verdict.
- FR-4.3.6: Assertions may compare against expected values, ranges, edges, and statistics registers (e.g., "watchdog expired").
- FR-4.3.7: All scenario events and all Modbus transactions shall be logged (CSV/JSONL) for the FAT report.
- FR-4.3.8: Python **action plugins** shall be supported for actions beyond the built-in set (registered callables), for complex plant-model physics.
- FR-4.3.9: The engine shall run **deterministically**: simulation time decoupled from wall-clock; results reproducible.
- FR-4.3.10: A scenario may load multiple nodes (multi-coupler FAT benches).
- FR-4.3.11: **Module-based channel addressing** — aliases may be addressed
  as *module type + module number + channel number*, all components
  explicitly configurable: `{ type: di, module: 2, channel: 1 }` selects
  digital input channel 1 (0-based) on module slot 2 (0-based position in
  the node's module list), i.e. `DI2.1`. Both numbers are 0-based to match
  physical slot/channel labeling. The channel kind must match the module
  (`DO` on a DI-only module is a validation error). This is an alternative
  to pool addressing (`{ type: di, channel: 3 }` = 3rd DI channel across
  the whole node); both schemes are supported and may be mixed, but an
  alias uses exactly one. **Implemented** in v1.1 (`channel_by_module`,
  `Alias.module`, `alias_location`).

### 4.4 Example FAT flow

1. PLC program boots, connects to simulator (Modbus TCP client), reads input image.
2. Scenario `pump_station_fat` starts in `idle` state; `em_stop_ok` turns ON.
3. Scenario pulses `start_button`; PLC sees input, starts pump relay (writes coil).
4. Engine detects rising edge on `pump_relay`, asserts `valve_open` within 2 s.
5. Scenario ramps `level_sensor` to 8500 counts; PLC adjusts `speed_setpoint`; assertions verify.
6. Scenario injects fault (KBUS error / watchdog timeout); PLC must react (e.g., switch to safe state) — asserted.
7. Report generated: verdicts, timing, Modbus trace.

---

## 5. Architecture

### 5.1 Package layout

```
wago-modbustcp-simulator-py/
├── docs/                       # WAGO manuals + this spec
│   └── spec/
│       ├── software-spec.md    # this document
│       └── register-map.md     # extracted WAGO tables
├── src/
│   └── wago_sim/
│       ├── __init__.py
│       ├── mbap.py             # MBAP frame codec
│       ├── pdu.py              # PDU codec (request/response/exception)
│       ├── server.py           # asyncio Modbus TCP server
│       ├── datastore.py        # WAGO word/coil datastores
│        │   # (holds process images + register bank)
│       ├── registers.py        # config/diagnostic/constant/firmware regs
│       ├── modules.py          # virtual WAGO I/O modules (module catalog)
│       ├── node.py             # node = modules → process image mapping
│       ├── watchdog.py         # Modbus watchdog simulation
│       ├── clock.py            # deterministic clock + scheduler
│       ├── scenario/
│       │   ├── __init__.py
│       │   ├── engine.py       # interpreter for scenario DSL
│       │   ├── dsl.py          # YAML schema + validation
│   │   │   ├── actions.py      # set/pulse/ramp/... + plugin registry
│   │   │   ├── assertions.py   # condition matcher
│   │   │   ├── statemachine.py
│       │   └── report.py       # verdicts, CSV/JSONL log
│       ├── stats.py            # Modbus TCP statistics counters
│       ├── logging_setup.py
│       └── cli.py              # entry point (argparse)
├── config/
│   └── pump_node.yaml          # example node configuration
├── scenarios/
│   └── pump_station_fat.yaml   # example scenario
├── tests/
│   ├── test_mbap.py
│   ├── test_pdu.py
│   ├── test_server.py
│   ├── test_datastore.py
│   ├── test_registers.py
│   �   ├── test_watchdog.py
│   ├── test_scenario_engine.py
│   └── conftest.py
├── pyproject.toml
└── README.md
```

### 5.2 Design decisions

| Decision | Rationale |
|---|---|
| Pure-Python, asyncio TCP server | No external Modbus library needed; full control over WAGO-specific behavior (register-map exceptions, statistics, watchdog); testable |
| Deterministic clock | Reproducible FAT runs; scenario times independent of host speed |
| YAML DSL + plugin boundary | Test engineers write scenarios, not code; complex physics via Python plugins |
| Datastore split: process image vs. register bank | Mirrors real device: process image vs. internal registers; the readback-mirror rule (+0x0200) is dataflow, not copy-on-read |
| Statistics as first-class objects | FAT assertions can check communication health (`0x1029`) |

### 5.3 Threading & concurrency model

- asyncio event loop owns the Modbus server and the scheduler tick.
- Scenario engine runs in the same loop (coroutines), so image updates and Modbus reads see consistent data without locks.
- Response delay (`0x1037`) implemented as asyncio sleep before response send.

### 5.4 Data model

```mermaid
erDiagram
    NodeConfig ||--|{ ModuleConfig : modules
    NodeConfig ||--|| ProcessImage : builds
    ModuleConfig ||--|{ Channel : channels
    ProcessImage ||--|| InputImage : inputs
    ProcessImage ||--|| OutputImage : outputs
    OutputImage ||--|| InputMirror : "read-back at +0x200/+0x1000"
    Scenario ||--|{ State : states
    Scenario ||--|{ SequenceStep : sequence
    State ||--|{ Action : entry
    State ||--|{ Transition : on
    SequenceStep ||--|{ Action : actions
    Scenario ||--|{ Alias : "inputs/outputs aliases"
    Scenario ||--|{ Macro : macros
    Macro ||--|{ Action : steps
```

### 5.5 State chart — server session

```mermaid
stateDiagram-v2
    [*] --> Listening
    Listening --> Connected: TCP accept (≤15)
    Connected --> RequestParsing: MBAP complete
    RequestParsing --> Dispatching: PDU decoded
    Dispatching --> Responding: result
    Dispatching --> ExceptionResponse: FC/addr/val error
    Responding --> Connected
    ExceptionResponse --> Connected
    RequestParsing --> Connected: malformed (count BadLength)
    Connected --> Closed: idle timeout / WD 0x1009=1 / client close
```

---

## 6. Non-Functional Requirements

- NFR-6.1 Performance: sustain ≥ 500 requests/s with ≤ 10 ms added latency (typical FAT bench load).
- NFR-6.2 Portability: Python 3.11+ on Windows/Linux.
- NFR-6.3 Determinism: two runs of a scenario with identical inputs and timing produce identical verdict logs (except wall-clock stamps).
- NFR-6.4 Observability: every Modbus transaction logged with timestamps (sim-time + wall-time), PDU hex, connection id.
- NFR-6.5 Robustness: malformed frames never crash the server; counted in statistics.
- NFR-6.6 Configurability: port, bind address, node config, firmware identity registers, MAC-ID configurable without code changes.

---

## 7. Acceptance Criteria (framework phase)

1. A Modbus TCP master (e.g., `pymodbus` client in tests) can connect, read constants `0x2000–0x2008`, and gets exactly `0x0000, 0xFFFF, 0x1234, 0xAAAA, 0x5555, 0x0166, ...` per spec — byte order verified.
2. Reads/writes in all mapped/unmapped areas produce values/exceptions per §3.3 tables.
3. Digital channel addressing: a configured 16-channel DI module + 8-channel DO module yields channel-number bit addressing (DI 47 → bit address 46).
4. Output readback mirrors at +`0x0200` (word) and +`0x0200`/+`0x1000` (bit/word area 2) work.
5. A YAML scenario can set a digital input, detect a PLC output rising edge, and produce a PASS/FAIL report file.
6. Watchdog: configure `0x1000`, trigger via `0x1003`, let it expire, outputs clear, `0x1006` = 2, process access → exception `0x04`, restart via `0x1007`.
7. Statistics counters increment correctly on bad frames/addresses; reset via `0x1029` write `0xAA55`.

---

## 8. Feature Request — Long-Duration (Continuous) Simulation

> **Status: requested 2026-10-03, planned (roadmap phase 3), not yet implemented.**
> Extends the scenario engine (§4) with a `continuous` mode for endurance
> (“soak”) testing: the facility runs for hours, days or weeks of simulated
> time against evolving inputs and an aging plant.

### 8.1 Motivation

FAT rounds (§4) validate functional behavior over minutes. A facility must
additionally be proven **over long time**:

- **Endurance/soak**: memory leaks, counter rollovers, watchdog stability over days.
- **Trend & historian verification**: SCADA trends, averaging, alarm shelving.
- **Cycle behavior**: daily/weekly demand profiles, shift patterns, weekend idle.
- **Maintenance logic**: wear-based alarms, degradation detection, service recovery.
- **Clock edge cases**: midnight rollovers and (via absolute-timestamp datasets) DST transitions.

Long runs cannot be hand-scripted step by step. Two mechanisms replace the
scripted `sequence`:

1. **Dataset playback** — designated inputs are driven from time-series files
   (e.g., CSV exported from a plant historian, or synthesized profiles).
2. **Degradation models** — plant-model parameters (e.g., pump capacity)
   degrade as a function of runtime and cycles, exercising the PLC’s
   compensation and maintenance logic.

### 8.2 Requirements — continuous mode & CSV dataset playback

- FR-8.2.1: A scenario may declare `mode: continuous`. The `sequence` becomes
  optional; the run continues until the dataset schedule (plus any `until:`
  duration) is exhausted.
- FR-8.2.2: Input aliases (di/ai) may be driven from **datasets**. Output
  aliases must not appear in datasets (validation error). An endogenous process
  variable (e.g., tank level) may instead be computed by a plant-model plugin
  (FR-4.3.8, closed loop). **Exactly one driver** may own an alias (dataset,
  plugin-declared variable, ramp, pulse, or step) — conflicts are validation errors.
- FR-8.2.3: CSV format: a header row with the time column (default `time`,
  configurable via `time_column`) plus one column per alias. Time is elapsed
  seconds (default) or ISO-8601 absolute timestamps (`time_format: iso8601`).
  Analog values are numeric; digital values accept `ON/OFF`, `1/0`,
  `true/false`. Lines starting with `#` are comments.
- FR-8.2.4: Values pass through the alias `scale`/`offset` (engineering
  units → raw counts), identical to `set:` semantics.
- FR-8.2.5: Between samples, analog aliases use per-dataset
  `interpolation: linear | hold`; digital aliases always use `hold` (never
  interpolated).
- FR-8.2.6: Datasets shall be **streamed with bounded memory** (one-row
  lookahead); files covering months of samples must be playable without
  loading them into RAM.
- FR-8.2.7: `repeat: n` loops a dataset seamlessly and monotonically (no time
  jump at the seam); identical loops produce identical values (deterministic).
  `until: <duration>` limits total playback.
- FR-8.2.8: `time_factor: k` (default 1.0) — dataset time advances k× faster
  than sim-time, enabling a 28-day soak in a fraction of the wall-clock time.
- FR-8.2.9: Multiple datasets share one sim-time axis; each has an optional
  `offset:` start shift. The engine merges them; an alias’s value is that of
  its owning dataset.
- FR-8.2.10: **Pacing**: in server mode (real PLC connected) sim-time follows
  wall-clock for real-time soak testing; headless runs are unpaced (as fast
  as deterministic processing allows).
- FR-8.2.11: Malformed data (unknown column, unparsable time or value,
  non-monotonic timestamps) ends the run with verdict **ERROR**, citing file
  and line number.

### 8.3 Requirements — degradation models (plant logic over time)

- FR-8.3.1: The engine maintains **wear counters** per alias, updated every
  tick: runtime hours (integral of truth), edge counts (rising/falling), and
  load-hours (integral of the analog value). Counters are deterministic state.
- FR-8.3.2: A **degradation model** computes a named plant parameter (e.g.
  `pump_capacity`, range 0…1) from wear counters and sim-time. Built-in
  shapes: `linear` (per runtime hour, per start cycle), `exponential`,
  `staircase` (threshold table); custom shapes via Python plugin.
- FR-8.3.3: Plant-model plugins read degraded parameters via
  `engine.parameter("pump_capacity")` and shall use them in the loop physics
  (e.g., actual pump flow = nominal flow × capacity), so the PLC must
  compensate (e.g., speed creep) — the behavior under test.
- FR-8.3.4: `maintenance_at:` threshold crossing fires configured actions:
  fault injection (module diagnosis, register `0x1050`), assertions
  (maintenance alarm within a time bound), and logging. A
  `maintenance_reset` restores the parameter to 1.0 and clears injected
  diagnoses — verifying the PLC’s alarm clearing and performance recovery.
- FR-8.3.5: `floor:`/`ceiling:` clamp the parameter so the simulated plant
  stays physically plausible.
- FR-8.3.6: Models must be pure functions of (sim-time, wear counters,
  configuration) — no wall-clock — keeping runs reproducible.
- FR-8.3.7: Degradation state and wear counters are included in snapshots
  (§8.4) and the final report.
- FR-8.3.8: New DSL actions introduced: `inject_diagnosis` / `clear_diagnosis`
  (module-diagnosis fault injection) and `maintenance_reset`.

### 8.4 Requirements — continuous assertions & monitoring

- FR-8.4.1: `invariants:` — conditions evaluated **every tick** (analog
  bounds, expected digital states). Violations are recorded as **episodes**
  (start, end, extreme value, tick count) so a 30-day run yields a bounded
  report, not a per-tick flood.
- FR-8.4.2: `rate_limits:` — maximum rising/falling edges per sliding hour
  window per alias (e.g., pump starts ≤ 6/h), verifying anti-cycling logic.
- FR-8.4.3: `report.snapshot_every: <duration>` — periodic dumps of all
  alias values, wear counters, and degradation parameters (CSV/JSONL) for
  trend/historian verification.
- FR-8.4.4: Continuous-mode verdict: **PASS** iff the dataset schedule
  completed, no invariant episode occurred, no rate limit was exceeded, and
  no assertion failed; otherwise FAIL/ERROR accordingly.
- FR-8.4.5: Report and log sizes shall be bounded independent of run length
  (episode aggregation + ring-buffered recent events).
- FR-8.4.6: A limited `sequence:` may still be used in continuous mode;
  steps may be scheduled via `at: <sim duration>` (e.g., a service visit at
  day 12). Scheduled steps and datasets interleave on the same sim-time axis.

### 8.5 Example — 28-day pump-station soak

Scenario (YAML):

```yaml
name: pump_station_soak_28d
description: "28-day soak: demand/operator playback, closed-loop plant with pump degradation"
mode: continuous
timing: { tick: 100ms }

inputs:
  start_button:  { type: di, channel: 1 }                 # exogenous (operator, CSV)
  em_stop_ok:    { type: di, channel: 2 }                 # exogenous (CSV)
  inflow_valve:  { type: di, channel: 3 }                 # exogenous (CSV)
  inflow_rate:   { type: ai, channel: 2, scale: 0.01 }    # exogenous (CSV), m³/h → counts
  level_sensor:  { type: ai, channel: 1, scale: 0.1 }     # endogenous (plant model computes)

outputs:
  pump_relay:        { type: do, channel: 1 }
  valve_open:        { type: do, channel: 2 }
  speed_setpoint:    { type: ao, channel: 1, scale: 0.1 }
  maintenance_alarm: { type: do, channel: 3 }

datasets:
  demand_week:                       # exogenous demand profile
    file: data/demand_week.csv
    aliases: [inflow_rate]
    interpolation: linear
    repeat: 4                        # 7-day profile × 4 = 28 sim-days
  operator_week:                     # operator actions
    file: data/operator_week.csv
    aliases: [start_button, em_stop_ok, inflow_valve]
    interpolation: hold
    repeat: 4

degradation:
  pump_wear:
    model: linear
    parameter: pump_capacity         # consumed by the plant model
    per_runtime_hour: 0.0004         # 0.04 %/h → ~10 % after ~10.4 sim-days
    per_start_cycle: 0.0002          # 0.02 % per start
    floor: 0.80
    maintenance_at: 0.90
    on_threshold:                    # fires when capacity crosses 90 %
      - inject_diagnosis: { module: 4, channel: 1, bits: [user_overrange] }
      - assert: { label: "maintenance alarm raised",
                  conditions: { maintenance_alarm: ON }, within: 60s }
    on_reset:                        # after maintenance_reset
      - clear_diagnosis: { module: 4 }

sequence:                           # scheduled events (sim-time)
  - at: 12d
    maintenance_reset: pump_wear     # service visit: capacity restored

plugins: [plugins.pump_plant.pump_plant]   # loop: d(level)/dt = inflow − pump_flow(speed, capacity)

invariants:
  - { alias: level_sensor, min: 200, max: 9000, label: "tank level bounds" }

rate_limits:
  - { alias: pump_relay, edge: rising, max_per_hour: 6, label: "pump start cycles" }

report:
  snapshot_every: 1h
  aggregate: episodes
```

Datasets (CSV):

```csv
# data/demand_week.csv  (elapsed seconds, inflow in m³/h)
time,inflow_rate
0,12.0
3600,12.4
7200,13.1
...
604800,12.0        # week boundary — loops seamlessly with repeat: 4
```

```csv
# data/operator_week.csv
time,start_button,em_stop_ok,inflow_valve
0,OFF,ON,OFF
28800,ON,ON,ON     # Mon 08:00: shift start, valve opened
28810,OFF,ON,ON
432000,OFF,OFF,ON  # Sat 00:00: weekend e-stop drill
440000,OFF,ON,ON
```

### 8.6 Architecture impact (planned modules)

```
src/wago_sim/scenario/
├── datasets.py        # CsvDataset: streaming reader, interpolation, repeat, time_factor
├── degradation.py     # WearCounters, DegradationModel registry, maintenance actions
├── invariants.py      # invariant & rate-limit evaluation, episode aggregation
└── engine.py          # mode: continuous, parameter() accessor, snapshot scheduler
```

```mermaid
erDiagram
    ContinuousScenario ||--|{ Dataset : datasets
    Dataset ||--|{ ColumnMapping : "alias columns"
    ContinuousScenario ||--|{ DegradationModel : degradation
    DegradationModel ||--|{ WearCounter : counts
    WearCounter }o--|| Alias : observes
    ContinuousScenario ||--|{ Invariant : invariants
    Invariant ||--o{ Episode : violations
    ContinuousScenario ||--|{ RateLimit : rate_limits
    ContinuousScenario ||--o{ Snapshot : "periodic dumps"
    PlantPlugin }o--|| DegradationModel : "reads parameters"
```

### 8.7 Non-functional requirements (long-duration)

- NFR-8.7.1: Memory O(1) in dataset length and run duration (streaming +
  bounded caches).
- NFR-8.7.2: A 28-sim-day soak with two datasets completes headless in
  ≤ 1 hour wall-clock on a standard PC (budget to be confirmed after
  implementation).
- NFR-8.7.3: Determinism incl. degradation: identical config + datasets
  produce identical reports (except wall-clock stamps).
- NFR-8.7.4: Robustness: host sleep/hibernate or GC pauses never distort
  sim-time or dataset position (sim-time accumulates by tick, never from
  wall-clock deltas — except when explicitly paced per FR-8.2.10).
- NFR-8.7.5: Report and log artifacts stay bounded (FR-8.4.5 mechanism),
  enabling unattended multi-day runs.

### 8.8 Acceptance criteria (long-duration simulation)

1. A ≥ 100,000-row CSV streams with constant memory; alias values at
   arbitrary ticks match the expected interpolation exactly.
2. `linear` interpolation for analog and `hold` for digital verified against
   hand-computed samples; digital aliases are never interpolated.
3. `repeat: 4` of a 7-day dataset produces four identical per-loop value
   sequences (seamless seam, deterministic).
4. `time_factor: 10` consumes a 7-day dataset in 16.8 h of sim-time.
5. An alias-ownership conflict (dataset + ramp on one alias) is rejected at
   validation time.
6. Degradation: `pump_capacity` declines per the configured formula; crossing
   `maintenance_at` injects the configured diagnosis and the maintenance-alarm
   assertion passes; `maintenance_reset` restores capacity to 1.0 and clears
   the diagnosis.
7. An invariant breach is recorded as one episode (start, end, peak)
   regardless of duration; a rate-limit breach fails the run.
8. A full 28-sim-day soak completes headless with a bounded report and a
   correct PASS/FAIL/ERROR verdict.

---

## 9. Feature Request — Bench Mode (Run Without a Scenario)

> **Status: requested 2026-10-03, planned (roadmap phase 2), partially
> available today.** `wago-sim serve --node <config>` already runs the
> Modbus TCP server with a static process image and no scenario engine;
> this section formalizes the mode and its supporting tooling.

### 9.1 Motivation

Early commissioning and interactive troubleshooting do not follow a
script: an engineer wants the virtual node up, connected to the PLC/SCADA,
and then *manually* observe and tweak values — the way one would probe a
real node with a screwdriver and a multimeter. Requiring a scenario file
for this is friction; a syntax error in an unrelated YAML file should not
block a bench session.

Bench mode is also the foundation for manual FAT exploration and for the
web UI (§10), which needs a long-lived node whose I/O can be manipulated
at runtime without a scenario driving it.

### 9.2 Requirements

- FR-9.2.1: `wago-sim serve --node <config>` shall start the Modbus TCP
  server with **no scenario** attached: the process image starts at
  defined defaults (all-zero), the watchdog/statistics behave normally,
  and the server runs until terminated. *(Available today.)*
- FR-9.2.2: `--set alias=value` CLI options (repeatable) shall seed input
  values at startup, e.g. `--set DI0.1=ON --set AI4.0=1234`, addressing
  channels by the module notation of FR-4.3.11. Optional in v1: a small
  startup-commands file for larger value sets.
- FR-9.2.3: An interactive **console monitor** (`--monitor`): periodically
  prints a compact table of all I/O channels (module, type, address,
  value) and highlights changes, so a bench session is observable in a
  terminal without any UI.
- FR-9.2.4: Runtime manipulation via the console monitor: simple commands
  (`set DI0.1 ON`, `pulse DO2.0 500ms`, `watch 0x1029`, `reset stats`) —
  the same operations the web UI (§10) offers, over stdio.
- FR-9.2.5: `serve` shall be combinable with a scenario later (`--scenario`
  becomes optional); running with neither scenario nor monitor prints a
  hint that the node is passive and values can only be changed by a master
  or via the web UI.
- FR-9.2.6: The console monitor and web UI (§10) must never violate device
  semantics — manipulations go through the same datastore paths as Modbus
  writes, so read-back mirrors, watchdog kicks, and statistics stay
  consistent.

### 9.3 Acceptance criteria

1. `wago-sim serve --node config/pump_node.yaml` starts with no scenario
   file present and serves a static image; a pymodbus client can read and
   write process data.
2. `--set DI0.1=ON` seeds the corresponding input bit; a master reading
   bit address 0 sees ON.
3. The console monitor shows the full channel table and flags value
   changes within one refresh interval.
4. Console `set`/`pulse`/`watch` commands affect the image immediately and
   are visible to a connected master in the same way Modbus writes are.

---

## 10. Feature Request — Web UI (I/O Overview & Manipulation)

> **Status: requested 2026-10-03, planned (roadmap phase 5), not yet
> implemented.** A browser front-end overlooking and manipulating the
> simulated node's I/O values and states at runtime.

### 10.1 Motivation

Terminal monitors (§9) suffice for single engineers, but FAT benches are
  collaborative: commissioning engineers, PLC programmers, and test
  witnesses need a **shared, visual** view of the virtual I/O — the
  equivalent of watching the LEDs on a real WAGO node, plus the ability to
  force signals the way WAGO's own WBM does on real devices. A web UI keeps
  the simulator usable from any machine on the bench network without
  installing tools.

### 10.2 Requirements

- FR-10.2.1: The simulator shall serve a web UI (default port 8080,
  configurable) alongside the Modbus TCP server, with no external backend
  dependencies beyond Python (FastAPI/Starlette + static files, or an
  equivalent embedded approach — implementation choice, to be decided).
- FR-10.2.2: The UI shall present the **node overview**: module list with
  article numbers, per-module channel tables (type, module, channel,
  addressing `DI0.1` per FR-4.3.11, Modbus address, current value/state),
  derived from the same process image the Modbus server serves.
- FR-10.2.3: Values shall update live (WebSocket push or short-polling),
  including changes made by the PLC/master over Modbus, by scenarios, by
  the console monitor, or by other UI clients — one shared source of truth.
- FR-10.2.4: **Manipulation**: clicking a DI/DO toggles it; an AI/AO gets a
  numeric input (engineering units, using alias scale/offset when
  defined); `pulse` (with duration) and `ramp` (target + duration) actions
  on DI/DO/AI. All writes go through the datastore's Modbus-equivalent
  paths (FR-9.2.6) so mirrors, watchdog, and statistics stay consistent.
- FR-10.2.5: **Diagnostics view**: watchdog status (0x1006), statistics
  block (0x1029, with reset button), module diagnosis (0x1050), LED error
  registers (0x1020/0x1021) — mirroring WBM pages of the real device —
  with controls to inject/clear faults for FAT fault cases.
- FR-10.2.6: A scenario/run view: which scenario (if any) is loaded,
  current step, verdicts so far, and basic controls (start/abort). Headless
  result reports (JSONL/CSV) remain downloadable via the CLI.
- FR-10.2.7: Multi-client consistency: several simultaneous browser
  clients see the same state; forced values propagate to all clients and
  to the Modbus side within one refresh interval.
- FR-10.2.8: Access control for shared benches: optional read-only mode
  and (v2) token-based login, so witnesses can observe without accident
  rights.
- FR-10.2.9: The UI must not disturb deterministic scenario runs: when a
  scenario owns an alias, UI writes to it are rejected with a clear
  message (alias-ownership rules of §8 FR-8.2.2 apply).

### 10.3 Architecture sketch (planned)

```
src/wago_sim/
├── webui/
│   ├── __init__.py
│   ├── app.py          # HTTP + WebSocket server (asyncio, same loop as Modbus)
│   ├── api.py          # REST endpoints: node layout, values, writes, diagnostics
│   └── static/         # single-page front-end (no build step)
```

The web server runs **in the same asyncio event loop** as the Modbus TCP
server, so a UI write and a Modbus read never race on the datastore.

### 10.4 Acceptance criteria

1. Opening the UI shows the node's module list and channel table exactly
   as configured, with `DI0.1`-style addresses and Modbus addresses.
2. Toggling a DO in the browser is immediately visible to a connected
   Modbus master (and vice versa: a master write appears in the UI within
   one refresh interval).
3. Forcing an AI value uses engineering units and the configured scale.
4. The diagnostics page shows live watchdog status and statistics; the
   reset button clears the counters (register 0x1029 semantics).
5. With a running scenario, writes to scenario-owned aliases are rejected
   with a visible message; the scenario continues unaffected.
6. Two simultaneous browsers stay consistent with each other and with
   the Modbus image.

---

## 11. Roadmap (post-framework)

| Phase | Feature |
|---|---|
| 2 | Module catalog expansion (analog, counter, SSI, DALI/DSI, serial modules), mailbox parameters; **bench mode tooling (§9)**: `--set` seeding, console monitor, runtime manipulation commands |
| 3 | **Long-duration simulation (§8)**: CSV dataset playback, degradation models, invariants, soak-test reporting |
| 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)** |
| 6 | CI integration: run scenarios headless, export JUnit XML |

---

## 12. 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)