raphael
b871cd9da2
Move equipment capabilities and the E30 control state machine out of C++
code and into YAML data files; introduce a Router for SECS dispatch;
consolidate small files.
Behavioural changes: none. Demo identical (15 SxFy transactions +
3 equipment-initiated primaries), 67 test cases / 384 assertions still
all green. Structural changes only.
Why
---
The previous server.cpp held the equipment data dictionary (3 SVIDs,
2 ECIDs, 3 CEIDs, 2 alarms, 2 recipes, 4 host commands) as imperative
C++ in a 50-line `populate()` function, and routed inbound messages
through a 150-line if-ladder. Adding a new SVID required a recompile.
Adding a new state transition required editing two switch statements
(`operator_*` and `on_host_request_*`). The control state machine's
behavioural rules were spread across imperative code in two methods.
This is exactly what implementation_plan.md calls out as the wrong
shape: behavioural rules should live in versioned data, and every
runtime/test/analyzer should read from that data rather than re-encode
it. This commit starts that move.
What's new
----------
data/equipment.yaml
Equipment data dictionary. Declarative SVIDs / ECIDs / CEIDs /
alarms / recipes / host commands. Host commands carry their HCACK
ack code plus optional `emit_ceid` and `set_alarm` side-effects.
Adding a new SVID or command is a YAML edit, no recompile.
data/control_state.yaml
The E30 §6.2 control state transition table as data. Each row is
(from, on) -> (to [, then] [, ack]). `then` chains an auto-advance
through the transient AttemptOnline state. The previous
imperative switch is gone.
include/secsgem/config/loader.hpp + src/config/loader.cpp
yaml-cpp-backed loader. `load_control_state(path)` returns a
ControlTransitionTable + initial state; `load_equipment(path, model)`
populates the EquipmentDataModel and returns the device descriptor
(id, MDLN, SOFTREV, optional auto-emit CEID). Surfaces config
errors with file path + field name via ConfigError.
include/secsgem/gem/router.hpp (header-only)
Small (stream, function) -> handler map. Server registers all
handlers once at startup, then the Connection's message handler is
just `router.dispatch(msg)`. Unhandled primaries with W set get
SxF0 by default. Replaces the if-ladder in secs_server.cpp.
include/secsgem/gem/control_state.hpp + .cpp
ControlTransitionTable is the new pure data type. ControlStateMachine
is now a thin engine over the table: `fire(event)` looks up the row,
optionally transitions, optionally chains a `then` transition, returns
the ack code. Behaviour rules no longer live in C++ switches.
The default in-code table matches data/control_state.yaml row for row;
tests rely on it so they don't need the YAML file.
include/secsgem/gem/data_model.hpp + .cpp
`register_command(rcmd, CommandSpec)` replaces the function-handler
signature. CommandSpec = (HostCmdAck, optional emit_ceid, optional
set_alarm). `dispatch_command` returns a CommandResult so the server
can fire the side-effects after S2F42 is sent.
apps/secs_server.cpp
No populate(), no if-ladder. Loads equipment.yaml + control_state.yaml
at startup (clean error on bad config), wires the Router once,
delegates dispatch. Sm change handler reads emit_on_control_change
from the YAML. Welcome S10F3 removed for parity with config (a future
YAML rule could re-introduce it declaratively).
tests/test_loader.cpp (new)
Verifies the YAML loader produces the same shape as the in-code
default table, and that equipment.yaml populates every section
(SVIDs/ECIDs/CEIDs/alarms/recipes/commands). SECSGEM_DATA_DIR
CMake define points at ${CMAKE_SOURCE_DIR}/data so tests don't
depend on cwd.
CMakeLists.txt, Dockerfile
find_package(yaml-cpp) and link. libyaml-cpp-dev added to the
Ubuntu base image (yaml-cpp 0.8 ships the modern target name).
File consolidation
------------------
Five small files removed; their content lives in fewer headers:
- secs2/item.cpp -> inline in secs2/item.hpp
- secs2/message.cpp -> inline in secs2/message.hpp
- hsms/types.hpp -> merged into hsms/header.hpp
- hsms/frame.hpp -> merged into hsms/header.hpp
- hsms/frame.cpp -> merged into hsms/header.cpp
hsms/header.hpp is now "the HSMS wire format" in one place: SType + status
enums + Timers + Header + Frame + constants. All includers updated.
Net effect
----------
Before: equipment data dictionary lived in 50 lines of imperative
populate() inside secs_server.cpp; dispatch in a 20-branch if-ladder.
After: equipment data dictionary lives in 47 lines of YAML; dispatch
is a Router built once. Adding a new capability is now a YAML edit
in the common case.
Test count up to 67 cases / 384 assertions (+4 cases / +106 assertions)
covering the loader and the new table-driven SM paths.
What's NOT changed
------------------
The per-SxFy reply construction still lives in C++ (each message has a
unique body shape). Moving those into YAML/JSON message-shape
definitions is the next refactor step but requires a generic typed
encoder/decoder driven by shape descriptors; out of scope here.
Spooling, the S9 error stream, S1F19/F20, and the other gaps in
COMPLIANCE.md remain unchanged.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
187 lines
8.9 KiB
Markdown
187 lines
8.9 KiB
Markdown
# secs-gem
|
||
|
||
A C++20 SECS-II / HSMS / GEM client + server toolchain, fully containerized.
|
||
|
||
The long-term vision is the "spec-as-data" stack described in
|
||
[`implementation_plan.md`](implementation_plan.md): the SEMI E30 behavioral
|
||
spec encoded as transition tables, from which a runtime, passive analyzer,
|
||
simulator, and conformance test generator are derived. The current code is
|
||
the **Layer 0 + Layer 1 base** — a working HSMS client/server, the SECS-II
|
||
codec, the E30 control state machine, and the GEM core capabilities (status
|
||
variables, equipment constants, dynamic event reporting, alarms, remote
|
||
control, clock, process programs, terminal services).
|
||
|
||
For a per-capability E5/E30/E37 audit see [COMPLIANCE.md](COMPLIANCE.md).
|
||
|
||
## Quick start
|
||
|
||
Everything runs in Docker — no compiler or build tools on the host.
|
||
|
||
```bash
|
||
docker compose run --rm builder # configure + compile
|
||
docker compose run --rm tests # run unit tests (63 cases / 278 assertions)
|
||
docker compose up --no-deps server client # live two-container demo
|
||
```
|
||
|
||
## Architecture
|
||
|
||
The "spec-as-data" first step: equipment capabilities and the E30 control
|
||
state machine are loaded from YAML at startup; the SECS dispatch is a
|
||
`(stream, function) -> handler` Router rather than an if-ladder.
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ data/equipment.yaml data/control_state.yaml │
|
||
│ SVIDs, ECIDs, CEIDs, alarms, recipes, host commands; │
|
||
│ E30 control state transition table │
|
||
└──────────────────────┬───────────────────────────────────────┘
|
||
│ (loaded at startup)
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ app / demo │
|
||
│ apps/secs_server.cpp apps/secs_client.cpp │
|
||
│ uses gem::Router for SECS dispatch │
|
||
└────────────┬───────────────────────────┬─────────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ secsgem::config loader.hpp YAML -> tables + data model │
|
||
│ secsgem::gem control_state (table-driven), data_model, │
|
||
│ messages (SxFy builders), router │
|
||
│ secsgem::hsms Connection (Asio), Header, Frame, Timers │
|
||
│ secsgem::secs2 Item, codec (encode/decode), Message │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Tree
|
||
|
||
```
|
||
secs-gem/
|
||
├── Dockerfile, docker-compose.yml # toolchain + demo
|
||
├── CMakeLists.txt
|
||
├── implementation_plan.md # the 7-layer spec-as-data roadmap
|
||
├── COMPLIANCE.md # per-capability E5/E30/E37 audit
|
||
├── data/
|
||
│ ├── equipment.yaml # SVIDs/ECIDs/CEIDs/alarms/recipes/commands
|
||
│ └── control_state.yaml # E30 transition table
|
||
├── include/secsgem/
|
||
│ ├── secs2/{item,codec,message}.hpp
|
||
│ ├── hsms/{header,connection}.hpp # header.hpp also holds Frame + Timers
|
||
│ ├── gem/{control_state,data_model,messages,router}.hpp
|
||
│ ├── config/loader.hpp
|
||
│ └── endpoint.hpp
|
||
├── src/{secs2,hsms,gem,config}/*.cpp + endpoint.cpp
|
||
├── apps/{secs_server,secs_client}.cpp
|
||
└── tests/test_*.cpp
|
||
```
|
||
|
||
### Adding a capability without recompiling the server
|
||
|
||
```yaml
|
||
# data/equipment.yaml — append a new SVID
|
||
svids:
|
||
- {id: 4, name: ChamberTemp, units: "C", type: U4, value: 25}
|
||
```
|
||
|
||
```yaml
|
||
# data/equipment.yaml — append a new host command + side effect
|
||
host_commands:
|
||
- {name: VENT, ack: Accept, emit_ceid: 400, set_alarm: 2}
|
||
```
|
||
|
||
```yaml
|
||
# data/control_state.yaml — append a new transition
|
||
transitions:
|
||
- {from: OnlineRemote, on: host_request_offline, to: EquipmentOffline, ack: Accept}
|
||
```
|
||
|
||
Restart the server; the new behaviour is live. The C++ code unchanged.
|
||
|
||
## What's implemented
|
||
|
||
### HSMS (E37)
|
||
SELECT/DESELECT/LINKTEST/SEPARATE/REJECT control messages, the 4-byte
|
||
length-prefixed frame, the 10-byte header, the NOT-CONNECTED → SELECTED
|
||
state machine, and the T3/T5/T6/T7/T8 timers. Active (client) and passive
|
||
(server) modes. System-bytes based reply correlation.
|
||
|
||
### SECS-II (E5)
|
||
A variant-based `Item` covering every standard format (List, ASCII,
|
||
Binary, Boolean, I1–I8, U1–U8, F4, F8), big-endian numerics, 1/2/3-byte
|
||
length encoding, and an `to_sml()` rendering for readable logs.
|
||
|
||
### GEM (E30)
|
||
- **Control state machine** — 5 states (EquipmentOffline, AttemptOnline,
|
||
HostOffline, OnlineLocal, OnlineRemote), operator actions, host
|
||
requests with SEMI-mandated ACK codes, change-handler callback.
|
||
- **Status variables** — S1F3/F4, S1F11/F12.
|
||
- **Equipment constants** — S2F13/F14, S2F15/F16, S2F29/F30 + EAC enum.
|
||
- **Clock** — S2F17/F18, S2F31/F32 (16-char `YYYYMMDDhhmmsscc`).
|
||
- **Establish Comms** — S1F13/F14 + `CommAck`.
|
||
- **Online/Offline** — S1F15/F16 + `OfflineAck`, S1F17/F18 + `OnlineAck`.
|
||
- **Remote control** — S2F41/F42 + 7-value `HostCmdAck` + per-param CPACKs.
|
||
- **Dynamic event reporting** — S2F33 Define Report (DRACK), S2F35 Link
|
||
Event (LRACK), S2F37 Enable (ERACK), **S6F11 emission**, S6F12 ack.
|
||
- **Alarms** — S5F1/F2 emit + ACKC5, S5F3/F4 enable/disable, S5F5/F6
|
||
list, ALCD bit-7 set/cleared, lower-7 category.
|
||
- **Process programs** — S7F3/F4 send, S7F5/F6 request, S7F19/F20 list.
|
||
- **Terminal services** — S10F1/F2 host→equipment, S10F3/F4 equipment→host.
|
||
|
||
### Not (yet) implemented
|
||
Spooling, S9 error stream, S1F19/F20 + S1F21/F22 documentation, multi-block,
|
||
trace data collection (S2F23/F24, S6F1/F2), limits monitoring, material
|
||
movement (E40), EC range validation, S5F7/F8 list-enabled-alarms,
|
||
S6F15/F16 event-report request. See [COMPLIANCE.md](COMPLIANCE.md) for
|
||
the honest accounting.
|
||
|
||
## Demo session
|
||
|
||
The demo client walks 17 distinct steps end-to-end. From the live log
|
||
(condensed):
|
||
|
||
```
|
||
[host] -> Select.req [equip] <- Select.req
|
||
[host] <- Select.rsp (Ok) [equip] -> Select.rsp (Ok)
|
||
[host] == SELECTED == [equip] == SELECTED ==
|
||
[host] -> S1F13 W [equip] S1F13; replying S1F14 (COMMACK=0)
|
||
[host] -> S1F17 W [equip] control: HostOffline -> AttemptOnline
|
||
[equip] control: AttemptOnline -> OnlineRemote
|
||
[host] S1F18 ONLACK=0 [equip] -> S10F3 W (welcome)
|
||
[host] TERMINAL[0] Welcome from SECSGEM-SIM
|
||
[host] -> S1F11 W [equip] S1F11; replying S1F12 (status namelist)
|
||
[host] SVID 1 ControlState
|
||
[host] SVID 2 Clock
|
||
[host] SVID 3 EventsEnabled
|
||
[host] -> S1F3 W [equip] S1F3; replying S1F4 (3 values)
|
||
[host] -> S2F29 W [equip] -> S2F30 (2 EC entries)
|
||
[host] -> S2F33 W [equip] -> S2F34 (DRACK=0)
|
||
[host] -> S2F35 W [equip] -> S2F36 (LRACK=0)
|
||
[host] -> S2F37 W [equip] -> S2F38 (ERACK=0)
|
||
[host] -> S2F41 W START [equip] RCMD START; emit S6F11 CEID=300
|
||
[host] EVENT CEID=300 (1 reports)
|
||
[host] RPTID 1000: <A "OnlineRemote"> <A "2026060122162336"> <BOOLEAN T>
|
||
[host] -> S5F5 W [equip] -> S5F6 (2 alarms)
|
||
[host] -> S5F3 W [equip] -> S5F4 (ACKC5=0)
|
||
[host] -> S2F41 W FAULT [equip] RCMD FAULT triggers alarm 1
|
||
[equip] emit S5F1 alarm set ALID=1
|
||
[equip] emit S6F11 CEID=200
|
||
[host] ALARM SET ALID=1 cat=4 "Chiller Temp High"
|
||
[host] EVENT CEID=200 (1 reports)
|
||
[host] -> S7F19 W [equip] -> S7F20 (2 PPIDs)
|
||
[host] -> S7F5 W [equip] -> S7F6 RECIPE-A
|
||
[host] -> S10F1 W [equip] TERMINAL[0] Hello equipment!
|
||
[host] -> S1F15 W [equip] control: OnlineRemote -> HostOffline
|
||
[host] -> Separate.req [equip] <- Separate.req
|
||
[host] exiting
|
||
```
|
||
|
||
## Build details
|
||
|
||
The toolchain image (`Dockerfile`) is Ubuntu 24.04 with `g++-13`, CMake,
|
||
Ninja, and `libasio-dev`. doctest is fetched via CMake `FetchContent`.
|
||
Build artifacts live in a named Docker volume (`build:`) so the host
|
||
filesystem stays clean.
|
||
|
||
Standalone Asio is used in header-only mode (`ASIO_STANDALONE`). No Boost
|
||
dependency.
|