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