secs-gem/examples/pvd_tool/README.md

ACME-PVD-3000 — worked vendor example

A fictional Physical Vapor Deposition tool, end-to-end. This is what a real tool integrator's deployment looks like:

• equipment.yaml — the tool's data dictionary (29 SVIDs, 5 DVIDs, 7 ECIDs, 21 CEIDs, 12 alarms, 3 recipes, 9 host commands)
• main.cpp — the vendor application: sensor simulator, recipe runner, alarm threshold monitor, EPT cycling, metrics exporter, Router handlers wiring it all to the wire.

If you're starting a real integration, fork these two files and customize. They're written to be a template, not an abstract demo.

What it demonstrates

Section in main.cpp	What it shows you how to do
§1 Helpers + constants	The few kSvidX / kCeidX constants worth pinning at file scope
§2 Sensor simulator	Multi-cadence sensor poll loops (10 Hz pressure, 1 Hz temps), with the asio::post-onto-strand thread-safety pattern
§3 Recipe runner	Driving a PJ through SettingUp → Processing → ProcessComplete by walking the recipe body, with per-step CEID emission
§4 Alarm threshold monitor	Continuous threshold-based alarm logic (chamber pressure, cleaning interval) with set/clear emission
§5 EPT cycling	E116 state transitions driven by PJ state + safety alarms
§6 main()	EquipmentRuntime + register_default_handlers (all 56 GEM handlers in one call) + commands.set_handler for the START behaviour
§7 main()	Loading YAML → validating → composing → running, including the Prometheus exporter on :9090 (§7.3)

Running it

From repo root:

# Validate the configs (this is what your CI should do).
docker compose run --rm builder /app/build/secs_server --validate-config \
    --config /app/examples/pvd_tool/equipment.yaml \
    --state-table /app/data/control_state.yaml \
    --pj-state-table /app/data/process_job_state.yaml \
    --cj-state-table /app/data/control_job_state.yaml

# Start the tool.
docker compose run --rm builder /app/build/pvd_tool \
    /app/examples/pvd_tool/equipment.yaml \
    /app/data/control_state.yaml \
    5000 \
    9090

# In another shell, drive it with the conformance harness or a real host.
docker compose run --rm builder /app/build/secs_conformance \
    --host 127.0.0.1 --port 5000 --device 0
# 47 / 47 checks passed

Or via Docker Compose if you'd rather wire it as a service.

What the host sees

Once a host connects and SELECTs:

1. S1F1 → S1F2 returns MDLN="ACME-PVD-3000", SOFTREV="1.4.2".
2. S1F3 on the 32 SVIDs returns live sensor readings — chamber pressure tracks the simulator's target (default 1e-7 Torr in idle), wafer counter increments per processed PJ, EPT state gauge says Standby.
3. S2F33/F35/F37 binds dynamic event reports; CEIDs 300 / 301 / 310 / 311 fire on real PJ activity.
4. S2F41 RCMD=START kicks the recipe runner: any PJ in WaitingForStart transitions to Processing and the simulator starts tracking the recipe's step targets. Sensor values change in real time. CEID 300 (ProcessStarted) emits, then per-step CEID 310/311, then CEID 301 (ProcessCompleted) on completion.
5. S2F41 RCMD=FAULT sets alarm 4 → S5F1 emitted (if enabled via S5F3 first).
6. S7F19 lists the 3 recipes; S7F5 returns the body (multi-line STEP definitions).
7. S16F11 (PJ create) + S14F9 (CJ create) + S16F27 (CJSTART) drives the full E40/E94 lifecycle.

What's the same as the secs-gem demo server

apps/secs_server.cpp (used by docker compose up server) is the canonical fully-loaded server. This example is structurally a slimmer fork:

• Same Router pattern (gem::Router + router.on(s, f, [...]))
• Same event/alarm emission helpers (deliver_or_spool, emit_event, emit_alarm_set)
• Same control-state-change handler wiring

What this example adds that the demo doesn't:

• Sensor simulator with multi-cadence poll loops. The demo's SVID values stay at their YAML defaults; PVD's drift toward recipe-step targets.
• Recipe runner that parses the recipe body and drives the PJ FSM step-by-step. The demo's RCMD=START just emits the linked CEID; PVD actually walks the recipe.
• Alarm threshold monitor — continuous evaluation of sensor values against ECID setpoints. The demo only fires alarms when RCMD=FAULT is sent.
• EPT cycling — automatic Standby↔Productive↔UnscheduledDowntime based on PJ + alarm state. The demo doesn't cycle EPT.
• Prometheus metrics exporter on a second port. The demo logs but doesn't export.

If you want one of these patterns in your own tool, lift the code from main.cpp directly — each section is independently usable.

What's not here

• Persistence. The demo server's --spool-dir flag is the pattern to copy. Add model->spool.enable_persistence(...) etc. at startup before binding the port. See docs/INTEGRATION.md §5.
• E84 handshake timers. No load-port AMHS wiring; see docs/INTEGRATION.md §4.6 for the E84AsioTimers adapter.
• Real I/O bridges. Sensor values come from a random-walk simulator. A real PVD tool would have a PLC/serial driver module-bridge feeding model->svids.set_value(...) from real hardware.
• Production deployment hardening — docs/SECURITY.md (nftables, stunnel, minisign signing) and docs/INTEGRATION.md §7 (HA pattern).

What you'd change for your tool

1. Replace equipment.yaml with your tool's actual SVIDs, ECIDs, alarms, recipes. Run secs_server --validate-config after every edit.
2. Replace the sensor simulator (pvd::Simulator) with calls into your real hardware driver. Keep the asio::post pattern for cross-thread updates.
3. Replace the recipe runner with your real recipe engine integration. The shape — fire Start, walk steps, fire ProcessComplete — is the contract; the implementation is yours.
4. Replace the alarm threshold monitor with your real alarm sources (sensor interrupts, watchdog timers, hardware fault lines). Same emit_alarm_set / emit_alarm_clear API.
5. Keep most of the Router handler section — those are spec- defined and you'll need them all in production.

That's it. No framework, no DI container, no abstract base classes. ~1,100 lines of vendor code on top of the library.

Cross-references

• docs/INTEGRATION.md — the conceptual tutorial this example concretizes
• docs/ARCHITECTURE.md — how stores compose, how to extend
• docs/BENCHMARKS.md — what the throughput envelope looks like
• docs/SECURITY.md — production hardening configs
• apps/secs_server.cpp — the demo server's fully-loaded Router (every handler PVD inherits + a few more)