secs-gem/examples/pvd_tool/main.cpp

// ACME-PVD-3000 — worked vendor application.
//
// This is what a real tool integrator's main() looks like.  Everything
// SECS-shaped (the data dictionary, the message catalogue, the state
// tables) comes from YAML; this file is the *vendor side* — the bits
// that connect the library to the actual tool:
//
//   §1.  Helpers and constants
//   §2.  Sensor simulator (4 sensors at 3 different cadences)
//   §3.  Recipe runner (drives PJ FSM through Processing → Complete)
//   §4.  Alarm threshold monitor (pressure-based)
//   §5.  EPT cycling (Standby ↔ Productive ↔ UnscheduledDowntime)
//   §6.  Router handlers (the minimum set; mostly copied from
//        apps/secs_server.cpp which has the full catalogue)
//   §7.  main() — wires everything together, including the
//        Prometheus metrics exporter on :9090 (§7.3)
//
// This file is deliberately self-contained — no pvd_internal/ helper
// headers, no factored-out "framework."  Customers should be able to
// fork this single file as a starting template.
//
// What's *not* here that production deployment needs:
//   - docs/SECURITY.md: nftables, stunnel, minisign signing.
//   - The other router handlers (S5/S6/S7/S10/S14/S16) — apps/
//     secs_server.cpp has them all.  We register the ones a demo
//     host actually exercises here.

#include <asio.hpp>
#include <atomic>
#include <chrono>
#include <cstdint>
#include <iostream>
#include <memory>
#include <optional>
#include <random>
#include <sstream>
#include <string>
#include <vector>

#include "secsgem/config/validate.hpp"
#include "secsgem/gem/data_model.hpp"
#include "secsgem/gem/default_handlers.hpp"
#include "secsgem/gem/runtime.hpp"
#include "secsgem/metrics/prometheus.hpp"
#include "secsgem/secs2/item.hpp"

using namespace secsgem;
using namespace std::chrono_literals;
namespace s2 = secsgem::secs2;
namespace gem = secsgem::gem;

// =============================================================================
// §1.  Helpers and constants
// =============================================================================

namespace pvd {

constexpr uint32_t kSvidControlState   = 1;
constexpr uint32_t kSvidClock          = 2;
constexpr uint32_t kSvidChamberPressure = 10;
constexpr uint32_t kSvidChamberTemp     = 11;
constexpr uint32_t kSvidVacuumPumpRpm   = 13;
constexpr uint32_t kSvidSourcePower     = 20;
constexpr uint32_t kSvidTargetVoltage   = 21;
constexpr uint32_t kSvidSourceMaterial  = 23;
constexpr uint32_t kSvidArgonFlow       = 30;
constexpr uint32_t kSvidNitrogenFlow    = 31;
constexpr uint32_t kSvidCoolingWater    = 32;
constexpr uint32_t kSvidWaferTotal      = 50;
constexpr uint32_t kSvidWafersSinceClean = 51;
constexpr uint32_t kSvidActivePpid      = 53;
constexpr uint32_t kSvidStepName        = 54;
constexpr uint32_t kSvidStepElapsed     = 55;
constexpr uint32_t kSvidEptName         = 70;
constexpr uint32_t kSvidProductiveHours = 71;

constexpr uint32_t kEcChamberPressureSp = 100;
constexpr uint32_t kEcSourcePowerSp     = 102;
constexpr uint32_t kEcCleaningInterval  = 105;

constexpr uint32_t kCeidProcessStarted   = 300;
constexpr uint32_t kCeidProcessCompleted = 301;
constexpr uint32_t kCeidStepStarted      = 310;
constexpr uint32_t kCeidStepCompleted    = 311;
constexpr uint32_t kCeidCJExecuting      = 400;
constexpr uint32_t kCeidCJCompleted      = 401;

constexpr uint32_t kAlarmPressureHigh    = 1;
constexpr uint32_t kAlarmTempOutOfRange  = 3;
constexpr uint32_t kAlarmSourcePowerLoss = 4;
constexpr uint32_t kAlarmCoolingWaterLoss = 5;
constexpr uint32_t kAlarmTargetEol       = 8;
constexpr uint32_t kAlarmCleaningNeeded  = 10;

// =============================================================================
// §2.  Sensor simulator
// =============================================================================
//
// Real tool sensors come from PLCs / serial buses / DAQ cards.  Here
// we simulate them: a random walk around each sensor's setpoint,
// updated on its natural cadence:
//
//   - Chamber pressure: 10 Hz (fast — a real PLC ticks this rate)
//   - Chamber temperature, gas flows, water flow: 1 Hz
//   - Wafer counters, EPT hours: on-event, not polled
//
// All updates marshal onto the io_context via asio::post — that's
// the thread-safety contract documented in docs/INTEGRATION.md §3.

struct Simulator {
  asio::io_context& io;
  std::shared_ptr<gem::EquipmentDataModel> model;
  std::mt19937 rng{std::random_device{}()};

  // Recipe state — when a recipe is running, sensors track the
  // step's target rather than the default setpoint.
  std::atomic<bool> processing{false};
  std::atomic<float> target_pressure_torr{1.0e-7f};
  std::atomic<float> target_temp_c{25.0f};
  std::atomic<float> source_power_setpoint{0.0f};
  std::atomic<float> argon_flow_setpoint{0.0f};

  std::shared_ptr<asio::steady_timer> fast_timer;
  std::shared_ptr<asio::steady_timer> slow_timer;

  Simulator(asio::io_context& io_,
             std::shared_ptr<gem::EquipmentDataModel> model_)
      : io(io_), model(std::move(model_)),
        fast_timer(std::make_shared<asio::steady_timer>(io)),
        slow_timer(std::make_shared<asio::steady_timer>(io)) {}

  // Random walk around `target` with normal-ish jitter.
  float jitter(float current, float target, float spread) {
    std::normal_distribution<float> n(0.0f, spread);
    const float drift = (target - current) * 0.05f;  // 5% of error toward target
    return current + drift + n(rng);
  }

  void tick_fast() {
    // Read current values, update toward target, write back.
    auto p_sv = model->svids.get(kSvidChamberPressure);
    if (p_sv) {
      const auto& cur = std::get<std::vector<float>>(p_sv->value.storage());
      const float new_p = jitter(cur.empty() ? 1.0e-7f : cur[0],
                                  target_pressure_torr.load(), 1.0e-8f);
      model->svids.set_value(kSvidChamberPressure, s2::Item::f4(new_p));
    }
    fast_timer->expires_after(100ms);
    fast_timer->async_wait([this](std::error_code ec) {
      if (!ec) tick_fast();
    });
  }

  void tick_slow() {
    auto upd_f4 = [&](uint32_t vid, float target, float spread, float fallback) {
      auto cur = model->svids.get(vid);
      const float c = (cur && std::holds_alternative<std::vector<float>>(cur->value.storage()))
                          ? std::get<std::vector<float>>(cur->value.storage())[0]
                          : fallback;
      model->svids.set_value(vid, s2::Item::f4(jitter(c, target, spread)));
    };
    upd_f4(kSvidChamberTemp,   target_temp_c.load(),         0.3f, 25.0f);
    upd_f4(kSvidSourcePower,   source_power_setpoint.load(), 5.0f, 0.0f);
    upd_f4(kSvidArgonFlow,     argon_flow_setpoint.load(),   0.5f, 0.0f);
    upd_f4(40 /*ChuckTemp*/,   target_temp_c.load() - 1.0f,  0.2f, 24.0f);
    upd_f4(41 /*ShieldTemp*/,  target_temp_c.load() - 2.0f,  0.2f, 24.0f);
    upd_f4(kSvidCoolingWater,  12.5f,                        0.1f, 12.5f);

    // Vacuum pump RPM — discrete state: ~0 when chamber pressure
    // > 1 Torr, ramping to ~80 000 when at vacuum.
    auto p_sv = model->svids.get(kSvidChamberPressure);
    if (p_sv) {
      const auto& v = std::get<std::vector<float>>(p_sv->value.storage());
      const float p = v.empty() ? 1.0f : v[0];
      const uint32_t rpm = p < 1.0e-3f ? 80000u : (p < 1.0f ? 40000u : 0u);
      model->svids.set_value(kSvidVacuumPumpRpm, s2::Item::u4(rpm));
    }

    // Update clock SVID for hosts that poll it via S1F3.
    model->svids.set_value(kSvidClock, s2::Item::ascii(
        model->clock.current_time_string()));

    slow_timer->expires_after(1s);
    slow_timer->async_wait([this](std::error_code ec) {
      if (!ec) tick_slow();
    });
  }

  void start() { tick_fast(); tick_slow(); }
};

// =============================================================================
// §3.  Recipe runner
// =============================================================================
//
// Drives a PJ through SettingUp → WaitingForStart → Processing →
// ProcessComplete by stepping through the recipe body line by line.
// Each STEP runs for its declared duration, with the sensor
// simulator's targets adjusted to match the step's parameters.

struct RecipeStep {
  std::string name;
  std::chrono::seconds duration{0};
  std::optional<float> target_pressure_torr;
  std::optional<float> target_temp_c;
  std::optional<float> source_power_w;
  std::optional<float> gas_flow_sccm;
  std::string source_material;
};

// Parse "STEP NAME duration=120s power=2500W gas=Argon flow=50sccm".
RecipeStep parse_step(const std::string& line) {
  RecipeStep s;
  std::istringstream is(line);
  std::string tok;
  is >> tok;  // STEP
  is >> s.name;
  while (is >> tok) {
    auto eq = tok.find('=');
    if (eq == std::string::npos) continue;
    const auto key = tok.substr(0, eq);
    auto val = tok.substr(eq + 1);
    auto strip_unit = [&](const char* unit) {
      const auto p = val.find(unit);
      if (p != std::string::npos) val = val.substr(0, p);
    };
    if (key == "duration") { strip_unit("s"); s.duration = std::chrono::seconds(std::stoi(val)); }
    else if (key == "target") {
      strip_unit("Torr"); strip_unit("C");
      try { s.target_pressure_torr = std::stof(val); } catch (...) {}
      try { if (!s.target_pressure_torr) s.target_temp_c = std::stof(val); } catch (...) {}
    }
    else if (key == "power")   { strip_unit("W");    s.source_power_w  = std::stof(val); }
    else if (key == "flow")    { strip_unit("sccm"); s.gas_flow_sccm   = std::stof(val); }
    else if (key == "gas")     { s.source_material = val; }
  }
  return s;
}

struct RecipeRunner {
  asio::io_context& io;
  std::shared_ptr<gem::EquipmentDataModel> model;
  Simulator& sim;
  std::function<void(uint32_t)> emit_event;

  RecipeRunner(asio::io_context& io_,
                std::shared_ptr<gem::EquipmentDataModel> model_,
                Simulator& sim_,
                std::function<void(uint32_t)> emit_)
      : io(io_), model(std::move(model_)), sim(sim_),
        emit_event(std::move(emit_)) {}

  void start(const std::string& prjobid) {
    auto* pj = model->process_jobs.get(prjobid);
    if (!pj) return;
    const auto body = model->recipes.get(pj->ppid);
    if (!body) return;

    // Parse steps from the recipe body.
    auto steps = std::make_shared<std::vector<RecipeStep>>();
    std::istringstream is(*body);
    std::string line;
    while (std::getline(is, line)) {
      if (line.rfind("STEP", 0) == 0) steps->push_back(parse_step(line));
    }
    model->svids.set_value(kSvidActivePpid, s2::Item::ascii(pj->ppid));
    sim.processing = true;

    run_step(prjobid, steps, 0);
  }

  void run_step(const std::string& prjobid,
                 std::shared_ptr<std::vector<RecipeStep>> steps,
                 std::size_t i) {
    if (i >= steps->size()) {
      // Recipe complete.
      model->process_jobs.fire_internal(prjobid, gem::ProcessJobEvent::ProcessComplete);
      model->svids.set_value(kSvidStepName, s2::Item::ascii(""));
      model->svids.set_value(kSvidStepElapsed, s2::Item::u4(0));
      sim.processing = false;
      sim.target_pressure_torr = 1.0e-7f;
      sim.target_temp_c = 25.0f;
      sim.source_power_setpoint = 0.0f;
      sim.argon_flow_setpoint = 0.0f;
      emit_event(kCeidProcessCompleted);
      return;
    }

    const auto& step = (*steps)[i];
    std::cout << "[recipe] step " << (i + 1) << "/" << steps->size()
              << ": " << step.name << " (" << step.duration.count() << "s)\n";

    model->svids.set_value(kSvidStepName, s2::Item::ascii(step.name));
    model->svids.set_value(kSvidStepElapsed, s2::Item::u4(0));
    if (step.target_pressure_torr) sim.target_pressure_torr = *step.target_pressure_torr;
    if (step.target_temp_c)        sim.target_temp_c        = *step.target_temp_c;
    if (step.source_power_w)       sim.source_power_setpoint = *step.source_power_w;
    if (step.gas_flow_sccm)        sim.argon_flow_setpoint   = *step.gas_flow_sccm;
    if (!step.source_material.empty())
      model->svids.set_value(kSvidSourceMaterial, s2::Item::ascii(step.source_material));

    emit_event(kCeidStepStarted);

    // Run the step for `duration` seconds (compressed to milliseconds
    // for demo runs — a real tool would actually wait the duration).
    // We use 100ms per declared second so a 120s step takes 12s.
    auto step_timer = std::make_shared<asio::steady_timer>(io);
    auto tick = std::make_shared<std::function<void(std::error_code)>>();
    auto elapsed = std::make_shared<std::atomic<uint32_t>>(0);
    *tick = [this, prjobid, steps, i, step_timer, tick, elapsed,
             duration_s = step.duration.count()](std::error_code ec) {
      if (ec) return;
      const uint32_t e = elapsed->fetch_add(1) + 1;
      model->svids.set_value(kSvidStepElapsed, s2::Item::u4(e));
      if (e >= static_cast<uint32_t>(duration_s)) {
        emit_event(kCeidStepCompleted);
        run_step(prjobid, steps, i + 1);
        return;
      }
      step_timer->expires_after(100ms);  // 1 demo-second
      step_timer->async_wait(*tick);
    };
    step_timer->expires_after(100ms);
    step_timer->async_wait(*tick);
  }
};

// =============================================================================
// §4.  Alarm threshold monitor
// =============================================================================

struct AlarmMonitor {
  asio::io_context& io;
  std::shared_ptr<gem::EquipmentDataModel> model;
  std::function<void(uint32_t)> emit_alarm_set;
  std::function<void(uint32_t)> emit_alarm_clear;
  std::shared_ptr<asio::steady_timer> timer;

  AlarmMonitor(asio::io_context& io_,
                std::shared_ptr<gem::EquipmentDataModel> model_,
                std::function<void(uint32_t)> set_,
                std::function<void(uint32_t)> clear_)
      : io(io_), model(std::move(model_)),
        emit_alarm_set(std::move(set_)), emit_alarm_clear(std::move(clear_)),
        timer(std::make_shared<asio::steady_timer>(io)) {}

  void start() { tick(); }

 private:
  void tick() {
    // Chamber pressure alarm: trips if > 2x setpoint.
    auto p_sv = model->svids.get(kSvidChamberPressure);
    auto sp = model->ecids.get(kEcChamberPressureSp);
    if (p_sv && sp) {
      const float p = std::get<std::vector<float>>(p_sv->value.storage())[0];
      const float setpoint = std::get<std::vector<float>>(sp->value.storage())[0];
      const bool over = p > setpoint * 100.0f;  // 2 orders of magnitude
      const bool was = model->alarms.active(kAlarmPressureHigh);
      if (over && !was) emit_alarm_set(kAlarmPressureHigh);
      else if (!over && was) emit_alarm_clear(kAlarmPressureHigh);
    }

    // Cleaning interval: alarm 10 fires when wafers-since-cleanup
    // exceeds the configured interval.
    auto wsc = model->svids.get(kSvidWafersSinceClean);
    auto ci  = model->ecids.get(kEcCleaningInterval);
    if (wsc && ci) {
      const uint32_t cur = std::get<std::vector<uint32_t>>(wsc->value.storage())[0];
      const uint32_t limit = std::get<std::vector<uint32_t>>(ci->value.storage())[0];
      const bool over = cur >= limit;
      const bool was = model->alarms.active(kAlarmCleaningNeeded);
      if (over && !was) emit_alarm_set(kAlarmCleaningNeeded);
      else if (!over && was) emit_alarm_clear(kAlarmCleaningNeeded);
    }

    timer->expires_after(500ms);
    timer->async_wait([this](std::error_code ec) { if (!ec) tick(); });
  }
};

// =============================================================================
// §5.  EPT cycling — E116 Equipment Performance Tracking
// =============================================================================
//
// Real tools transition EPT state based on operator actions, alarm
// activity, and process activity.  Here we follow a simple rule:
//   - Standby when nothing's running and no alarms active
//   - Productive when at least one PJ is in Processing
//   - UnscheduledDowntime when a safety alarm is active

struct EptCycler {
  std::shared_ptr<gem::EquipmentDataModel> model;
  asio::io_context& io;
  std::shared_ptr<asio::steady_timer> timer;

  EptCycler(asio::io_context& io_,
             std::shared_ptr<gem::EquipmentDataModel> m)
      : model(std::move(m)), io(io_),
        timer(std::make_shared<asio::steady_timer>(io)) {}

  void start() { tick(); }

 private:
  void tick() {
    bool any_processing = false;
    for (const auto& id : model->process_jobs.ids()) {
      auto* pj = model->process_jobs.get(id);
      if (pj && pj->fsm->state() == gem::ProcessJobState::Processing) {
        any_processing = true;
        break;
      }
    }
    const bool safety_alarm = model->alarms.active(kAlarmSourcePowerLoss) ||
                              model->alarms.active(kAlarmCoolingWaterLoss);
    const auto cur = model->ept.state();
    gem::EptState target = gem::EptState::Standby;
    if (safety_alarm) target = gem::EptState::UnscheduledDowntime;
    else if (any_processing) target = gem::EptState::Productive;

    if (cur != target) {
      auto ev = gem::EptEvent::EnterStandby;
      if (target == gem::EptState::Productive)            ev = gem::EptEvent::EnterProductive;
      if (target == gem::EptState::UnscheduledDowntime)   ev = gem::EptEvent::EnterUnscheduledDown;
      model->ept.on_event(ev);
    }
    model->svids.set_value(kSvidEptName,
        s2::Item::ascii(gem::ept_state_name(target)));
    timer->expires_after(2s);
    timer->async_wait([this](std::error_code ec) { if (!ec) tick(); });
  }
};

}  // namespace pvd

// =============================================================================
// §6.  main() — the integration, on the modern stack
// =============================================================================
//
// Everything protocol-shaped is three calls now: construct an
// EquipmentRuntime from the YAML, register_default_handlers (all 56 GEM
// handlers + state-change emitters; ids bound via the config's roles:
// defaults), and hook tool behaviour onto the host commands with
// commands.set_handler.  Compare with git history: this main() replaced
// ~650 lines of hand-wired Server/Router/handler plumbing.

int main(int argc, char** argv) {
  const std::string config_path = (argc > 1) ? argv[1] :
      "/app/examples/pvd_tool/equipment.yaml";
  const std::string state_path  = (argc > 2) ? argv[2] :
      "/app/data/control_state.yaml";
  const uint16_t port           = (argc > 3) ?
      static_cast<uint16_t>(std::stoi(argv[3])) : 5000;
  const uint16_t metrics_port   = (argc > 4) ?
      static_cast<uint16_t>(std::stoi(argv[4])) : 9090;

  // ---- Validate the YAML configs before binding the port -----------------
  {
    config::ConfigValidator v;
    v.validate_equipment(config_path);
    v.validate_control_state(state_path);
    if (v.has_errors()) {
      config::format_issues_to(std::cerr, v.issues());
      std::cerr << v.error_count() << " config error(s); refusing to start\n";
      return 1;
    }
  }

  // std::endl (not "\n"): flush per line so logs are visible immediately
  // when stdout is piped (docker logs, CI captures).
  auto logfn = [](const std::string& m) { std::cout << "[pvd] " << m << std::endl; };

  // ---- The engine: one runtime + the default GEM behaviour ---------------
  gem::EquipmentRuntime::Config cfg;
  cfg.equipment_yaml     = config_path;
  cfg.control_state_yaml = state_path;
  cfg.process_job_yaml   = "/app/data/process_job_state.yaml";
  cfg.control_job_yaml   = "/app/data/control_job_state.yaml";
  cfg.port = port;
  cfg.log  = logfn;

  std::unique_ptr<gem::EquipmentRuntime> runtime;
  try {
    runtime = std::make_unique<gem::EquipmentRuntime>(cfg);
  } catch (const std::exception& e) {
    std::cerr << "[pvd] config load failed: " << e.what() << "\n";
    return 1;
  }
  auto& R = *runtime;
  gem::register_default_handlers(R);

  auto model = R.model_ptr();
  logfn("loaded " + std::to_string(model->svids.size()) + " SVIDs, " +
        std::to_string(model->ecids.all().size()) + " ECIDs, " +
        std::to_string(model->events.all_events().size()) + " CEIDs, " +
        std::to_string(model->alarms.all().size()) + " alarms, " +
        std::to_string(model->recipes.list().size()) + " recipes");

  // ---- Metrics exporter on a second port ---------------------------------
  auto registry = std::make_shared<metrics::Registry>();
  registry->describe("pvd_events_total", "Collection events fired",
                      metrics::MetricType::Counter);
  registry->describe("pvd_chamber_pressure_torr", "Process chamber pressure",
                      metrics::MetricType::Gauge);
  registry->describe("pvd_spool_depth", "Queued spool messages",
                      metrics::MetricType::Gauge);
  auto exporter = std::make_shared<metrics::PrometheusServer>(
      R.io(), metrics_port, registry);
  exporter->start();
  logfn("metrics exporter on :" + std::to_string(metrics_port) + "/metrics");

  // ---- Tool behaviour: sensors, EPT, alarms, recipes ----------------------
  // The emit helpers are the runtime's thread-safe API plus a metrics bump.
  auto emit_event = [&R, registry](uint32_t ceid) {
    R.emit_event(ceid);
    registry->inc("pvd_events_total", {{"ceid", std::to_string(ceid)}});
  };
  auto emit_alarm_set   = [&R](uint32_t alid) { R.set_alarm(alid); };
  auto emit_alarm_clear = [&R](uint32_t alid) { R.clear_alarm(alid); };

  auto sim = std::make_shared<pvd::Simulator>(R.io(), model);
  sim->start();
  auto ept = std::make_shared<pvd::EptCycler>(R.io(), model);
  ept->start();
  auto alarm_mon = std::make_shared<pvd::AlarmMonitor>(
      R.io(), model, emit_alarm_set, emit_alarm_clear);
  alarm_mon->start();
  auto recipe_runner = std::make_shared<pvd::RecipeRunner>(
      R.io(), model, *sim, emit_event);

  // Host command behaviour via the set_handler hook (runs on the io thread
  // during S2F41/F21/F49 dispatch) — this used to be a hand-rolled S2F41
  // router override.  The YAML still declares the static ack + emit_ceid;
  // this adds the part config can't express: actually starting the recipe.
  model->commands.set_handler(
      "START", [model, recipe_runner](const std::string&,
                                      const std::vector<gem::CommandParameter>&) {
        for (const auto& pjid : model->process_jobs.ids()) {
          auto* pj = model->process_jobs.get(pjid);
          if (pj && pj->fsm->state() == gem::ProcessJobState::WaitingForStart) {
            model->process_jobs.fire_internal(pjid, gem::ProcessJobEvent::Start);
            recipe_runner->start(pjid);
            break;
          }
        }
        return gem::HostCmdAck::Accept;
      });

  // ---- Periodic gauge updates for Prometheus ------------------------------
  auto gauge_timer = std::make_shared<asio::steady_timer>(R.io());
  auto gauge_tick = std::make_shared<std::function<void(std::error_code)>>();
  *gauge_tick = [gauge_tick, gauge_timer, model, registry](std::error_code ec) {
    if (ec) return;
    auto p = model->svids.get(pvd::kSvidChamberPressure);
    if (p && std::holds_alternative<std::vector<float>>(p->value.storage())) {
      registry->set_gauge("pvd_chamber_pressure_torr",
                          std::get<std::vector<float>>(p->value.storage())[0]);
    }
    registry->set_gauge("pvd_spool_depth", model->spool.size());
    gauge_timer->expires_after(5s);
    gauge_timer->async_wait(*gauge_tick);
  };
  gauge_timer->expires_after(5s);
  gauge_timer->async_wait(*gauge_tick);

  logfn("ACME-PVD-3000 ready, listening on :" + std::to_string(port));
  R.run();  // accept connections + run the io_context (blocks)
  return 0;
}