raphael/secs-gem
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Table/YAML-driven refactor (Layer 1 start)

Browse Source 
Move equipment capabilities and the E30 control state machine out of C++
code and into YAML data files; introduce a Router for SECS dispatch;
consolidate small files.

Behavioural changes: none.  Demo identical (15 SxFy transactions +
3 equipment-initiated primaries), 67 test cases / 384 assertions still
all green.  Structural changes only.

Why
---

The previous server.cpp held the equipment data dictionary (3 SVIDs,
2 ECIDs, 3 CEIDs, 2 alarms, 2 recipes, 4 host commands) as imperative
C++ in a 50-line `populate()` function, and routed inbound messages
through a 150-line if-ladder.  Adding a new SVID required a recompile.
Adding a new state transition required editing two switch statements
(`operator_*` and `on_host_request_*`).  The control state machine's
behavioural rules were spread across imperative code in two methods.

This is exactly what implementation_plan.md calls out as the wrong
shape: behavioural rules should live in versioned data, and every
runtime/test/analyzer should read from that data rather than re-encode
it.  This commit starts that move.

What's new
----------

data/equipment.yaml
  Equipment data dictionary.  Declarative SVIDs / ECIDs / CEIDs /
  alarms / recipes / host commands.  Host commands carry their HCACK
  ack code plus optional `emit_ceid` and `set_alarm` side-effects.
  Adding a new SVID or command is a YAML edit, no recompile.

data/control_state.yaml
  The E30 §6.2 control state transition table as data.  Each row is
  (from, on) -> (to [, then] [, ack]).  `then` chains an auto-advance
  through the transient AttemptOnline state.  The previous
  imperative switch is gone.

include/secsgem/config/loader.hpp + src/config/loader.cpp
  yaml-cpp-backed loader.  `load_control_state(path)` returns a
  ControlTransitionTable + initial state; `load_equipment(path, model)`
  populates the EquipmentDataModel and returns the device descriptor
  (id, MDLN, SOFTREV, optional auto-emit CEID).  Surfaces config
  errors with file path + field name via ConfigError.

include/secsgem/gem/router.hpp  (header-only)
  Small (stream, function) -> handler map.  Server registers all
  handlers once at startup, then the Connection's message handler is
  just `router.dispatch(msg)`.  Unhandled primaries with W set get
  SxF0 by default.  Replaces the if-ladder in secs_server.cpp.

include/secsgem/gem/control_state.hpp + .cpp
  ControlTransitionTable is the new pure data type.  ControlStateMachine
  is now a thin engine over the table: `fire(event)` looks up the row,
  optionally transitions, optionally chains a `then` transition, returns
  the ack code.  Behaviour rules no longer live in C++ switches.
  The default in-code table matches data/control_state.yaml row for row;
  tests rely on it so they don't need the YAML file.

include/secsgem/gem/data_model.hpp + .cpp
  `register_command(rcmd, CommandSpec)` replaces the function-handler
  signature.  CommandSpec = (HostCmdAck, optional emit_ceid, optional
  set_alarm).  `dispatch_command` returns a CommandResult so the server
  can fire the side-effects after S2F42 is sent.

apps/secs_server.cpp
  No populate(), no if-ladder.  Loads equipment.yaml + control_state.yaml
  at startup (clean error on bad config), wires the Router once,
  delegates dispatch.  Sm change handler reads emit_on_control_change
  from the YAML.  Welcome S10F3 removed for parity with config (a future
  YAML rule could re-introduce it declaratively).

tests/test_loader.cpp  (new)
  Verifies the YAML loader produces the same shape as the in-code
  default table, and that equipment.yaml populates every section
  (SVIDs/ECIDs/CEIDs/alarms/recipes/commands).  SECSGEM_DATA_DIR
  CMake define points at ${CMAKE_SOURCE_DIR}/data so tests don't
  depend on cwd.

CMakeLists.txt, Dockerfile
  find_package(yaml-cpp) and link.  libyaml-cpp-dev added to the
  Ubuntu base image (yaml-cpp 0.8 ships the modern target name).

File consolidation
------------------

Five small files removed; their content lives in fewer headers:

  - secs2/item.cpp        -> inline in secs2/item.hpp
  - secs2/message.cpp     -> inline in secs2/message.hpp
  - hsms/types.hpp        -> merged into hsms/header.hpp
  - hsms/frame.hpp        -> merged into hsms/header.hpp
  - hsms/frame.cpp        -> merged into hsms/header.cpp

hsms/header.hpp is now "the HSMS wire format" in one place: SType + status
enums + Timers + Header + Frame + constants.  All includers updated.

Net effect
----------

Before: equipment data dictionary lived in 50 lines of imperative
populate() inside secs_server.cpp; dispatch in a 20-branch if-ladder.

After: equipment data dictionary lives in 47 lines of YAML; dispatch
is a Router built once.  Adding a new capability is now a YAML edit
in the common case.

Test count up to 67 cases / 384 assertions (+4 cases / +106 assertions)
covering the loader and the new table-driven SM paths.

What's NOT changed
------------------

The per-SxFy reply construction still lives in C++ (each message has a
unique body shape).  Moving those into YAML/JSON message-shape
definitions is the next refactor step but requires a generic typed
encoder/decoder driven by shape descriptors; out of scope here.

Spooling, the S9 error stream, S1F19/F20, and the other gaps in
COMPLIANCE.md remain unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Raphael Maenle
2026-06-02 08:57:38 +02:00
parent 96b02f8b50
commit b871cd9da2
28 changed files with 1141 additions and 682 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/secsgem/gem/control_state.hpp
+51 -33
View File
@@ -2,25 +2,25 @@
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
#include <vector>
namespace secsgem::gem {
// E30 Control State Model (§6.2). Drives whether the equipment is
// communicating with a host and, if so, who is in control.
// E30 §6.2 Control State Model.
enum class ControlState {
EquipmentOffline, // equipment is offline; no host comms attempted
AttemptOnline, // transient: equipment trying to come online
HostOffline, // HSMS up but host has not established control
OnlineLocal, // online, operator in control; host observes only
OnlineRemote, // online, host in control
EquipmentOffline,
AttemptOnline,
HostOffline,
OnlineLocal,
OnlineRemote,
};
const char* control_state_name(ControlState s);
std::optional<ControlState> parse_control_state(const std::string& s);
bool is_online(ControlState s);
// What triggered a state change — surfaced to the on_change handler so the UI
// or logs can show *why* the state moved.
enum class ControlEvent {
OperatorSwitchOnline,
OperatorSwitchOffline,
@@ -28,72 +28,90 @@ enum class ControlEvent {
OperatorSwitchRemote,
AttemptComplete,
AttemptFailed,
HostRequestOnline, // S1F17
HostRequestOffline, // S1F15
HostRequestOnline,
HostRequestOffline,
};
const char* control_event_name(ControlEvent e);
std::optional<ControlEvent> parse_control_event(const std::string& s);
// S1F18 ONLACK codes.
enum class OnlineAck : uint8_t {
Accept = 0,
NotAccept = 1,
AlreadyOnline = 2,
};
// S1F16 OFLACK codes.
enum class OfflineAck : uint8_t {
Accept = 0,
};
// S1F14 COMMACK codes.
enum class CommAck : uint8_t {
Accept = 0,
Denied = 1,
};
// Drives the E30 control state. Pure state machine — no IO. The Server layer
// owns one of these per equipment and dispatches host-initiated events and
// operator actions into it.
// One row of the control-state transition table (E30 §6.2 + extensions).
// `to` and `then` are both optional: a row may produce no transition (e.g.
// host_request_online while already OnlineRemote — ack only); a row may also
// chain straight through the transient AttemptOnline state via `then`.
// `ack_code` is the raw uint8_t carried by S1F18 (ONLACK) or S1F16 (OFLACK);
// its interpretation depends on the triggering event.
struct ControlTransition {
ControlState from;
ControlEvent on;
std::optional<ControlState> to;
std::optional<ControlState> then;
std::optional<uint8_t> ack_code;
};
// Pure data table — no behaviour. Lookup is first-match on (from, on).
class ControlTransitionTable {
public:
void add(ControlTransition row);
const ControlTransition* find(ControlState from, ControlEvent on) const;
std::size_t size() const { return rows_.size(); }
const std::vector<ControlTransition>& rows() const { return rows_; }
// Built-in default table, matching data/control_state.yaml exactly.
// Used by tests so they don't depend on the YAML file being present.
static ControlTransitionTable default_table();
private:
std::vector<ControlTransition> rows_;
};
// The E30 control state machine, driven by a transition table. All
// behavioural rules live in the table; this class is just the engine.
class ControlStateMachine {
public:
struct Config {
ControlState initial = ControlState::HostOffline;
// When ATTEMPT_ONLINE completes via a host request, do we land in REMOTE
// (host in control) or LOCAL (host observes only)? For host-initiated
// online this defaults to REMOTE; for operator-initiated online it follows
// `operator_default_remote`.
bool host_request_grants_remote = true;
bool operator_default_remote = false;
};
using StateChangeHandler =
std::function<void(ControlState from, ControlState to, ControlEvent trigger)>;
ControlStateMachine();
explicit ControlStateMachine(Config cfg);
explicit ControlStateMachine(ControlTransitionTable table,
ControlState initial = ControlState::HostOffline);
ControlState state() const { return state_; }
bool online() const { return is_online(state_); }
void set_state_change_handler(StateChangeHandler h) { on_change_ = std::move(h); }
// Operator actions. Each returns true if a transition occurred, false if the
// current state didn't permit it.
// Operator actions. Return true if a transition (or self-ack) was found.
bool operator_online();
bool operator_offline();
bool operator_local();
bool operator_remote();
// Host-initiated requests. The SM responds with the SEMI-mandated ack code
// and performs any transition.
// Host requests. Return the ack code from the matching table row.
OnlineAck on_host_request_online();
OfflineAck on_host_request_offline();
private:
// Apply the matching row (if any) for (state_, event); returns the row.
const ControlTransition* fire(ControlEvent on);
void transition(ControlState next, ControlEvent trigger);
Config cfg_;
ControlTransitionTable table_;
ControlState state_;
StateChangeHandler on_change_;
};