# 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
```
┌──────────────────────────────────────────────────────────────┐
│ app / demo │
│ apps/secs_server.cpp apps/secs_client.cpp │
└────────────┬───────────────────────────┬─────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ secsgem::gem (E30 / E5 logic) │
│ data_model.hpp SVIDs, DVIDs, ECIDs, CEIDs, alarms, │
│ reports, links, recipes │
│ control_state.h E30 control state machine │
│ messages.hpp all SxFy builders + parsers │
└────────────┬─────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ secsgem::hsms (E37 transport) │
│ Connection async TCP, state machine, T3/T5/T6/T7/T8 │
│ Frame, Header 4-byte length prefix + 10-byte header │
│ Server, Client endpoint wrappers (in include/secsgem/) │
└────────────┬─────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ secsgem::secs2 (E5 codec) │
│ Item variant over L/A/B/BOOLEAN/I1-8/U1-8/F4/F8 │
│ encode/decode big-endian, length-byte aware │
│ Message SxFy + W-bit + optional root Item │
│ to_sml human-readable text for logs │
└──────────────────────────────────────────────────────────────┘
```
### 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
├── include/secsgem/
│ ├── secs2/{item,codec,message}.hpp
│ ├── hsms/{types,header,frame,connection}.hpp
│ ├── gem/{control_state,data_model,messages}.hpp
│ └── endpoint.hpp
├── src/{secs2,hsms,gem,endpoint.cpp}/*.cpp
├── apps/{secs_server,secs_client}.cpp
└── tests/test_*.cpp
```
## 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:
[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.