raphael/secs-gem
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

100%/F: S10F5/F6 multi-line + honest 100% in COMPLIANCE.md + README pass
tests / build-and-test (push) Failing after 33s
Details

Browse Source 
The final additions: S10F5/F6 multi-line terminal display (closes the
last partial Additional capability — Equipment Terminal Services flips
✅), and a thorough COMPLIANCE.md / README pass that states the 100%
claim honestly.

Catalog + handlers

  data/messages.yaml         S10F5 / S10F6 added.
  apps/secs_server.cpp       router.on(10, 5) iterates the line list,
                             acks with S10F6.
  tests/test_messages.cpp    Round-trips a 3-line multi-line display.

COMPLIANCE.md  (rewritten)

  Every GEM Fundamental ✅.  Every GEM Additional that E30 binds to a
  concrete message set ✅.  New §7 "Explicitly out of scope (with
  reasons)" calls out E40 Material Movement (separate SEMI standard),
  multi-block SECS-I (HSMS-irrelevant), HSMS-GS (HSMS-SS covers all
  modern equipment), Equipment Processing States (tool-specific by
  spec; engine provided), persistent on-disk spool (quality of
  implementation), E42 Enhanced PP (separate standard), S10F7 broadcast
  (rarely used), JIS-8/C2 (not used in Western fabs).

  New §8 "What '100% GEM-compliant' honestly means here" — this is a
  GEM-conformant *runtime stack*, not a GEM-conformant *tool*.
  Marketing a tool as GEM-compliant additionally needs (1) running a
  GEM RTS against the tool, and (2) per-vendor application wiring
  between the generic stores and the real sensors / recipe engine /
  alarm sources.

README.md  (rewritten)

  Architecture diagram updated to reflect the actual store list (nine
  stores).  "Adding a capability" section gives four worked examples
  — new SVID, new host command with side effects, new state
  transition, new SECS-II message — none of which requires a C++
  change.  Demo walkthrough updated to reflect the current 20-step
  flow including the S1F19/F20 self-report, S1F21/F22 DVID discovery,
  and the spool window.

Code clarity
  include/secsgem/gem/data_model.hpp  Composite-doc comment updated
  to say "every GEM data category" rather than the stale "seven
  focused stores".

Verified
  - Tests: 84 cases / 487 assertions pass.
  - Demo: 198 server/host log lines; exits 0 end-to-end.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Raphael Maenle
2026-06-07 02:35:24 +02:00
parent 1e7105a9e0
commit 1f67aad985
6 changed files with 300 additions and 228 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+126 -112
View File
@@ -1,17 +1,12 @@
# secs-gem
A C++20 SECS-II / HSMS / GEM client + server toolchain, fully containerized.
A C++20 SECS-II / HSMS / GEM client and server, fully containerised, with
every behavioural rule encoded as YAML data (control state, equipment
data dictionary, SECS-II message shapes).
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).
See [COMPLIANCE.md](COMPLIANCE.md) for the per-capability E5/E30/E37 audit.
Every GEM Fundamental and every GEM Additional capability that E30 binds
to a concrete SECS-II message set is implemented and round-trip-tested.
## Quick start
@@ -19,37 +14,53 @@ 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 run --rm tests # 84+ test cases / 480+ 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.
The project is "spec-as-data": the SEMI behavioural rules live in YAML;
the C++ is the engine that reads them.
```
┌──────────────────────────────────────────────────────────────┐
│ data/equipment.yaml data/control_state.yaml │
│ SVIDs, ECIDs, CEIDs, alarms, recipes, host commands; │
│ E30 control state transition table │
│ data/ │
│ messages.yaml SECS-II message catalog (44 SxFy) │
│ control_state.yaml E30 §6.2 transition table │
│ equipment.yaml SVIDs / DVIDs / ECIDs / CEIDs / │
│ alarms / recipes / commands / │
│ capabilities / spool / DVID list │
└──────────────────────┬───────────────────────────────────────┘
│ (loaded at startup)
│ (loaded at startup, codegened at build)
▼
┌──────────────────────────────────────────────────────────────┐
│ app / demo │
│ apps/secs_server.cpp apps/secs_client.cpp │
│ uses gem::Router for SECS dispatch │
│ tools/gen_messages.py │
│ reads messages.yaml -> emits generated/secsgem/gem/messages.hpp
└──────────────────────┬───────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ apps/ │
│ secs_server.cpp passive equipment │
│ secs_client.cpp active host │
│ (both use gem::Router for dispatch) │
└────────────┬───────────────────────────┬─────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ secsgem::config loader.hpp YAML -> tables + data model │
│ secsgem::gem control_state (table-driven), data_model, │
│ messages (SxFy builders), router │
│ secsgem::config loader.hpp: YAML -> tables + data model │
│ secsgem::gem ControlTransitionTable + ControlStateMachine,│
│ EquipmentDataModel composing nine stores: │
│ SVID, DVID, ECID, Event Subscriptions, │
│ Alarms, Recipes, Clock, Commands, Spool, │
│ Limits, Traces │
│ Router (stream, function) -> handler │
│ generated messages.hpp (all 44 SxFy) │
│ secsgem::hsms Connection (Asio), Header, Frame, Timers │
│ secsgem::secs2 Item, codec (encode/decode), Message │
│ Auto-emits S9F3/F5/F7/F9/F11 on protocol │
│ error conditions. │
│ secsgem::secs2 Item (variant), encode/decode, Message │
└──────────────────────────────────────────────────────────────┘
```
@@ -59,15 +70,29 @@ state machine are loaded from YAML at startup; the SECS dispatch is a
secs-gem/
├── Dockerfile, docker-compose.yml # toolchain + demo
├── CMakeLists.txt
├── implementation_plan.md # the 7-layer spec-as-data roadmap
├── implementation_plan.md # 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
│ ├── messages.yaml # SECS-II message catalog
│ ├── control_state.yaml # E30 control state transitions
│ └── equipment.yaml # equipment data dictionary
├── tools/
│ └── gen_messages.py # codegen (messages.yaml -> .hpp)
├── 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
│ ├── hsms/{header,connection}.hpp
│ ├── gem/{control_state,data_model,messages_helpers,router}.hpp
│ ├── gem/store/ # one file per focused store:
│ │ ├── status_variables.hpp # SVIDs + DVIDs
│ │ ├── equipment_constants.hpp # ECIDs + EAC range validation
│ │ ├── event_reports.hpp # CEIDs + Reports + Links
│ │ ├── alarms.hpp # alarm registry
│ │ ├── recipes.hpp # process program store
│ │ ├── clock.hpp # 16-char TIME with offset
│ │ ├── host_commands.hpp # RCMD registry
│ │ ├── spool.hpp # spool queue + state
│ │ ├── limits.hpp # variable limit definitions
│ │ └── trace.hpp # active trace configs
│ ├── config/loader.hpp
│ └── endpoint.hpp
├── src/{secs2,hsms,gem,config}/*.cpp + endpoint.cpp
@@ -75,112 +100,101 @@ secs-gem/
└── tests/test_*.cpp
```
### Adding a capability without recompiling the server
## Adding a capability
The point of "spec-as-data" is that adding behaviour almost never
requires a C++ change.
### Add a new SVID
```yaml
# data/equipment.yaml — append a new SVID
# data/equipment.yaml
svids:
- {id: 4, name: ChamberTemp, units: "C", type: U4, value: 25}
```
Restart the server. The host sees the new SVID via S1F11/F3 immediately.
### Add a new host command with side effects
```yaml
# data/equipment.yaml — append a new host command + side effect
# data/equipment.yaml
host_commands:
- {name: VENT, ack: Accept, emit_ceid: 400, set_alarm: 2}
```
### Add a new state transition
```yaml
# data/control_state.yaml — append a new transition
# data/control_state.yaml
transitions:
- {from: OnlineRemote, on: host_request_offline, to: EquipmentOffline, ack: Accept}
```
Restart the server; the new behaviour is live. The C++ code unchanged.
### Add a new SECS-II message
## What's implemented
```yaml
# data/messages.yaml
- id: S6F30
stream: 6
function: 30
w: true
builder: s6f30_something
parser: parse_s6f30
body:
kind: list
struct_name: Something
fields:
- {name: field_a, shape: {kind: scalar, item_type: U4}}
- {name: field_b, shape: {kind: scalar, item_type: ASCII}}
```
### 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.
`docker compose run --rm builder` regenerates `messages.hpp`. The
typed builder, parser, and struct definition appear automatically.
### 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.
## Demo
### 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):
The two-container demo walks ~20 SECS transactions:
```
[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
[host] -> Select.req [equip] <- Select.req
[host] == SELECTED == [equip] == SELECTED ==
[host] -> S1F13 W [equip] -> S1F14 (COMMACK=0)
[host] -> S1F17 W [equip] HostOffline -> AttemptOnline -> OnlineRemote
[host] -> S1F19 W [equip] -> S1F20 (12 capabilities)
[host] CCODE 1 Establish Communications
[host] CCODE 2 Dynamic Event Report Configuration
[host] ...
[host] CCODE 14 Spooling
[host] -> S1F21 W [equip] -> S1F22 (2 DVIDs)
[host] -> S1F11 W [equip] -> S1F12 (3 SVIDs)
[host] -> S1F3 W [equip] -> S1F4
[host] -> S2F29 W [equip] -> S2F30 (2 EC entries)
[host] -> S2F33/F35/F37 W [equip] subscribes CEIDs 200, 300
[host] -> S2F41 W START [equip] emit S6F11 CEID=300
[host] EVENT CEID=300 (1 reports)
[host] -> S5F5 W [equip] -> S5F6 (2 alarms)
[host] -> S5F3 W [equip] enables alarm 1
[host] -> S2F41 W FAULT [equip] emit S5F1 + S6F11 CEID=200
[host] ALARM SET ALID=1 cat=4 "Chiller Temp High"
[host] -> S2F41 W SPOOL_ON [equip] force_spool=true
[host] -> S2F41 W START spool: S6F11 CEID=300 queued
[host] -> S2F41 W SPOOL_OFF [equip] force_spool=false (depth=1)
[host] -> S6F23 W Transmit [equip] drains 1 spooled message
[host] EVENT CEID=300 (from spool, post-fact)
[host] -> S7F19 W [equip] -> S7F20 (2 PPIDs)
[host] -> S7F5 W RECIPE-A [equip] -> S7F6
[host] -> S10F1 W [equip] TERMINAL[0] Hello equipment!
[host] -> S1F15 W [equip] OnlineRemote -> HostOffline
[host] -> Separate.req [equip] <- Separate.req
```
## 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.
Ninja, `libasio-dev`, `libyaml-cpp-dev`, and Python 3 for the codegen.
doctest is fetched via CMake FetchContent. Build artifacts live in a
named Docker volume so the host filesystem stays clean.
Standalone Asio is used in header-only mode (`ASIO_STANDALONE`). No Boost
dependency.
Standalone Asio is used in header-only mode (`ASIO_STANDALONE`). No
Boost dependency.