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
+126
View File
@@ -0,0 +1,126 @@
#include "secsgem/gem/control_state.hpp"
namespace secsgem::gem {
const char* control_state_name(ControlState s) {
switch (s) {
case ControlState::EquipmentOffline: return "EquipmentOffline";
case ControlState::AttemptOnline: return "AttemptOnline";
case ControlState::HostOffline: return "HostOffline";
case ControlState::OnlineLocal: return "OnlineLocal";
case ControlState::OnlineRemote: return "OnlineRemote";
}
return "?";
}
bool is_online(ControlState s) {
return s == ControlState::OnlineLocal || s == ControlState::OnlineRemote;
}
const char* control_event_name(ControlEvent e) {
switch (e) {
case ControlEvent::OperatorSwitchOnline: return "OperatorSwitchOnline";
case ControlEvent::OperatorSwitchOffline: return "OperatorSwitchOffline";
case ControlEvent::OperatorSwitchLocal: return "OperatorSwitchLocal";
case ControlEvent::OperatorSwitchRemote: return "OperatorSwitchRemote";
case ControlEvent::AttemptComplete: return "AttemptComplete";
case ControlEvent::AttemptFailed: return "AttemptFailed";
case ControlEvent::HostRequestOnline: return "HostRequestOnline";
case ControlEvent::HostRequestOffline: return "HostRequestOffline";
}
return "?";
}
ControlStateMachine::ControlStateMachine() : ControlStateMachine(Config{}) {}
ControlStateMachine::ControlStateMachine(Config cfg)
: cfg_(cfg), state_(cfg.initial) {}
void ControlStateMachine::transition(ControlState next, ControlEvent trigger) {
if (state_ == next) return;
const ControlState prev = state_;
state_ = next;
if (on_change_) on_change_(prev, next, trigger);
}
bool ControlStateMachine::operator_online() {
switch (state_) {
case ControlState::EquipmentOffline:
case ControlState::HostOffline:
transition(ControlState::AttemptOnline, ControlEvent::OperatorSwitchOnline);
transition(cfg_.operator_default_remote ? ControlState::OnlineRemote
: ControlState::OnlineLocal,
ControlEvent::AttemptComplete);
return true;
case ControlState::AttemptOnline:
case ControlState::OnlineLocal:
case ControlState::OnlineRemote:
return false;
}
return false;
}
bool ControlStateMachine::operator_offline() {
switch (state_) {
case ControlState::OnlineLocal:
case ControlState::OnlineRemote:
case ControlState::AttemptOnline:
transition(ControlState::HostOffline, ControlEvent::OperatorSwitchOffline);
return true;
case ControlState::EquipmentOffline:
case ControlState::HostOffline:
return false;
}
return false;
}
bool ControlStateMachine::operator_local() {
if (state_ == ControlState::OnlineRemote) {
transition(ControlState::OnlineLocal, ControlEvent::OperatorSwitchLocal);
return true;
}
return false;
}
bool ControlStateMachine::operator_remote() {
if (state_ == ControlState::OnlineLocal) {
transition(ControlState::OnlineRemote, ControlEvent::OperatorSwitchRemote);
return true;
}
return false;
}
OnlineAck ControlStateMachine::on_host_request_online() {
switch (state_) {
case ControlState::HostOffline:
transition(ControlState::AttemptOnline, ControlEvent::HostRequestOnline);
transition(cfg_.host_request_grants_remote ? ControlState::OnlineRemote
: ControlState::OnlineLocal,
ControlEvent::AttemptComplete);
return OnlineAck::Accept;
case ControlState::OnlineLocal:
case ControlState::OnlineRemote:
return OnlineAck::AlreadyOnline;
case ControlState::EquipmentOffline:
case ControlState::AttemptOnline:
return OnlineAck::NotAccept;
}
return OnlineAck::NotAccept;
}
OfflineAck ControlStateMachine::on_host_request_offline() {
switch (state_) {
case ControlState::OnlineLocal:
case ControlState::OnlineRemote:
transition(ControlState::HostOffline, ControlEvent::HostRequestOffline);
return OfflineAck::Accept;
case ControlState::EquipmentOffline:
case ControlState::AttemptOnline:
case ControlState::HostOffline:
// Idempotent: already offline from host's point of view.
return OfflineAck::Accept;
}
return OfflineAck::Accept;
}
} // namespace secsgem::gem
+339
View File
@@ -0,0 +1,339 @@
#include "secsgem/gem/data_model.hpp"
#include <array>
#include <chrono>
#include <cstdio>
#include <ctime>
namespace secsgem::gem {
// ---- SVIDs ---------------------------------------------------------------
void EquipmentDataModel::add_status_variable(StatusVariable sv) {
const uint32_t id = sv.id;
svids_.insert_or_assign(id, std::move(sv));
}
std::optional<StatusVariable> EquipmentDataModel::status_variable(uint32_t id) const {
auto it = svids_.find(id);
if (it == svids_.end()) return std::nullopt;
return it->second;
}
std::vector<StatusVariable> EquipmentDataModel::all_status_variables() const {
std::vector<StatusVariable> out;
out.reserve(svids_.size());
for (const auto& [_, sv] : svids_) out.push_back(sv);
return out;
}
void EquipmentDataModel::set_status_value(uint32_t id, s2::Item value) {
auto it = svids_.find(id);
if (it != svids_.end()) it->second.value = std::move(value);
}
// ---- DVIDs ---------------------------------------------------------------
void EquipmentDataModel::add_data_variable(DataVariable dv) {
const uint32_t id = dv.id;
dvids_.insert_or_assign(id, std::move(dv));
}
std::optional<DataVariable> EquipmentDataModel::data_variable(uint32_t id) const {
auto it = dvids_.find(id);
if (it == dvids_.end()) return std::nullopt;
return it->second;
}
std::vector<DataVariable> EquipmentDataModel::all_data_variables() const {
std::vector<DataVariable> out;
out.reserve(dvids_.size());
for (const auto& [_, dv] : dvids_) out.push_back(dv);
return out;
}
void EquipmentDataModel::set_data_value(uint32_t id, s2::Item value) {
auto it = dvids_.find(id);
if (it != dvids_.end()) it->second.value = std::move(value);
}
std::optional<s2::Item> EquipmentDataModel::vid_value(uint32_t vid) const {
if (auto it = svids_.find(vid); it != svids_.end()) return it->second.value;
if (auto it = dvids_.find(vid); it != dvids_.end()) return it->second.value;
return std::nullopt;
}
bool EquipmentDataModel::vid_exists(uint32_t vid) const {
return svids_.count(vid) || dvids_.count(vid);
}
// ---- ECIDs ---------------------------------------------------------------
void EquipmentDataModel::add_equipment_constant(EquipmentConstant ec) {
const uint32_t id = ec.id;
ecids_.insert_or_assign(id, std::move(ec));
}
std::optional<EquipmentConstant> EquipmentDataModel::equipment_constant(uint32_t id) const {
auto it = ecids_.find(id);
if (it == ecids_.end()) return std::nullopt;
return it->second;
}
std::vector<EquipmentConstant> EquipmentDataModel::all_equipment_constants() const {
std::vector<EquipmentConstant> out;
out.reserve(ecids_.size());
for (const auto& [_, ec] : ecids_) out.push_back(ec);
return out;
}
EquipmentAck EquipmentDataModel::set_equipment_constant_value(uint32_t id, s2::Item value) {
auto it = ecids_.find(id);
if (it == ecids_.end()) return EquipmentAck::Denied_UnknownEcid;
it->second.value = std::move(value);
return EquipmentAck::Accept;
}
// ---- Clock ---------------------------------------------------------------
std::string EquipmentDataModel::current_time_string() const {
using namespace std::chrono;
const auto now = system_clock::now() + seconds(time_offset_seconds_);
const auto t = system_clock::to_time_t(now);
const auto ms = duration_cast<milliseconds>(now.time_since_epoch()) % 1000;
std::tm tm{};
gmtime_r(&t, &tm);
std::array<char, 64> buf{};
std::snprintf(buf.data(), buf.size(), "%04d%02d%02d%02d%02d%02d%02d",
tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday,
tm.tm_hour, tm.tm_min, tm.tm_sec,
static_cast<int>(ms.count() / 10));
return std::string(buf.data());
}
namespace {
bool parse_uint(const char* p, std::size_t n, int& out) {
int v = 0;
for (std::size_t i = 0; i < n; ++i) {
if (p[i] < '0' || p[i] > '9') return false;
v = v * 10 + (p[i] - '0');
}
out = v;
return true;
}
} // namespace
TimeAck EquipmentDataModel::set_time_string(const std::string& s) {
if (s.size() != 14 && s.size() != 16) return TimeAck::Error;
int y, mo, d, h, mi, se;
if (!parse_uint(s.data() + 0, 4, y) ||
!parse_uint(s.data() + 4, 2, mo) ||
!parse_uint(s.data() + 6, 2, d) ||
!parse_uint(s.data() + 8, 2, h) ||
!parse_uint(s.data() + 10, 2, mi) ||
!parse_uint(s.data() + 12, 2, se)) {
return TimeAck::Error;
}
std::tm tm{};
tm.tm_year = y - 1900;
tm.tm_mon = mo - 1;
tm.tm_mday = d;
tm.tm_hour = h;
tm.tm_min = mi;
tm.tm_sec = se;
const std::time_t target = timegm(&tm);
if (target == static_cast<std::time_t>(-1)) return TimeAck::Error;
const std::time_t now = std::time(nullptr);
time_offset_seconds_ = static_cast<std::int64_t>(target - now);
return TimeAck::Accept;
}
// ---- Host commands -------------------------------------------------------
void EquipmentDataModel::register_command(const std::string& rcmd, HostCommandHandler handler) {
commands_.insert_or_assign(rcmd, std::move(handler));
}
bool EquipmentDataModel::has_command(const std::string& rcmd) const {
return commands_.find(rcmd) != commands_.end();
}
HostCmdAck EquipmentDataModel::dispatch_command(
const std::string& rcmd, const std::vector<CommandParam>& params) const {
auto it = commands_.find(rcmd);
if (it == commands_.end()) return HostCmdAck::InvalidCommand;
return it->second(params);
}
// ---- Collection events ---------------------------------------------------
void EquipmentDataModel::register_event(CollectionEvent ce) {
const uint32_t id = ce.id;
ceids_.insert_or_assign(id, std::move(ce));
}
bool EquipmentDataModel::has_event(uint32_t ceid) const { return ceids_.count(ceid); }
std::vector<CollectionEvent> EquipmentDataModel::all_events() const {
std::vector<CollectionEvent> out;
out.reserve(ceids_.size());
for (const auto& [_, e] : ceids_) out.push_back(e);
return out;
}
DefineReportAck EquipmentDataModel::define_reports(
const std::vector<std::pair<uint32_t, std::vector<uint32_t>>>& reports) {
// Empty outer list deletes all reports (and links).
if (reports.empty()) {
reports_.clear();
ce_links_.clear();
return DefineReportAck::Accept;
}
// Validate first; commit only on full success.
for (const auto& [rptid, vids] : reports) {
if (vids.empty()) continue; // delete-report row is always valid
for (auto v : vids)
if (!vid_exists(v)) return DefineReportAck::InvalidVid;
}
for (const auto& [rptid, vids] : reports) {
if (vids.empty()) {
reports_.erase(rptid);
// Drop the RPTID from any links.
for (auto& [ceid, rpts] : ce_links_) {
rpts.erase(std::remove(rpts.begin(), rpts.end(), rptid), rpts.end());
}
} else {
reports_.insert_or_assign(rptid, Report{rptid, vids});
}
}
return DefineReportAck::Accept;
}
LinkEventAck EquipmentDataModel::link_event_reports(
const std::vector<std::pair<uint32_t, std::vector<uint32_t>>>& links) {
if (links.empty()) {
ce_links_.clear();
return LinkEventAck::Accept;
}
for (const auto& [ceid, rpts] : links) {
if (!has_event(ceid)) return LinkEventAck::UnknownCeid;
for (auto r : rpts)
if (!reports_.count(r)) return LinkEventAck::UnknownRptid;
}
for (const auto& [ceid, rpts] : links) {
if (rpts.empty()) {
ce_links_.erase(ceid);
} else {
ce_links_[ceid] = rpts;
}
}
return LinkEventAck::Accept;
}
EnableEventAck EquipmentDataModel::enable_events(bool enable,
const std::vector<uint32_t>& ceids) {
if (ceids.empty()) {
if (enable) {
for (const auto& [id, _] : ceids_) events_enabled_.insert(id);
} else {
events_enabled_.clear();
}
return EnableEventAck::Accept;
}
for (auto id : ceids)
if (!has_event(id)) return EnableEventAck::UnknownCeid;
for (auto id : ceids) {
if (enable) events_enabled_.insert(id);
else events_enabled_.erase(id);
}
return EnableEventAck::Accept;
}
bool EquipmentDataModel::is_event_enabled(uint32_t ceid) const {
return events_enabled_.count(ceid) > 0;
}
std::vector<ReportData> EquipmentDataModel::compose_reports_for(uint32_t ceid) const {
std::vector<ReportData> out;
auto it = ce_links_.find(ceid);
if (it == ce_links_.end()) return out;
for (auto rptid : it->second) {
auto rit = reports_.find(rptid);
if (rit == reports_.end()) continue;
ReportData rd{rptid, {}};
for (auto vid : rit->second.vids) {
auto v = vid_value(vid);
rd.values.push_back(v ? *v : s2::Item::list({}));
}
out.push_back(std::move(rd));
}
return out;
}
std::vector<Report> EquipmentDataModel::all_reports() const {
std::vector<Report> out;
out.reserve(reports_.size());
for (const auto& [_, r] : reports_) out.push_back(r);
return out;
}
// ---- Alarms --------------------------------------------------------------
void EquipmentDataModel::add_alarm(Alarm a) {
const uint32_t id = a.id;
alarms_.insert_or_assign(id, std::move(a));
}
std::optional<Alarm> EquipmentDataModel::alarm(uint32_t alid) const {
auto it = alarms_.find(alid);
if (it == alarms_.end()) return std::nullopt;
return it->second;
}
std::vector<Alarm> EquipmentDataModel::all_alarms() const {
std::vector<Alarm> out;
out.reserve(alarms_.size());
for (const auto& [_, a] : alarms_) out.push_back(a);
return out;
}
AlarmAck EquipmentDataModel::set_alarm_enabled(uint32_t alid, bool enable) {
if (!alarms_.count(alid)) return AlarmAck::Error;
if (enable) alarms_enabled_.insert(alid);
else alarms_enabled_.erase(alid);
return AlarmAck::Accept;
}
bool EquipmentDataModel::alarm_enabled(uint32_t alid) const {
return alarms_enabled_.count(alid) > 0;
}
std::optional<uint8_t> EquipmentDataModel::alarm_set(uint32_t alid) {
auto it = alarms_.find(alid);
if (it == alarms_.end()) return std::nullopt;
alarms_active_.insert(alid);
return static_cast<uint8_t>((it->second.severity_category & 0x7F) | 0x80);
}
std::optional<uint8_t> EquipmentDataModel::alarm_clear(uint32_t alid) {
auto it = alarms_.find(alid);
if (it == alarms_.end()) return std::nullopt;
alarms_active_.erase(alid);
return static_cast<uint8_t>(it->second.severity_category & 0x7F);
}
bool EquipmentDataModel::alarm_active(uint32_t alid) const {
return alarms_active_.count(alid) > 0;
}
// ---- Process programs ----------------------------------------------------
void EquipmentDataModel::add_process_program(std::string ppid, std::string ppbody) {
process_programs_.insert_or_assign(std::move(ppid), std::move(ppbody));
}
std::optional<std::string> EquipmentDataModel::process_program(const std::string& ppid) const {
auto it = process_programs_.find(ppid);
if (it == process_programs_.end()) return std::nullopt;
return it->second;
}
std::vector<std::string> EquipmentDataModel::process_program_list() const {
std::vector<std::string> out;
out.reserve(process_programs_.size());
for (const auto& [k, _] : process_programs_) out.push_back(k);
return out;
}
ProcessProgramAck EquipmentDataModel::delete_process_program(const std::string& ppid) {
if (!process_programs_.count(ppid)) return ProcessProgramAck::PpidNotFound;
process_programs_.erase(ppid);
return ProcessProgramAck::Accept;
}
} // namespace secsgem::gem