raphael
b031f057af
Audit pass over the public-facing surface so a customer can read it end-to-end without tripping on stale numbers or self-contradictions. README + docs accuracy: - Test counts 426 → 445, assertions 2 557 → 2 753 (verified via doctest run); E5 row was missing test_e5_kat (19 cases) - Interop checks 24 → 31, COMPLIANCE.md message count 149 → 164, COMPLIANCE.md "291 cases / 1515 assertions" → 445 / 2 753 - README "60+ test IDs" for MES_INTEROP → actual 59 - PVD example counts: 32 SVIDs/17 CEIDs → 29/21, "~40 handlers in ~200 lines" → 51 in ~460, "~700 lines" → ~1,100; main.cpp header table-of-contents resynced with the actual 7 sections Out-of-scope honesty (COMPLIANCE.md §8 + FAQ.md): - Removed HSMS-GS (was both ✅ implemented in §1 and "out of scope" in §8; INTEGRATION.md §7 documents using it) - Removed multi-block SECS-I (split_message/assemble_message exist with 4 dedicated tests) - Added serial-port wiring as the genuine open ⬜ item — FSM is tested end-to-end over TCP; only the asio serial_port glue is deferred - COMPLIANCE.md intro now lists E42 and notes "E37 (SS + GS)" README restructure: - Moved the 8-command proof table and per-standard test-coverage table to a new PROOFS.md (72 lines) - README now leads with what / Quick start / Documentation map, then a one-paragraph "How it's proved" linking to PROOFS.md - Updated cross-refs in FAQ.md, GLOSSARY.md, VERIFICATION.md, and interop/README.md to point at PROOFS.md CI fix — tshark-dissector job: - interop/tshark_validate.sh hardcoded /app/build/secs_server etc. which only works inside the docker image. Now derives ROOT from the script's own location and accepts BUILD/SERVER/CLIENT/DATA env overrides, so CI can run it from the workspace dir - Verified still passes in docker (69 frames, 0 malformed) .gitignore: - Added build-fuzz/ and build-tsan/ (were showing as untracked) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
154 lines
6.9 KiB
Markdown
154 lines
6.9 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 (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 Router handlers | Every SECS/GEM message a host might send to a PVD tool, 51 handlers in ~460 lines |
|
|
| §7 main() | Loading YAML → validating → composing → running, including the Prometheus exporter on `:9090` (§7.3) |
|
|
|
|
## 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. ~1,100 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)
|