Table/YAML-driven refactor (Layer 1 start)
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:
+101
-68
@@ -1,5 +1,7 @@
|
||||
#include "secsgem/gem/control_state.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
|
||||
namespace secsgem::gem {
|
||||
|
||||
const char* control_state_name(ControlState s) {
|
||||
@@ -13,6 +15,15 @@ const char* control_state_name(ControlState s) {
|
||||
return "?";
|
||||
}
|
||||
|
||||
std::optional<ControlState> parse_control_state(const std::string& s) {
|
||||
if (s == "EquipmentOffline") return ControlState::EquipmentOffline;
|
||||
if (s == "AttemptOnline") return ControlState::AttemptOnline;
|
||||
if (s == "HostOffline") return ControlState::HostOffline;
|
||||
if (s == "OnlineLocal") return ControlState::OnlineLocal;
|
||||
if (s == "OnlineRemote") return ControlState::OnlineRemote;
|
||||
return std::nullopt;
|
||||
}
|
||||
|
||||
bool is_online(ControlState s) {
|
||||
return s == ControlState::OnlineLocal || s == ControlState::OnlineRemote;
|
||||
}
|
||||
@@ -31,10 +42,79 @@ const char* control_event_name(ControlEvent e) {
|
||||
return "?";
|
||||
}
|
||||
|
||||
ControlStateMachine::ControlStateMachine() : ControlStateMachine(Config{}) {}
|
||||
std::optional<ControlEvent> parse_control_event(const std::string& s) {
|
||||
if (s == "operator_online") return ControlEvent::OperatorSwitchOnline;
|
||||
if (s == "operator_offline") return ControlEvent::OperatorSwitchOffline;
|
||||
if (s == "operator_local") return ControlEvent::OperatorSwitchLocal;
|
||||
if (s == "operator_remote") return ControlEvent::OperatorSwitchRemote;
|
||||
if (s == "attempt_complete") return ControlEvent::AttemptComplete;
|
||||
if (s == "attempt_failed") return ControlEvent::AttemptFailed;
|
||||
if (s == "host_request_online") return ControlEvent::HostRequestOnline;
|
||||
if (s == "host_request_offline") return ControlEvent::HostRequestOffline;
|
||||
return std::nullopt;
|
||||
}
|
||||
|
||||
ControlStateMachine::ControlStateMachine(Config cfg)
|
||||
: cfg_(cfg), state_(cfg.initial) {}
|
||||
void ControlTransitionTable::add(ControlTransition row) {
|
||||
rows_.push_back(row);
|
||||
}
|
||||
|
||||
const ControlTransition* ControlTransitionTable::find(ControlState from,
|
||||
ControlEvent on) const {
|
||||
for (const auto& r : rows_) {
|
||||
if (r.from == from && r.on == on) return &r;
|
||||
}
|
||||
return nullptr;
|
||||
}
|
||||
|
||||
ControlTransitionTable ControlTransitionTable::default_table() {
|
||||
using S = ControlState;
|
||||
using E = ControlEvent;
|
||||
using A = OnlineAck;
|
||||
ControlTransitionTable t;
|
||||
|
||||
// Host: Request Online
|
||||
t.add({S::HostOffline, E::HostRequestOnline, S::AttemptOnline, S::OnlineRemote,
|
||||
static_cast<uint8_t>(A::Accept)});
|
||||
t.add({S::OnlineLocal, E::HostRequestOnline, std::nullopt, std::nullopt,
|
||||
static_cast<uint8_t>(A::AlreadyOnline)});
|
||||
t.add({S::OnlineRemote, E::HostRequestOnline, std::nullopt, std::nullopt,
|
||||
static_cast<uint8_t>(A::AlreadyOnline)});
|
||||
t.add({S::EquipmentOffline, E::HostRequestOnline, std::nullopt, std::nullopt,
|
||||
static_cast<uint8_t>(A::NotAccept)});
|
||||
t.add({S::AttemptOnline, E::HostRequestOnline, std::nullopt, std::nullopt,
|
||||
static_cast<uint8_t>(A::NotAccept)});
|
||||
|
||||
// Host: Request Offline (always accept, idempotent)
|
||||
for (auto from : {S::EquipmentOffline, S::HostOffline, S::AttemptOnline}) {
|
||||
t.add({from, E::HostRequestOffline, std::nullopt, std::nullopt,
|
||||
static_cast<uint8_t>(OfflineAck::Accept)});
|
||||
}
|
||||
t.add({S::OnlineLocal, E::HostRequestOffline, S::HostOffline, std::nullopt,
|
||||
static_cast<uint8_t>(OfflineAck::Accept)});
|
||||
t.add({S::OnlineRemote, E::HostRequestOffline, S::HostOffline, std::nullopt,
|
||||
static_cast<uint8_t>(OfflineAck::Accept)});
|
||||
|
||||
// Operator: Online (-> Local by default)
|
||||
t.add({S::EquipmentOffline, E::OperatorSwitchOnline, S::AttemptOnline, S::OnlineLocal, std::nullopt});
|
||||
t.add({S::HostOffline, E::OperatorSwitchOnline, S::AttemptOnline, S::OnlineLocal, std::nullopt});
|
||||
|
||||
// Operator: Offline
|
||||
t.add({S::OnlineLocal, E::OperatorSwitchOffline, S::HostOffline, std::nullopt, std::nullopt});
|
||||
t.add({S::OnlineRemote, E::OperatorSwitchOffline, S::HostOffline, std::nullopt, std::nullopt});
|
||||
t.add({S::AttemptOnline, E::OperatorSwitchOffline, S::HostOffline, std::nullopt, std::nullopt});
|
||||
|
||||
// Operator: Local <-> Remote
|
||||
t.add({S::OnlineRemote, E::OperatorSwitchLocal, S::OnlineLocal, std::nullopt, std::nullopt});
|
||||
t.add({S::OnlineLocal, E::OperatorSwitchRemote, S::OnlineRemote, std::nullopt, std::nullopt});
|
||||
|
||||
return t;
|
||||
}
|
||||
|
||||
ControlStateMachine::ControlStateMachine()
|
||||
: ControlStateMachine(ControlTransitionTable::default_table(), ControlState::HostOffline) {}
|
||||
|
||||
ControlStateMachine::ControlStateMachine(ControlTransitionTable table, ControlState initial)
|
||||
: table_(std::move(table)), state_(initial) {}
|
||||
|
||||
void ControlStateMachine::transition(ControlState next, ControlEvent trigger) {
|
||||
if (state_ == next) return;
|
||||
@@ -43,84 +123,37 @@ void ControlStateMachine::transition(ControlState next, ControlEvent trigger) {
|
||||
if (on_change_) on_change_(prev, next, trigger);
|
||||
}
|
||||
|
||||
const ControlTransition* ControlStateMachine::fire(ControlEvent on) {
|
||||
const ControlTransition* row = table_.find(state_, on);
|
||||
if (!row) return nullptr;
|
||||
if (row->to) transition(*row->to, on);
|
||||
if (row->then) transition(*row->then, ControlEvent::AttemptComplete);
|
||||
return row;
|
||||
}
|
||||
|
||||
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;
|
||||
return fire(ControlEvent::OperatorSwitchOnline) != nullptr;
|
||||
}
|
||||
|
||||
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;
|
||||
return fire(ControlEvent::OperatorSwitchOffline) != nullptr;
|
||||
}
|
||||
|
||||
bool ControlStateMachine::operator_local() {
|
||||
if (state_ == ControlState::OnlineRemote) {
|
||||
transition(ControlState::OnlineLocal, ControlEvent::OperatorSwitchLocal);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
return fire(ControlEvent::OperatorSwitchLocal) != nullptr;
|
||||
}
|
||||
|
||||
bool ControlStateMachine::operator_remote() {
|
||||
if (state_ == ControlState::OnlineLocal) {
|
||||
transition(ControlState::OnlineRemote, ControlEvent::OperatorSwitchRemote);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
return fire(ControlEvent::OperatorSwitchRemote) != nullptr;
|
||||
}
|
||||
|
||||
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;
|
||||
const ControlTransition* row = fire(ControlEvent::HostRequestOnline);
|
||||
if (!row || !row->ack_code) return OnlineAck::NotAccept;
|
||||
return static_cast<OnlineAck>(*row->ack_code);
|
||||
}
|
||||
|
||||
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;
|
||||
const ControlTransition* row = fire(ControlEvent::HostRequestOffline);
|
||||
if (!row || !row->ack_code) return OfflineAck::Accept;
|
||||
return static_cast<OfflineAck>(*row->ack_code);
|
||||
}
|
||||
|
||||
} // namespace secsgem::gem
|
||||
|
||||
@@ -142,17 +142,17 @@ TimeAck EquipmentDataModel::set_time_string(const std::string& s) {
|
||||
|
||||
// ---- Host commands -------------------------------------------------------
|
||||
|
||||
void EquipmentDataModel::register_command(const std::string& rcmd, HostCommandHandler handler) {
|
||||
commands_.insert_or_assign(rcmd, std::move(handler));
|
||||
void EquipmentDataModel::register_command(const std::string& rcmd, CommandSpec spec) {
|
||||
commands_.insert_or_assign(rcmd, std::move(spec));
|
||||
}
|
||||
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 {
|
||||
EquipmentDataModel::CommandResult 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);
|
||||
if (it == commands_.end()) return {HostCmdAck::InvalidCommand, std::nullopt, std::nullopt};
|
||||
return {it->second.ack, it->second.emit_ceid, it->second.set_alarm};
|
||||
}
|
||||
|
||||
// ---- Collection events ---------------------------------------------------
|
||||
|
||||
Reference in New Issue
Block a user