jobe/wago-modbustcp-simulator-py
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

🚧 WIP

Browse Source
This commit is contained in:
Jonas Bengtsson
2026-10-03 18:54:37 +02:00
parent ba8df075c3
commit 1aa7aa8767
13 changed files with 1167 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/wago_sim/cli.py
+182 -19
View File
@@ -5,6 +5,24 @@ Examples::
wago-sim serve --node config/pump_node.yaml --port 502
wago-sim run --node config/pump_node.yaml --scenario scenarios/pump_station_fat.yaml
wago-sim validate --scenario scenarios/pump_station_fat.yaml
Verbose mode (``-v`` / ``--verbose`` / env ``WAGO_SIM_VERBOSE=1``) enables
DEBUG logging: every Modbus request and response is then traced in
plain text, e.g.::
REQ txn=0x0001 unit=1 FC03 Read Holding Registers
addr=0x2002 count=1 [config/constant regs 0x2002]
RSP txn=0x0001 unit=1 FC03 -> 1 regs: [0x1234]
Service/container operation: every `serve` option can also come from
environment variables (WAGO_SIM_NODE, WAGO_SIM_HOST, WAGO_SIM_PORT),
and the server shuts down gracefully on SIGINT/SIGTERM (docker stop,
systemctl stop/restart).
Error handling: invalid arguments and unreadable/invalid input files
produce a clean one-line ``wago-sim: error: ...`` message on stderr and
exit code 2 — never a Python traceback. (Unexpected internal errors keep
their traceback so they can be reported as bugs.)
"""
from __future__ import annotations
@@ -13,42 +31,140 @@ import argparse
import asyncio
import inspect
import logging
import os
import signal
import sys
from pathlib import Path
import yaml
from .app import build_app
from .modules import ChannelMismatch, ModuleUnknown
from .scenario.dsl import load_node_modules, load_yaml, validate_scenario
from .scenario.engine import ScenarioEngine
from .scenario.engine import ScenarioEngine, ScenarioError
from .scenario.report import result_summary, write_csv, write_jsonl
log = logging.getLogger("wago_sim.cli")
def _build_logger(verbose: bool) -> None:
# Stream logs unbuffered & single-line so they work in docker/systemd
logging.basicConfig(
level=logging.DEBUG if verbose else logging.INFO,
format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
stream=sys.stdout,
force=True,
)
def _fail(message: str, code: int = 2):
"""Report a bad-argument / bad-configuration error cleanly and exit.
Prints a one-line ``wago-sim: error: ...`` to stderr (never a
traceback) and raises SystemExit with `code` (2 = usage error).
"""
print(f"wago-sim: error: {message}", file=sys.stderr)
raise SystemExit(code)
def _port_type(value: str) -> int:
"""argparse type: TCP port 1..65535.
Rejected at parse time with a clean message instead of failing
later with ``OverflowError: bind(): port must be 0-65535``.
"""
try:
port = int(value)
except ValueError:
raise argparse.ArgumentTypeError(f"invalid port number: {value!r}") from None
if not 1 <= port <= 65535:
raise argparse.ArgumentTypeError(f"port must be 1-65535, got {port}")
return port
def _env(name: str, default: str) -> str:
"""Environment override for CLI defaults (service operation)."""
return os.environ.get(name, default)
def _env_port(name: str, default: int) -> int:
"""WAGO_SIM_PORT with the same validation as --port (argparse does
not type-check defaults, so env values must be validated here)."""
raw = os.environ.get(name, str(default))
try:
return _port_type(raw)
except argparse.ArgumentTypeError as exc:
_fail(f"{name}: {exc}")
def _env_flag(name: str) -> bool:
"""Truthy env flag for service/container operation ('1', 'true', 'yes')."""
return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
def _load_yaml_file(path: str, what: str) -> dict:
"""Load a YAML file with clean CLI errors (missing / unparsable).
`what` names the file kind in messages, e.g. "node config".
"""
p = Path(path)
if not p.is_file():
_fail(f"{what} file not found (or not a file): {path}")
try:
return load_yaml(p)
except ScenarioError as exc:
_fail(f"{what} file {path}: {exc}")
except yaml.YAMLError as exc:
_fail(f"{what} file {path} is not valid YAML:\n {exc}")
def _prepare_report_path(path: str, option: str) -> Path:
"""Validate a report output path upfront (before the run starts).
Creates missing parent directories so a fresh clone works without
a manual `mkdir out/`; unwritable locations fail here with a clean
error instead of losing the verdict after a long scenario run.
"""
p = Path(path)
try:
p.parent.mkdir(parents=True, exist_ok=True)
except OSError as exc:
_fail(f"cannot create directory for {option} ({path}): "
f"{exc.strerror or exc}")
return p
async def _serve(args: argparse.Namespace) -> int:
node_config = load_yaml(args.node)
node_config = _load_yaml_file(args.node, "node config")
modules = load_node_modules(node_config)
app = build_app(modules=modules, host=args.host, port=args.port)
await app.server.start()
print(f"Simulating WAGO 750-362 with {len(modules)} modules "
f"on {args.host}:{args.port} (Ctrl+C to stop)")
# Graceful shutdown on SIGINT/SIGTERM (docker stop, systemctl stop).
# asyncio.run installs a SIGINT handler; SIGTERM arrives as a raw
# signal on the main thread — route both to the stop event.
loop = asyncio.get_running_loop()
stop = asyncio.Event()
for sig in (signal.SIGTERM,):
try:
loop.add_signal_handler(sig, stop.set)
except NotImplementedError: # pragma: no cover - Windows
pass
try:
await asyncio.Event().wait()
await stop.wait()
except asyncio.CancelledError:
pass
pass # SIGINT via asyncio.run's handler
finally:
await app.server.stop()
return 0
def _run_scenario(args: argparse.Namespace) -> int:
node_config = load_yaml(args.node)
node_config = _load_yaml_file(args.node, "node config")
modules = load_node_modules(node_config)
scenario = load_yaml(args.scenario)
scenario = _load_yaml_file(args.scenario, "scenario")
problems = validate_scenario(scenario)
if problems:
@@ -57,8 +173,18 @@ def _run_scenario(args: argparse.Namespace) -> int:
print(f" - {p}", file=sys.stderr)
return 2
# validate report destinations BEFORE running: a bad path must not
# lose the verdict of an hours-long scenario
report_jsonl = (_prepare_report_path(args.report_jsonl, "--report-jsonl")
if args.report_jsonl else None)
report_csv = (_prepare_report_path(args.report_csv, "--report-csv")
if args.report_csv else None)
app = build_app(modules=modules)
engine = ScenarioEngine(app.node, scenario)
try:
engine = ScenarioEngine(app.node, scenario)
except (ScenarioError, ChannelMismatch, IndexError, ValueError) as exc:
_fail(f"scenario {args.scenario}: {exc}")
engine.start()
result = None
max_ticks = 2_000_000
@@ -70,15 +196,15 @@ def _run_scenario(args: argparse.Namespace) -> int:
print("Scenario did not terminate (tick limit reached)", file=sys.stderr)
return 3
print(result_summary(result))
if args.report_jsonl:
write_jsonl(result, args.report_jsonl)
if args.report_csv:
write_csv(result, args.report_csv)
if report_jsonl:
write_jsonl(result, report_jsonl)
if report_csv:
write_csv(result, report_csv)
return 0 if result.passed else 1
def _validate(args: argparse.Namespace) -> int:
scenario = load_yaml(args.scenario)
scenario = _load_yaml_file(args.scenario, "scenario")
problems = validate_scenario(scenario)
if problems:
print("Scenario validation problems:")
@@ -94,13 +220,28 @@ def main(argv: list[str] | None = None) -> int:
prog="wago-sim",
description="WAGO 750-362 Modbus TCP simulator for PLC FAT testing",
)
parser.add_argument("-v", "--verbose", action="store_true")
parser.add_argument(
"-v", "--verbose",
action="store_true",
default=_env_flag("WAGO_SIM_VERBOSE"),
help=("trace every Modbus request/response in plain text "
"(env: WAGO_SIM_VERBOSE)"),
)
sub = parser.add_subparsers(dest="command", required=True)
serve = sub.add_parser("serve", help="run the Modbus TCP server")
serve.add_argument("--node", required=True, help="node config YAML")
serve.add_argument("--host", default="0.0.0.0")
serve.add_argument("--port", type=int, default=502)
serve.add_argument(
"--node", default=None,
help="node config YAML (or env: WAGO_SIM_NODE)",
)
serve.add_argument(
"--host", default=_env("WAGO_SIM_HOST", "0.0.0.0"),
help="bind address (or env: WAGO_SIM_HOST)",
)
serve.add_argument(
"--port", type=_port_type, default=_env_port("WAGO_SIM_PORT", 502),
help="listen port 1-65535 (or env: WAGO_SIM_PORT)",
)
serve.set_defaults(func=_serve)
runp = sub.add_parser("run", help="run a scenario headless (no server)")
@@ -116,9 +257,31 @@ def main(argv: list[str] | None = None) -> int:
args = parser.parse_args(argv)
_build_logger(args.verbose)
if inspect.iscoroutinefunction(args.func):
return asyncio.run(args.func(args))
return int(args.func(args))
# `--node` may come from the environment when omitted (service mode);
# only `serve` has an optional --node (`run` requires it in argparse)
if args.func is _serve and args.node is None:
args.node = _env("WAGO_SIM_NODE", "")
if not args.node:
parser.error("serve: --node is required (or set WAGO_SIM_NODE)")
try:
if inspect.iscoroutinefunction(args.func):
return asyncio.run(args.func(args))
return int(args.func(args))
except SystemExit:
raise
except KeyboardInterrupt:
# second Ctrl+C while already shutting down (first one is
# handled gracefully inside _serve)
print("\nwago-sim: interrupted", file=sys.stderr)
raise SystemExit(130) from None
except (ScenarioError, ModuleUnknown, ChannelMismatch,
yaml.YAMLError, OSError) as exc:
# user-input / environment problems: clean message, no traceback
_fail(str(exc))
except Exception:
# genuine internal bug: keep the traceback for bug reports
log.exception("unexpected internal error")
raise SystemExit(1) from None
if __name__ == "__main__":