Initial commit: C++20 SECS-II / HSMS / GEM client + server

A fully containerised SECS/GEM toolchain. Single docker compose project,
no host build tools. 63 unit-test cases / 278 assertions, two demo
executables, end-to-end two-container demo exercising every implemented
capability.

Architecture (bottom-up):

  secs2/   E5 SECS-II codec
    Item        variant over L/A/B/BOOLEAN/I1-8/U1-8/F4/F8
    encode/decode  big-endian, 1/2/3-byte length encoding
    Message     SxFy + W-bit + optional root item
    to_sml      human-readable text rendering

  hsms/    E37 HSMS transport (TCP)
    Header      10-byte header + SType enum (Data/Select/Deselect/
                Linktest/Reject/Separate)
    Frame       4-byte length prefix + payload encode/decode
    Connection  async Asio TCP, NOT-SELECTED -> SELECTED state machine,
                T3/T5/T6/T7/T8 timers, system-bytes reply correlation,
                graceful close-after-flush separation

  endpoint  active Client (connect with T5 retry) and passive Server
            (accept loop) wrappers over Connection

  gem/     E30 GEM logic
    ControlStateMachine  5-state E30 control model with operator
                         actions, host requests, SEMI-mandated ack
                         codes (OnlineAck, OfflineAck, CommAck), and
                         a state-change handler
    EquipmentDataModel   in-memory dictionary: SVIDs, DVIDs, ECIDs
                         (with EAC), CEIDs, report defs, CEID->report
                         links, enabled-events set, alarm table
                         (ALCD, enabled, active), process programs,
                         host command registry, clock (16-char
                         YYYYMMDDhhmmsscc with offset)
    messages.hpp         builders + parsers for every SxFy below

GEM message coverage (full list):

  S1F1/F2    Are You There / On Line Data
  S1F3/F4    Selected Equipment Status Request / Data
  S1F11/F12  Status Variable Namelist Request / Data
  S1F13/F14  Establish Communications (+ CommAck)
  S1F15/F16  Request OFFLINE (+ OfflineAck)
  S1F17/F18  Request ONLINE (+ OnlineAck)
  S2F13/F14  Equipment Constant Request / Data
  S2F15/F16  EC Send + EquipmentAck (Accept/UnknownEcid/Busy/OutOfRange)
  S2F17/F18  Date and Time Request / Data
  S2F29/F30  Equipment Constant Namelist Request / Data
  S2F31/F32  Date and Time Set Request / TimeAck
  S2F33/F34  Define Report + DefineReportAck (5 enum values)
  S2F35/F36  Link Event Report + LinkEventAck
  S2F37/F38  Enable / Disable Event Report + EnableEventAck
  S2F41/F42  Host Command + HostCmdAck (7 values) + per-param CPACKs
  S5F1/F2    Alarm Report Send + AlarmAck (ALCD bit-7 set/cleared
             + lower-7 category)
  S5F3/F4    Enable/Disable Alarm Send + AlarmAck
  S5F5/F6    List Alarms Request / Data (active alarms tagged in ALCD)
  S6F11/F12  Event Report Send (equipment-initiated CEID emission
             with full report data) + EventReportAck
  S7F3/F4    Process Program Send + ProcessProgramAck (7 values)
  S7F5/F6    Process Program Request / Data
  S7F19/F20  Current EPPD List Request / Data
  S10F1/F2   Terminal Display Single (host->equipment) + TerminalAck
  S10F3/F4   Terminal Display Single (equipment->host)

Demo apps:

  apps/secs_server.cpp   passive equipment. Populates the data model
                         with 3 SVIDs (ControlState, Clock,
                         EventsEnabled), 2 ECIDs, 3 CEIDs
                         (ControlStateChanged, AlarmSetEvent,
                         ProcessStarted), 2 alarms (Chiller Temp High
                         cat 4, Door Open cat 1), 2 recipes
                         (RECIPE-A, RECIPE-B), and 4 host commands
                         (START, STOP, PAUSE, FAULT). Emits S6F11 on
                         every control state transition + on START;
                         emits S5F1 + the AlarmSetEvent CEID on FAULT.
                         Pushes an S10F3 welcome message when the host
                         comes online.

  apps/secs_client.cpp   active host. Walks 17 steps: Establish ->
                         Online -> S1F11 SVID namelist -> S1F3 read ->
                         S2F29 EC namelist -> S2F13 read ->
                         S2F17 clock -> S2F33/S2F35/S2F37 dynamic
                         event subscription -> S2F41 START
                         (-> receives S6F11) -> S5F5 alarm list ->
                         S5F3 enable alarm 1 -> S2F41 FAULT
                         (-> receives S5F1 + S6F11) -> S7F19/S7F5
                         recipe list + body -> S10F1 terminal ->
                         S1F15 Offline -> Separate. Handles inbound
                         S6F11, S5F1, S10F3 primaries.

Testing:

  tests/test_secs2.cpp         codec round-trip for every format,
                               byte-layout assertions for known values,
                               truncation/trailing-byte rejection,
                               nested list round-trip, SML rendering
  tests/test_hsms.cpp          header byte layout, data + control
                               header round-trip, full frame round-
                               trip with length prefix, short-payload
                               rejection
  tests/test_control_state.cpp every (state, event) pair in the E30
                               control state machine, including
                               AlreadyOnline / NotAccept rejections
                               and idempotent offline-while-offline
  tests/test_data_model.cpp    SVID/ECID/Alarm/Recipe CRUD, clock
                               format + parse, host command registry,
                               full event-report pipeline (define ->
                               link -> enable -> compose) with
                               every error path (InvalidVid,
                               UnknownCeid, UnknownRptid), alarm
                               set/clear with ALCD bit-7 semantics
  tests/test_messages.cpp      round-trip + byte-layout for every
                               builder/parser pair, including S6F11
                               event reports with mixed item types

Toolchain:

  Dockerfile          Ubuntu 24.04, g++-13, CMake, Ninja, libasio-dev
  docker-compose.yml  builder / tests / server / client services,
                      source bind-mounted, build artifacts in a
                      named volume so the host tree stays clean
  CMakeLists.txt      C++20, -Wall -Wextra -Wpedantic, standalone
                      Asio (ASIO_STANDALONE), doctest via FetchContent

Documentation:

  README.md           architecture, quick start, demo log
  COMPLIANCE.md       honest per-capability E5/E30/E37 audit with
                      spec section refs. Calls out what's implemented,
                      what's partial (Reject.req, Alarms missing F7/F8,
                      EC range validation, PP without verify, terminal
                      single-line only), and what's intentionally not
                      yet implemented (spooling, S9 error stream,
                      Documentation S1F19/F20+F21/F22, limits monitoring,
                      trace data collection, multi-block, material
                      movement). Does NOT claim "100% GEM-compliant" and
                      lists the work required to honestly make that claim.

This is Layer 0 + the start of Layer 1 from implementation_plan.md.
The transition-table-driven "spec-as-data" architecture (Layer 1
proper) is not yet implemented; the current code uses imperative
state machines that are structurally ready to be refactored onto
tables.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-06-02 00:21:10 +02:00
commit 96b02f8b50
36 changed files with 5210 additions and 0 deletions
+375
View File
@@ -0,0 +1,375 @@
// Passive SECS/GEM equipment: a small simulated tool. Drives the E30 control
// state machine, owns an in-memory data dictionary (SVIDs, DVIDs, ECIDs,
// CEIDs, alarms, recipes), answers the GEM SxFy core, and emits S6F11 +
// S5F1 primaries when host-subscribed events fire.
#include <asio.hpp>
#include <chrono>
#include <cstdint>
#include <iostream>
#include <memory>
#include <optional>
#include <string>
#include <system_error>
#include <vector>
#include "secsgem/endpoint.hpp"
#include "secsgem/gem/control_state.hpp"
#include "secsgem/gem/data_model.hpp"
#include "secsgem/gem/messages.hpp"
#include "secsgem/secs2/item.hpp"
#include "secsgem/secs2/message.hpp"
using namespace secsgem;
namespace s2 = secsgem::secs2;
namespace gem = secsgem::gem;
namespace {
std::string arg(int argc, char** argv, const std::string& key, const std::string& def) {
for (int i = 1; i + 1 < argc; ++i)
if (key == argv[i]) return argv[i + 1];
return def;
}
constexpr const char* kModelName = "SECSGEM-SIM";
constexpr const char* kSoftRev = "0.1.0";
// SVIDs
constexpr uint32_t kSvidControlState = 1;
constexpr uint32_t kSvidClock = 2;
constexpr uint32_t kSvidEventsEnabled = 3;
// ECIDs
constexpr uint32_t kEcidTimeFormat = 10;
constexpr uint32_t kEcidEstablishTimeout = 11;
// CEIDs
constexpr uint32_t kCeidControlStateChanged = 100;
constexpr uint32_t kCeidAlarmSetEvent = 200;
constexpr uint32_t kCeidProcessStarted = 300;
// ALIDs
constexpr uint32_t kAlarmChillerTempHigh = 1;
constexpr uint32_t kAlarmDoorOpen = 2;
void populate(gem::EquipmentDataModel& m, const gem::ControlStateMachine& sm) {
m.add_status_variable(
{kSvidControlState, "ControlState", "", s2::Item::ascii(gem::control_state_name(sm.state()))});
m.add_status_variable({kSvidClock, "Clock", "", s2::Item::ascii(m.current_time_string())});
m.add_status_variable({kSvidEventsEnabled, "EventsEnabled", "", s2::Item::boolean(true)});
m.add_equipment_constant({kEcidTimeFormat, "TimeFormat", "code",
s2::Item::u4(uint32_t{1}), s2::Item::u4(uint32_t{1}), "0", "1"});
m.add_equipment_constant({kEcidEstablishTimeout, "EstablishCommTimeout", "sec",
s2::Item::u4(uint32_t{10}), s2::Item::u4(uint32_t{10}), "1", "60"});
m.register_event({kCeidControlStateChanged, "ControlStateChanged"});
m.register_event({kCeidAlarmSetEvent, "AlarmSetEvent"});
m.register_event({kCeidProcessStarted, "ProcessStarted"});
m.add_alarm({kAlarmChillerTempHigh, "Chiller Temp High", 4});
m.add_alarm({kAlarmDoorOpen, "Door Open", 1});
m.add_process_program("RECIPE-A", "STEP CHAMBER ARGON 30s\nSTEP CHAMBER NITROGEN 60s\nEND");
m.add_process_program("RECIPE-B", "STEP HEATER 800C 120s\nEND");
}
void refresh_dynamic_svids(gem::EquipmentDataModel& m, const gem::ControlStateMachine& sm) {
m.set_status_value(kSvidControlState, s2::Item::ascii(gem::control_state_name(sm.state())));
m.set_status_value(kSvidClock, s2::Item::ascii(m.current_time_string()));
}
} // namespace
int main(int argc, char** argv) {
Server::Config cfg;
cfg.port = static_cast<uint16_t>(std::stoi(arg(argc, argv, "--port", "5000")));
cfg.device_id = static_cast<uint16_t>(std::stoi(arg(argc, argv, "--device", "0")));
asio::io_context io;
Server server(io, cfg);
auto logfn = [](const std::string& m) { std::cout << "[equip] " << m << std::endl; };
server.on_log(logfn);
auto sm = std::make_shared<gem::ControlStateMachine>();
auto model = std::make_shared<gem::EquipmentDataModel>();
populate(*model, *sm);
auto active_conn = std::make_shared<std::weak_ptr<Connection>>();
// Emit a CEID via S6F11 to the currently-active host connection, if any
// and if the host has subscribed to that CEID via S2F37.
auto emit_event = [&io, active_conn, model, logfn](uint32_t ceid) {
asio::post(io, [active_conn, model, logfn, ceid]() {
auto conn = active_conn->lock();
if (!conn) return;
if (!model->is_event_enabled(ceid)) {
logfn("CEID " + std::to_string(ceid) + " not enabled; suppressed");
return;
}
auto reports = model->compose_reports_for(ceid);
logfn("emit S6F11 CEID=" + std::to_string(ceid) + " (" +
std::to_string(reports.size()) + " reports)");
conn->send_request(gem::s6f11_event_report(0, ceid, reports),
[logfn, ceid](std::error_code ec, const s2::Message&) {
if (ec)
logfn("CEID " + std::to_string(ceid) + " emit failed: " + ec.message());
});
});
};
// Equipment-initiated alarm set: emits S5F1 (if alarm enabled) and the
// AlarmSetEvent CEID (if event enabled).
auto emit_alarm_set = [&io, active_conn, model, logfn, emit_event](uint32_t alid) {
asio::post(io, [active_conn, model, logfn, emit_event, alid]() {
auto conn = active_conn->lock();
if (!conn) return;
auto alarm = model->alarm(alid);
if (!alarm) return;
auto alcd = model->alarm_set(alid);
if (!alcd) return;
if (!model->alarm_enabled(alid)) {
logfn("alarm " + std::to_string(alid) + " not enabled; suppressed");
} else {
logfn("emit S5F1 alarm set ALID=" + std::to_string(alid));
conn->send_request(gem::s5f1_alarm_report(*alcd, alid, alarm->text),
[](std::error_code, const s2::Message&) {});
}
emit_event(kCeidAlarmSetEvent);
});
};
sm->set_state_change_handler(
[logfn, emit_event](gem::ControlState from, gem::ControlState to, gem::ControlEvent ev) {
logfn(std::string("control: ") + gem::control_state_name(from) + " -> " +
gem::control_state_name(to) + " (" + gem::control_event_name(ev) + ")");
emit_event(kCeidControlStateChanged);
});
server.on_connection([sm, model, logfn, active_conn, emit_event,
emit_alarm_set](std::shared_ptr<Connection> conn) {
*active_conn = conn;
conn->set_closed_handler([active_conn, logfn](const std::string&) {
active_conn->reset();
});
conn->set_selected_handler([logfn, sm]() {
logfn(std::string("host is online; control=") + gem::control_state_name(sm->state()));
});
// Host commands are registered here so they can capture emit_event /
// emit_alarm_set without static globals.
model->register_command("START", [logfn, emit_event](const auto& params) {
logfn("RCMD START (" + std::to_string(params.size()) + " params)");
emit_event(kCeidProcessStarted);
return gem::HostCmdAck::Accept;
});
model->register_command("STOP",
[](const auto&) { return gem::HostCmdAck::Accept; });
model->register_command("PAUSE",
[](const auto&) { return gem::HostCmdAck::CannotDoNow; });
model->register_command("FAULT", [logfn, emit_alarm_set](const auto&) {
logfn("RCMD FAULT triggers alarm 1");
emit_alarm_set(kAlarmChillerTempHigh);
return gem::HostCmdAck::Accept;
});
conn->set_message_handler([sm, model, logfn](const s2::Message& msg)
-> std::optional<s2::Message> {
const uint8_t s = msg.stream, f = msg.function;
// ---- S1: equipment status ----------------------------------------
if (s == 1 && f == 1) {
logfn("S1F1; replying S1F2");
return gem::s1f2_on_line_data(kModelName, kSoftRev);
}
if (s == 1 && f == 3) {
refresh_dynamic_svids(*model, *sm);
auto svids = gem::parse_s1f3(msg);
if (!svids) return s2::Message(1, 0, false);
std::vector<std::optional<s2::Item>> values;
if (svids->empty()) {
for (const auto& sv : model->all_status_variables()) values.push_back(sv.value);
} else {
for (auto id : *svids) {
auto sv = model->status_variable(id);
values.push_back(sv ? std::optional<s2::Item>(sv->value) : std::nullopt);
}
}
logfn("S1F3; replying S1F4 (" + std::to_string(values.size()) + " values)");
return gem::s1f4_selected_status_data(values);
}
if (s == 1 && f == 11) {
logfn("S1F11; replying S1F12 (status namelist)");
return gem::s1f12_status_namelist_data(model->all_status_variables());
}
if (s == 1 && f == 13) {
logfn("S1F13; replying S1F14 (COMMACK=0)");
return gem::s1f14_establish_comms_ack(gem::CommAck::Accept, kModelName, kSoftRev);
}
if (s == 1 && f == 15) {
auto ack = sm->on_host_request_offline();
logfn(std::string("S1F15; replying S1F16 (OFLACK=") +
std::to_string(static_cast<int>(ack)) + ")");
return gem::s1f16_offline_ack(ack);
}
if (s == 1 && f == 17) {
auto ack = sm->on_host_request_online();
logfn(std::string("S1F17; replying S1F18 (ONLACK=") +
std::to_string(static_cast<int>(ack)) + ")");
return gem::s1f18_online_ack(ack);
}
// ---- S2: equipment control + reports -----------------------------
if (s == 2 && f == 13) {
auto ids = gem::parse_u4_list_body(msg);
if (!ids) return s2::Message(2, 0, false);
std::vector<s2::Item> values;
for (auto id : *ids) {
auto ec = model->equipment_constant(id);
values.push_back(ec ? ec->value : s2::Item::list({}));
}
logfn("S2F13; replying S2F14 (" + std::to_string(values.size()) + " values)");
return gem::s2f14_ec_data(values);
}
if (s == 2 && f == 15) {
auto sets = gem::parse_s2f15(msg);
if (!sets) return gem::s2f16_ec_ack(gem::EquipmentAck::Denied_OutOfRange);
auto eac = gem::EquipmentAck::Accept;
for (const auto& [id, val] : *sets) {
auto r = model->set_equipment_constant_value(id, val);
if (r != gem::EquipmentAck::Accept) eac = r;
}
logfn(std::string("S2F15; replying S2F16 (EAC=") +
std::to_string(static_cast<int>(eac)) + ")");
return gem::s2f16_ec_ack(eac);
}
if (s == 2 && f == 17) {
logfn("S2F17; replying S2F18 (clock)");
return gem::s2f18_date_time_data(model->current_time_string());
}
if (s == 2 && f == 29) {
auto ids = gem::parse_u4_list_body(msg);
std::vector<gem::EquipmentConstant> ecs;
if (ids && ids->empty()) {
ecs = model->all_equipment_constants();
} else if (ids) {
for (auto id : *ids) {
auto ec = model->equipment_constant(id);
if (ec) ecs.push_back(*ec);
}
}
logfn("S2F29; replying S2F30 (" + std::to_string(ecs.size()) + " EC entries)");
return gem::s2f30_ec_namelist_data(ecs);
}
if (s == 2 && f == 31) {
auto t = gem::parse_s2f31(msg);
auto ack = t ? model->set_time_string(*t) : gem::TimeAck::Error;
logfn(std::string("S2F31; replying S2F32 (TIACK=") +
std::to_string(static_cast<int>(ack)) + ")");
return gem::s2f32_date_time_ack(ack);
}
if (s == 2 && f == 33) {
auto req = gem::parse_s2f33(msg);
auto ack = req ? model->define_reports(req->reports)
: gem::DefineReportAck::InvalidFormat;
logfn(std::string("S2F33; replying S2F34 (DRACK=") +
std::to_string(static_cast<int>(ack)) + ")");
return gem::s2f34_define_report_ack(ack);
}
if (s == 2 && f == 35) {
auto req = gem::parse_s2f35(msg);
auto ack = req ? model->link_event_reports(req->links) : gem::LinkEventAck::InvalidFormat;
logfn(std::string("S2F35; replying S2F36 (LRACK=") +
std::to_string(static_cast<int>(ack)) + ")");
return gem::s2f36_link_event_report_ack(ack);
}
if (s == 2 && f == 37) {
auto req = gem::parse_s2f37(msg);
auto ack = req ? model->enable_events(req->enable, req->ceids)
: gem::EnableEventAck::UnknownCeid;
logfn(std::string("S2F37 ") + (req && req->enable ? "enable" : "disable") +
"; replying S2F38 (ERACK=" + std::to_string(static_cast<int>(ack)) + ")");
return gem::s2f38_enable_event_ack(ack);
}
if (s == 2 && f == 41) {
auto cmd = gem::parse_s2f41(msg);
if (!cmd) return gem::s2f42_host_command_ack(gem::HostCmdAck::ParameterInvalid);
auto ack = model->dispatch_command(cmd->rcmd, cmd->params);
logfn("S2F41 RCMD=" + cmd->rcmd + "; replying S2F42 (HCACK=" +
std::to_string(static_cast<int>(ack)) + ")");
return gem::s2f42_host_command_ack(ack);
}
// ---- S5: alarms --------------------------------------------------
if (s == 5 && f == 3) {
auto req = gem::parse_s5f3(msg);
auto ack = req ? model->set_alarm_enabled(req->alid, req->enable)
: gem::AlarmAck::Error;
logfn(std::string("S5F3 ALID=") + (req ? std::to_string(req->alid) : "?") +
(req && req->enable ? " enable" : " disable") +
"; replying S5F4 (ACKC5=" + std::to_string(static_cast<int>(ack)) + ")");
return gem::s5f4_enable_alarm_ack(ack);
}
if (s == 5 && f == 5) {
auto ids = gem::parse_u4_list_body(msg);
std::vector<gem::Alarm> alarms;
if (ids && ids->empty()) {
alarms = model->all_alarms();
} else if (ids) {
for (auto id : *ids) {
auto a = model->alarm(id);
if (a) alarms.push_back(*a);
}
}
logfn("S5F5; replying S5F6 (" + std::to_string(alarms.size()) + " alarms)");
return gem::s5f6_list_alarms_data(alarms, [model](uint32_t id) {
return model->alarm_active(id);
});
}
// ---- S7: process programs ----------------------------------------
if (s == 7 && f == 3) {
auto pp = gem::parse_s7f3(msg);
if (!pp) return gem::s7f4_process_program_ack(gem::ProcessProgramAck::LengthError);
model->add_process_program(pp->ppid, pp->ppbody);
logfn("S7F3 PPID=" + pp->ppid + " (" + std::to_string(pp->ppbody.size()) +
" bytes); replying S7F4 (ACKC7=0)");
return gem::s7f4_process_program_ack(gem::ProcessProgramAck::Accept);
}
if (s == 7 && f == 5) {
auto ppid = gem::parse_s7f5(msg);
if (!ppid) return gem::s7f6_process_program_data("", "");
auto body = model->process_program(*ppid);
logfn("S7F5 PPID=" + *ppid + (body ? "; replying S7F6" : "; PPID not found"));
return gem::s7f6_process_program_data(*ppid, body ? *body : "");
}
if (s == 7 && f == 19) {
auto list = model->process_program_list();
logfn("S7F19; replying S7F20 (" + std::to_string(list.size()) + " PPIDs)");
return gem::s7f20_current_eppd_data(list);
}
// ---- S10: terminal services --------------------------------------
if (s == 10 && f == 1) {
auto td = gem::parse_terminal_display(msg);
if (td) logfn("TERMINAL[" + std::to_string(td->tid) + "] " + td->text);
return gem::s10f2_terminal_display_ack(gem::TerminalAck::Accepted);
}
// Unhandled primaries expecting a reply get SxF0 (abort).
if (msg.reply_expected) {
logfn("unhandled " + msg.sml() + "; replying S" + std::to_string(s) + "F0");
return s2::Message(s, 0, false);
}
return std::nullopt;
});
});
server.start();
io.run();
return 0;
}