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:
@@ -0,0 +1,214 @@
|
||||
#include "secsgem/config/loader.hpp"
|
||||
|
||||
#include <yaml-cpp/yaml.h>
|
||||
|
||||
#include <cstdint>
|
||||
#include <stdexcept>
|
||||
#include <string>
|
||||
|
||||
#include "secsgem/secs2/item.hpp"
|
||||
|
||||
namespace secsgem::config {
|
||||
|
||||
namespace s2 = secsgem::secs2;
|
||||
namespace gem = secsgem::gem;
|
||||
|
||||
namespace {
|
||||
|
||||
[[noreturn]] void fail(const std::string& path, const std::string& what) {
|
||||
throw ConfigError(path + ": " + what);
|
||||
}
|
||||
|
||||
template <typename T>
|
||||
T req_as(const YAML::Node& n, const std::string& path, const char* field) {
|
||||
if (!n) fail(path, std::string("missing required field `") + field + "`");
|
||||
try {
|
||||
return n.as<T>();
|
||||
} catch (const YAML::Exception& e) {
|
||||
fail(path, std::string("field `") + field + "`: " + e.what());
|
||||
}
|
||||
}
|
||||
|
||||
// Build a SECS-II Item from a (type, value) pair in YAML.
|
||||
s2::Item make_item(const YAML::Node& type_n, const YAML::Node& value_n,
|
||||
const std::string& path) {
|
||||
if (!type_n) fail(path, "missing `type` for value");
|
||||
const auto type = type_n.as<std::string>();
|
||||
if (type == "ASCII") return s2::Item::ascii(value_n ? value_n.as<std::string>() : "");
|
||||
if (type == "BOOLEAN") return s2::Item::boolean(value_n && value_n.as<bool>());
|
||||
if (type == "BINARY") {
|
||||
std::vector<uint8_t> b;
|
||||
if (value_n && value_n.IsSequence())
|
||||
for (const auto& e : value_n) b.push_back(static_cast<uint8_t>(e.as<int>()));
|
||||
return s2::Item::binary(std::move(b));
|
||||
}
|
||||
if (type == "U1") return s2::Item::u1(static_cast<uint8_t>(value_n.as<int>()));
|
||||
if (type == "U2") return s2::Item::u2(static_cast<uint16_t>(value_n.as<int>()));
|
||||
if (type == "U4") return s2::Item::u4(static_cast<uint32_t>(value_n.as<uint64_t>()));
|
||||
if (type == "U8") return s2::Item::u8(value_n.as<uint64_t>());
|
||||
if (type == "I1") return s2::Item::i1(static_cast<int8_t>(value_n.as<int>()));
|
||||
if (type == "I2") return s2::Item::i2(static_cast<int16_t>(value_n.as<int>()));
|
||||
if (type == "I4") return s2::Item::i4(static_cast<int32_t>(value_n.as<int>()));
|
||||
if (type == "I8") return s2::Item::i8(value_n.as<int64_t>());
|
||||
if (type == "F4") return s2::Item::f4(value_n.as<float>());
|
||||
if (type == "F8") return s2::Item::f8(value_n.as<double>());
|
||||
fail(path, "unknown SECS-II type `" + type + "`");
|
||||
}
|
||||
|
||||
gem::OnlineAck parse_ack(const std::string& s, const std::string& path) {
|
||||
if (s == "Accept") return gem::OnlineAck::Accept;
|
||||
if (s == "NotAccept") return gem::OnlineAck::NotAccept;
|
||||
if (s == "AlreadyOnline") return gem::OnlineAck::AlreadyOnline;
|
||||
fail(path, "unknown ack `" + s + "` (expected Accept/NotAccept/AlreadyOnline)");
|
||||
}
|
||||
|
||||
gem::HostCmdAck parse_hcack(const std::string& s, const std::string& path) {
|
||||
if (s == "Accept") return gem::HostCmdAck::Accept;
|
||||
if (s == "InvalidCommand") return gem::HostCmdAck::InvalidCommand;
|
||||
if (s == "CannotDoNow") return gem::HostCmdAck::CannotDoNow;
|
||||
if (s == "ParameterInvalid") return gem::HostCmdAck::ParameterInvalid;
|
||||
if (s == "AcceptedWillFinishLater") return gem::HostCmdAck::AcceptedWillFinishLater;
|
||||
if (s == "Rejected") return gem::HostCmdAck::Rejected;
|
||||
if (s == "InvalidObject") return gem::HostCmdAck::InvalidObject;
|
||||
fail(path, "unknown HCACK `" + s + "`");
|
||||
}
|
||||
|
||||
YAML::Node load(const std::string& path) {
|
||||
try {
|
||||
return YAML::LoadFile(path);
|
||||
} catch (const YAML::Exception& e) {
|
||||
fail(path, std::string("YAML parse error: ") + e.what());
|
||||
}
|
||||
}
|
||||
|
||||
} // namespace
|
||||
|
||||
ControlStateConfig load_control_state(const std::string& path) {
|
||||
YAML::Node root = load(path);
|
||||
|
||||
ControlStateConfig cfg;
|
||||
if (auto initial = root["initial"]) {
|
||||
auto parsed = gem::parse_control_state(initial.as<std::string>());
|
||||
if (!parsed) fail(path, "unknown initial state `" + initial.as<std::string>() + "`");
|
||||
cfg.initial = *parsed;
|
||||
}
|
||||
|
||||
const auto transitions = root["transitions"];
|
||||
if (!transitions || !transitions.IsSequence())
|
||||
fail(path, "missing or non-sequence `transitions`");
|
||||
|
||||
for (std::size_t i = 0; i < transitions.size(); ++i) {
|
||||
const auto& row = transitions[i];
|
||||
const auto where = path + " transitions[" + std::to_string(i) + "]";
|
||||
|
||||
auto from = gem::parse_control_state(req_as<std::string>(row["from"], where, "from"));
|
||||
auto on = gem::parse_control_event(req_as<std::string>(row["on"], where, "on"));
|
||||
if (!from) fail(where, "unknown `from` state");
|
||||
if (!on) fail(where, "unknown `on` event");
|
||||
|
||||
gem::ControlTransition t{*from, *on, std::nullopt, std::nullopt, std::nullopt};
|
||||
if (auto to = row["to"]) {
|
||||
auto s = gem::parse_control_state(to.as<std::string>());
|
||||
if (!s) fail(where, "unknown `to` state");
|
||||
t.to = *s;
|
||||
}
|
||||
if (auto th = row["then"]) {
|
||||
auto s = gem::parse_control_state(th.as<std::string>());
|
||||
if (!s) fail(where, "unknown `then` state");
|
||||
t.then = *s;
|
||||
}
|
||||
if (auto ack = row["ack"]) {
|
||||
const auto s = ack.as<std::string>();
|
||||
const auto is_offline = (*on == gem::ControlEvent::HostRequestOffline);
|
||||
if (is_offline) {
|
||||
if (s != "Accept") fail(where, "OfflineAck only supports `Accept`");
|
||||
t.ack_code = static_cast<uint8_t>(gem::OfflineAck::Accept);
|
||||
} else {
|
||||
t.ack_code = static_cast<uint8_t>(parse_ack(s, where));
|
||||
}
|
||||
}
|
||||
cfg.table.add(t);
|
||||
}
|
||||
return cfg;
|
||||
}
|
||||
|
||||
EquipmentDescriptor load_equipment(const std::string& path, gem::EquipmentDataModel& model) {
|
||||
YAML::Node root = load(path);
|
||||
|
||||
EquipmentDescriptor desc;
|
||||
if (auto d = root["device"]) {
|
||||
desc.device_id = static_cast<uint16_t>(d["id"].as<int>());
|
||||
desc.model_name = d["model_name"].as<std::string>();
|
||||
desc.software_rev = d["software_rev"].as<std::string>();
|
||||
}
|
||||
if (auto e = root["emit_on_control_change"]) {
|
||||
if (!e.IsNull()) desc.emit_on_control_change = static_cast<uint32_t>(e.as<int>());
|
||||
}
|
||||
|
||||
if (auto svids = root["svids"]) {
|
||||
for (const auto& sv : svids) {
|
||||
model.add_status_variable({
|
||||
static_cast<uint32_t>(sv["id"].as<int>()),
|
||||
sv["name"].as<std::string>(),
|
||||
sv["units"] ? sv["units"].as<std::string>() : "",
|
||||
make_item(sv["type"], sv["value"], path + " svid"),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (auto ecids = root["ecids"]) {
|
||||
for (const auto& ec : ecids) {
|
||||
const auto value = make_item(ec["type"], ec["value"], path + " ecid");
|
||||
model.add_equipment_constant({
|
||||
static_cast<uint32_t>(ec["id"].as<int>()),
|
||||
ec["name"].as<std::string>(),
|
||||
ec["units"] ? ec["units"].as<std::string>() : "",
|
||||
value,
|
||||
value, // default = initial value
|
||||
ec["min"] ? ec["min"].as<std::string>() : "",
|
||||
ec["max"] ? ec["max"].as<std::string>() : "",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (auto ceids = root["ceids"]) {
|
||||
for (const auto& ce : ceids) {
|
||||
model.register_event({
|
||||
static_cast<uint32_t>(ce["id"].as<int>()),
|
||||
ce["name"].as<std::string>(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (auto alarms = root["alarms"]) {
|
||||
for (const auto& a : alarms) {
|
||||
model.add_alarm({
|
||||
static_cast<uint32_t>(a["id"].as<int>()),
|
||||
a["text"].as<std::string>(),
|
||||
static_cast<uint8_t>(a["category"].as<int>()),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (auto recipes = root["recipes"]) {
|
||||
for (const auto& r : recipes) {
|
||||
model.add_process_program(r["id"].as<std::string>(), r["body"].as<std::string>());
|
||||
}
|
||||
}
|
||||
|
||||
if (auto commands = root["host_commands"]) {
|
||||
for (const auto& c : commands) {
|
||||
gem::EquipmentDataModel::CommandSpec spec;
|
||||
spec.ack = parse_hcack(c["ack"].as<std::string>(), path + " host_commands");
|
||||
if (auto e = c["emit_ceid"])
|
||||
spec.emit_ceid = static_cast<uint32_t>(e.as<int>());
|
||||
if (auto a = c["set_alarm"])
|
||||
spec.set_alarm = static_cast<uint32_t>(a.as<int>());
|
||||
model.register_command(c["name"].as<std::string>(), spec);
|
||||
}
|
||||
}
|
||||
|
||||
return desc;
|
||||
}
|
||||
|
||||
} // namespace secsgem::config
|
||||
Reference in New Issue
Block a user