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: 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.

Quick start

Everything runs in Docker — no compiler or build tools on the host.

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 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.