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>
2026-06-02 00:21:10 +02:00
commit 96b02f8b50
36 changed files with 5210 additions and 0 deletions
@@ -0,0 +1,139 @@
+#pragma once
+
+#include <asio.hpp>
+#include <array>
+#include <cstdint>
+#include <deque>
+#include <functional>
+#include <map>
+#include <memory>
+#include <optional>
+#include <string>
+#include <system_error>
+
+#include "secsgem/hsms/frame.hpp"
+#include "secsgem/hsms/types.hpp"
+#include "secsgem/secs2/message.hpp"
+
+namespace secsgem::hsms {
+
+// One HSMS session over a connected TCP socket. Drives the connection state
+// machine (NOT_SELECTED -> SELECTED), runs the SELECT/LINKTEST/SEPARATE control
+// handshakes and the T3/T6/T7/T8 timers, and correlates data replies by system
+// bytes. Single-threaded: all work runs on the socket's executor.
+class Connection : public std::enable_shared_from_this<Connection> {
+ public:
+  enum class Mode { Active, Passive };
+  enum class State { NotSelected, Selected };
+
+  // Handler for an inbound primary (request) message. Return a reply Message to
+  // send it back (system bytes are filled in automatically), or nullopt for none.
+  using MessageHandler = std::function<std::optional<secs2::Message>(const secs2::Message&)>;
+  using SelectedHandler = std::function<void()>;
+  using ClosedHandler = std::function<void(const std::string& reason)>;
+  using ReplyHandler = std::function<void(std::error_code, const secs2::Message&)>;
+  using LogHandler = std::function<void(const std::string&)>;
+
+  Connection(asio::ip::tcp::socket socket, Mode mode, uint16_t device_id, Timers timers);
+
+  void set_message_handler(MessageHandler h) { on_message_ = std::move(h); }
+  void set_selected_handler(SelectedHandler h) { on_selected_ = std::move(h); }
+  void set_closed_handler(ClosedHandler h) { on_closed_ = std::move(h); }
+  void set_log_handler(LogHandler h) { on_log_ = std::move(h); }
+
+  // Begin the read loop. Active mode also initiates the SELECT handshake;
+  // Passive mode arms the T7 not-selected timer and waits for Select.req.
+  void start();
+
+  // Send a primary data message (W-bit set) and invoke `cb` with the reply or a
+  // timeout/error. Must be SELECTED.
+  void send_request(secs2::Message msg, ReplyHandler cb);
+
+  // Send a data message with no reply expected.
+  void send_data(secs2::Message msg);
+
+  // Graceful teardown: send Separate.req and close.
+  void separate();
+
+  // Hard close.
+  void close(const std::string& reason);
+
+  State state() const { return state_; }
+  bool selected() const { return state_ == State::Selected; }
+
+ private:
+  // --- read path ---
+  void read_length();
+  void on_length(std::error_code ec, std::size_t n);
+  void on_payload(std::error_code ec, std::size_t n);
+  void handle_frame(Frame frame);
+  void handle_data(const Frame& frame);
+  void handle_control(const Frame& frame);
+
+  // --- write path ---
+  void send_frame(Frame frame);
+  void write_next();
+
+  // --- handshakes & timers ---
+  void send_select_req();
+  void send_linktest_req();
+  void enter_selected();
+  void arm_t7();
+  void arm_linktest();
+  void start_control_transaction(SType expected_response, uint32_t system_bytes,
+                                 const char* what);
+  void clear_control_transaction();
+
+  uint32_t next_system_bytes();
+  void log(const std::string& msg);
+
+  asio::ip::tcp::socket socket_;
+  asio::steady_timer t6_timer_;        // control transaction timeout
+  asio::steady_timer t7_timer_;        // not-selected timeout (passive)
+  asio::steady_timer t8_timer_;        // intercharacter timeout (during a read)
+  asio::steady_timer linktest_timer_;  // periodic linktest interval
+
+  Mode mode_;
+  uint16_t device_id_;
+  Timers timers_;
+  State state_ = State::NotSelected;
+  bool closed_ = false;
+
+  std::array<uint8_t, kLengthPrefixSize> len_buf_{};
+  std::vector<uint8_t> payload_;
+
+  std::deque<std::vector<uint8_t>> write_queue_;
+  bool writing_ = false;
+  bool close_after_flush_ = false;
+  std::string close_reason_;
+
+  uint32_t next_system_bytes_ = 1;
+
+  // outstanding data request transactions, keyed by system bytes
+  struct PendingRequest {
+    ReplyHandler cb;
+    std::shared_ptr<asio::steady_timer> t3;
+  };
+  std::map<uint32_t, PendingRequest> pending_requests_;
+
+  // single outstanding control transaction (select / linktest)
+  struct PendingControl {
+    SType expected_response;
+    uint32_t system_bytes;
+  };
+  std::optional<PendingControl> pending_control_;
+
+  MessageHandler on_message_;
+  SelectedHandler on_selected_;
+  ClosedHandler on_closed_;
+  LogHandler on_log_;
+};
+
+// Error category for HSMS protocol-level failures surfaced through ReplyHandler.
+enum class Error {
+  Timeout = 1,
+  Closed = 2,
+};
+std::error_code make_error(Error e);
+
+}  // namespace secsgem::hsms
@@ -0,0 +1,40 @@
+#pragma once
+
+#include <cstdint>
+#include <stdexcept>
+#include <vector>
+
+#include "secsgem/hsms/header.hpp"
+
+namespace secsgem::hsms {
+
+class FrameError : public std::runtime_error {
+ public:
+  using std::runtime_error::runtime_error;
+};
+
+// One HSMS message: a header plus an optional SECS-II body (control messages
+// have no body). On the wire it is prefixed by a 4-byte big-endian length that
+// counts the header (10) plus the body.
+struct Frame {
+  Header header;
+  std::vector<uint8_t> body;
+
+  Frame() = default;
+  explicit Frame(Header h, std::vector<uint8_t> b = {})
+      : header(h), body(std::move(b)) {}
+
+  // Full wire bytes including the 4-byte length prefix.
+  std::vector<uint8_t> encode() const;
+
+  // Decode a message from its payload (header + body, i.e. the bytes that
+  // follow the length prefix). `len` must be >= 10.
+  static Frame decode(const uint8_t* payload, std::size_t len);
+};
+
+// HSMS message length prefix is 4 bytes; payload must be at least the 10-byte
+// header.
+inline constexpr std::size_t kLengthPrefixSize = 4;
+inline constexpr std::size_t kHeaderSize = 10;
+
+}  // namespace secsgem::hsms
@@ -0,0 +1,60 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <string>
+
+#include "secsgem/hsms/types.hpp"
+
+namespace secsgem::hsms {
+
+// The fixed 10-byte HSMS message header (SEMI E37). The interpretation of
+// byte2/byte3 depends on `stype`: for data messages byte2 = (W<<7)|stream and
+// byte3 = function; for control messages they carry status / reason codes.
+struct Header {
+  uint16_t session_id = kControlSessionId;
+  uint8_t byte2 = 0;
+  uint8_t byte3 = 0;
+  uint8_t ptype = kPTypeSecsII;
+  SType stype = SType::Data;
+  uint32_t system_bytes = 0;
+
+  // Data-message field views.
+  bool w_bit() const { return (byte2 & 0x80) != 0; }
+  uint8_t stream() const { return byte2 & 0x7F; }
+  uint8_t function() const { return byte3; }
+
+  static Header data_message(uint16_t session_id, uint8_t stream, uint8_t function,
+                             bool reply_expected, uint32_t system_bytes) {
+    Header h;
+    h.session_id = session_id;
+    h.byte2 = static_cast<uint8_t>((reply_expected ? 0x80 : 0x00) | (stream & 0x7F));
+    h.byte3 = function;
+    h.ptype = kPTypeSecsII;
+    h.stype = SType::Data;
+    h.system_bytes = system_bytes;
+    return h;
+  }
+
+  static Header control(SType stype, uint32_t system_bytes,
+                        uint16_t session_id = kControlSessionId, uint8_t byte2 = 0,
+                        uint8_t byte3 = 0) {
+    Header h;
+    h.session_id = session_id;
+    h.byte2 = byte2;
+    h.byte3 = byte3;
+    h.ptype = kPTypeSecsII;
+    h.stype = stype;
+    h.system_bytes = system_bytes;
+    return h;
+  }
+
+  std::array<uint8_t, 10> encode() const;
+  static Header decode(const uint8_t* data);  // reads exactly 10 bytes
+
+  std::string describe() const;
+
+  bool operator==(const Header&) const = default;
+};
+
+}  // namespace secsgem::hsms
@@ -0,0 +1,62 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+
+namespace secsgem::hsms {
+
+// HSMS session type (byte 5 of the message header) — SEMI E37.
+enum class SType : uint8_t {
+  Data = 0,
+  SelectReq = 1,
+  SelectRsp = 2,
+  DeselectReq = 3,
+  DeselectRsp = 4,
+  LinktestReq = 5,
+  LinktestRsp = 6,
+  RejectReq = 7,
+  SeparateReq = 9,
+};
+
+const char* stype_name(SType s);
+
+// Select.rsp status (header byte 3).
+enum class SelectStatus : uint8_t {
+  Ok = 0,
+  AlreadyActive = 1,
+  NotReady = 2,
+  ConnectExhaust = 3,
+};
+
+// Deselect.rsp status (header byte 3).
+enum class DeselectStatus : uint8_t {
+  Ok = 0,
+  NotEstablished = 1,
+  Busy = 2,
+};
+
+// Reject.req reason code (header byte 3).
+enum class RejectReason : uint8_t {
+  StypeNotSupported = 1,
+  PtypeNotSupported = 2,
+  TransactionNotOpen = 3,
+  EntityNotSelected = 4,
+};
+
+// Presentation type 0 == SECS-II message encoding.
+inline constexpr uint8_t kPTypeSecsII = 0;
+
+// Control messages carry no device id; E37 recommends 0xFFFF.
+inline constexpr uint16_t kControlSessionId = 0xFFFF;
+
+// HSMS protocol timers (SEMI E37 defaults).
+struct Timers {
+  std::chrono::milliseconds t3{45000};  // reply timeout
+  std::chrono::milliseconds t5{10000};  // connect separation timeout
+  std::chrono::milliseconds t6{5000};   // control transaction timeout
+  std::chrono::milliseconds t7{10000};  // not-selected timeout
+  std::chrono::milliseconds t8{5000};   // network intercharacter timeout
+  std::chrono::milliseconds linktest{0};  // linktest interval; 0 disables
+};
+
+}  // namespace secsgem::hsms