raphael
6aa4427186
A fictional Physical Vapor Deposition tool wired end-to-end.
examples/pvd_tool/ is the template a real customer should fork.
Files:
- equipment.yaml: 32 SVIDs (chamber pressure, temperature, source
power, gas flows, cooling water, wafer counters, recipe step
state, EPT name, 4 load ports), 5 DVIDs, 7 ECIDs (setpoints
+ T_CRA/T_DELAY + cleaning interval + retry count), 17 CEIDs
(control state, alarms, process lifecycle, material movement,
EPT), 12 alarms with realistic categories (safety, error,
warning, attention), 3 multi-step recipes (Al / Ti / Cu),
9 host commands.
- main.cpp (~860 lines): the vendor-side application:
§1 helpers + constants
§2 sensor simulator — 4 sensors at 10 Hz + 1 Hz cadences,
random-walk around step-targeted setpoints, asio::post-on-strand
thread-safety pattern
§3 recipe runner — parses recipe body (STEP NAME duration=120s
power=2500W gas=Argon flow=50sccm), walks each step at 1s
per declared-second, fires step-started/completed CEIDs,
drives PJ FSM through ProcessComplete
§4 alarm threshold monitor — chamber-pressure-over-setpoint and
cleaning-interval logic, continuous evaluation, set/clear
emission gated on alarm-enable
§5 EPT cycler — Standby ↔ Productive ↔ UnscheduledDowntime
based on PJ activity + safety alarms
§6 Prometheus exporter on :9090 (pvd_messages_total,
pvd_chamber_pressure_torr, pvd_spool_depth, pvd_events_total,
pvd_alarm_set_total)
§7 Router handlers — full E30 set (~40 handlers) so a host can
do real work
§8 main() — YAML validation, model construction, server wiring,
periodic gauge updates
- README.md: section-by-section walkthrough, what's the same as
apps/secs_server.cpp, what this adds (simulator + recipe runner
+ alarm monitor + EPT cycler + metrics), what's not here
(persistence + E84 + real I/O), and what to change for your tool.
Verification: 47/47 conformance harness checks PASS against the
PVD tool — same as the demo server.
CMakeLists.txt adds the pvd_tool target.
README's documentation map points at examples/pvd_tool/.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
155 lines
7.0 KiB
Markdown
155 lines
7.0 KiB
Markdown
# 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 (32 SVIDs, 5 DVIDs,
|
|
7 ECIDs, 17 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 Metrics | Prometheus exporter on `:9090` with per-CEID counters and gauge updates |
|
|
| §7 Router handlers | Every SECS/GEM message a host might send to a PVD tool, ~40 handlers in ~200 lines |
|
|
| §8 main() | Loading YAML → validating → composing → running |
|
|
|
|
## Running it
|
|
|
|
From repo root:
|
|
|
|
```bash
|
|
# 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 INTEGRATION.md §5.
|
|
- **E84 handshake timers.** No load-port AMHS wiring; see
|
|
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** — SECURITY.md (nftables,
|
|
stunnel, minisign signing) and 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. ~700 lines of vendor code on top of the library.
|
|
|
|
## Cross-references
|
|
|
|
- [INTEGRATION.md](../../INTEGRATION.md) — the conceptual tutorial
|
|
this example concretizes
|
|
- [ARCHITECTURE.md](../../ARCHITECTURE.md) — how stores compose, how
|
|
to extend
|
|
- [BENCHMARKS.md](../../BENCHMARKS.md) — what the throughput
|
|
envelope looks like
|
|
- [SECURITY.md](../../SECURITY.md) — production hardening configs
|
|
- [apps/secs_server.cpp](../../apps/secs_server.cpp) — the demo
|
|
server's fully-loaded Router (every handler PVD inherits + a
|
|
few more)
|