# FOCAS PDU v3 — implementation plan (finish real 30i/31i-B support)

**Date:** 2026-06-25
**Companion to:** [`2026-06-25-focas-pdu-v3-30i-b-support.md`](2026-06-25-focas-pdu-v3-30i-b-support.md) (finding + live captures + per-command validation) and [`../deployments/wonder-app-vd03-makino-z-34184.md`](../deployments/wonder-app-vd03-makino-z-34184.md) (the deployment this unblocks).
**Goal:** make the managed `WireFocasClient` fully interoperate with a real FANUC 30i/31i-B (FOCAS Ethernet **PDU v3**), then light up the live OPC UA data on `wonder-app-vd03` for the Makino Pro 5 (`Z-34184`, `10.201.31.5`).

## ⏳ Time-boxed asset — capture/validate live FIRST
`10.201.31.5:8193` (real 31i-B) is reachable from the dev box and the wonder host **right now**. Every
per-command v3 framing fix needs a live capture + live re-validation. **Do all captures in Phase 1 while
access lasts**; the parser fixes + unit tests can be finished offline against the captured bytes later.
Tools already in place: `scripts/focas/capture-initiate.py <host>` (initiate only — extend it) and the
throwaway status harness pattern (see the finding doc).

## Current status — DONE (2026-06-25), live-validated on the real 31i-B (`10.201.31.5`)
The Phase-1 capture corrected the diagnosis (4 of 6 "framing failures" were not framing problems).
All tractable phases are implemented + unit-tested (FOCAS suite **234 green**, full solution builds 0
errors) + re-validated live. The full corrected diagnosis + per-surface evidence is in the companion
finding doc's **Resolution** section.

| Phase | Item | State |
|---|---|---|
| 0 | inbound PDU-version gate `{1,3}` | DONE — macros + all status reads work on v3 |
| 1 | capture every v3 data PDU | DONE — 20 fixtures under `tests/.../Fixtures/v3/` |
| 2 | servo "hang" → CT-bound reads | DONE — `ReadExactlyAsync` dispose-on-cancel; servo answers in 0 ms (no real wire hang) |
| 3 | request-version policy | DONE — keep emitting v1 (CNC accepts it); no command needed v3 requests |
| 4 | servo + alarms framing | DONE — servo 8-byte stride + names from 0x0089; alarms already correct (read `#3080` live) |
| 5 | timer v3 struct | DONE — `ParseTimer` little-endian {minute, msec} |
| 6 | dynamic axis iteration | DONE — driver poll already 1-based; added a `ReadDynamicAsync` contract guard |
| 7 | PMC framing | DONE — `end = start + width - 1`; **parameter framing BLOCKED** (EW_FUNC across 14 variants — see finding) |
| 8 | probe truthfulness | DONE — `FocasDriverProbe` runs a real wire session (initiate + cnc_statinfo) |
| 9 | docs + version matrix | DONE — this plan, the finding doc, `FOCAS.md`, `focas-version-matrix.md` |
| 10 | deploy to wonder + e2e | DONE (binary live, driver speaks v3) — but live-tag verify BLOCKED by a separate OtOpcUa data-plane issue (see below) |
| 11 | commit + push | DONE — `feat/focas-pdu-v3` @ `5f0a5286` committed + pushed to gitea |

**Only genuinely open v3 item:** `cnc_rdparam` (EW_FUNC on every framing — needs a reference FWLIB
trace or is restricted on this control). Deferred; the deployed config uses macros, not parameters.

## Phase 10 outcome — v3 binary LIVE, but a separate OtOpcUa data-plane issue blocks tag values
Deployed the Release driver DLL to `E:\ApiInstall\OtOpcUa\` (backup `_focasbak-pre-v3-20260625T164909.dll`),
restarted `OtOpcUaHost` (clean), and re-deployed in the AdminUI (deployment `12e0d528`, Sealed/In-sync).
**`DRIVER STATUS: HEALTHY` now reflects a real FOCAS v3 session** (the rewritten probe does initiate +
`cnc_statinfo`) — i.e. the deployed binary genuinely speaks v3 to the Makino, which was impossible before.

**However**, the live OPC UA equipment tags (`parts-count`/`parts-required` = `MACRO:3901/3902`) still read
`Bad_WaitingForInitialData` via `read` and a 30 s `subscribe`, and a recursive browse shows ONLY the two
UNS-projected macro tags — **no FixedTree (Identity/Axes/Timers/…) nodes** — identical to before the v3 fix,
and unchanged by host-restart / re-deploy / driver-`Restart`. A box-side watch saw no 250 ms-cadence
connection to the CNC (only the periodic probe), so the driver's **data poll loop isn't running** while its
probe loop is. This is a **separate, pre-existing OtOpcUa data-plane / Equipment-projection issue**, not a
FOCAS-protocol problem (the wire client is proven by the healthy real-session probe + exhaustive dev-box
reads). Follow-on: investigate why the driver's DiscoverAsync FixedTree build + equipment-tag value source
don't run/surface on this single fused admin+driver node (poll-group engine / monitored-item sampling /
whether the Equipment projection exposes driver FixedTree auto-nodes at all).

---

## Phase 1 — Capture every v3 data-PDU response (live, do first)
- Extend `scripts/focas/capture-initiate.py` (or add a C# capture mode to `Driver.FOCAS.Cli`) to: run the
  two-socket initiate, then send each `0x21` data request (command IDs in
  `docs/v2/implementation/focas-wire-protocol.md`) and dump the raw v3 response: `cnc_rdtimer`,
  `cnc_rdsvmeter`, `pmc_rdpmcrng` (R100), `cnc_rdparam` (e.g. 1320), `cnc_rdalmmsg2`, `cnc_rddynamic2`
  (axis 1 — a known-good — as the v3 reference layout).
- Save raw bytes as fixtures under `tests/Drivers/.../Fixtures/v3/` for offline unit tests.
- **Acceptance:** raw v3 response bytes captured + checked in for all six commands.

## Phase 2 — Safety: `cnc_rdsvmeter` must never hang
- Root cause: the read blocks waiting for a body length the v3 response never satisfies, and the wait
  doesn't observe the `CancellationToken`. A hang here can wedge the FixedTree poll loop.
- Make the wire read honor the per-operation timeout/CT **regardless of framing** (the socket read path in
  `FocasWireClient` must be CT-bound), so a bad parse fails fast as `BadCommunicationError`/timeout.
- **Acceptance:** `GetServoLoadsAsync` returns or fails within the timeout on the live 31i-B; a unit test
  proves a truncated/oversized body length cancels rather than blocks. **Gating:** FixedTree must not be
  enabled on a v3 control until this lands (capability probe could otherwise hang at init).

## Phase 3 — Decide request-version policy
- We currently emit v1 requests and accept v1/v3 responses; macro + most status reads work that way.
- If any Phase 5–7 command turns out to need v3-framed *requests*, thread the version negotiated from the
  initiate response onto `FocasWireClient` and have `BuildPdu` emit it. Otherwise keep emitting v1.
- **Acceptance:** documented decision; negotiated version plumbed only if a command requires it.

## Phase 4 — Servo load + alarms v3 framing
- Diff captured `cnc_rdsvmeter` / `cnc_rdalmmsg2` bytes vs the v1 struct assumptions in `FocasWireModels.cs`
  + the `ParseServoLoad` / alarm parsers; fix offsets/strides for v3.
- **Acceptance:** servo-load % values are plausible; `ReadAlarmsAsync` returns the real active-alarm set;
  unit tests over the Phase-1 fixtures; live re-validation.

## Phase 5 — Timer v3 struct
- Diff captured `cnc_rdtimer` bytes; fix the timer struct parse (running machine must show non-zero
  PowerOn/Operating; Cutting sane).
- **Acceptance:** all four timers plausible on the live machine; fixture unit test; matches the
  FixedTree `Timers/*` node expectations.

## Phase 6 — Dynamic axis iteration (1-based)
- FixedTree currently probes axis 0 → `EW_4`. Iterate `1..AxesCount` (from `cnc_sysinfo`); never request 0.
- **Acceptance:** every configured axis (per sysinfo `AxesCount`) yields a `FocasDynamicSnapshot`; no `EW_4`.

## Phase 7 — PMC + Parameter v3 framing
- Diff captured `pmc_rdpmcrng` (R100) + `cnc_rdparam` (1320) bytes vs the v1 `IODBPMC0` / `IODBPSD` shapes;
  fix v3 parsing. Confirm whether the failures are framing or genuine CNC restriction (PMC path / param
  presence) — macro working proves the envelope is fine, so suspect struct offsets first.
- **Acceptance:** `R100` reads a plausible value (or a *correct* status if genuinely restricted); a known
  parameter reads its value; fixture unit tests; live re-validation.

## Phase 8 — Probe truthfulness
- `FocasDriverProbe` Phase-2 degrades to `Ok=true` ("TCP only") when FWLIB is absent → HEALTHY off a bare
  socket. Replace with a wire-client probe: open `WireFocasClient` + one sample read (e.g. sysinfo). Keep
  the TCP preflight for fast rejection.
- **Acceptance:** probe reports unhealthy when the CNC TCP-accepts but FOCAS reads fail; HEALTHY only on a
  real session + read.

## Phase 9 — Docs + version matrix
- Add a real-hardware row to `docs/v2/focas-version-matrix.md`: 30i/31i-B → PDU v3; record which command
  families are validated. Update `docs/drivers/FOCAS.md` + this plan's status as phases land.

## Phase 10 — Deploy to wonder + end-to-end verify
- Optional: set the device series to `ThirtyOne_i` (sysinfo says CncType 31; capability ranges identical to
  `Thirty_i`, so cosmetic).
- Rebuild a self-contained win-x64 publish of `ZB.MOM.WW.OtOpcUa.Host` (or swap just
  `ZB.MOM.WW.OtOpcUa.Driver.FOCAS.dll`) into `E:\ApiInstall\OtOpcUa\` on `wonder-app-vd03`, preserving
  `appsettings*.json` + `data\`; restart `OtOpcUaHost`. (Access: servecli `:2222`, key
  `~/.ssh/servecli_wonder` — see the deployment doc + memory.)
- **Re-run a deployment** in the AdminUI afterward — FixedTree nodes are emitted at `DiscoverAsync`, so the
  address space must be rebuilt to surface them.
- **Acceptance (via the OtOpcUa CLI client → `opc.tcp://wonder-app-vd03.zmr.zimmer.com:4840/OtOpcUa`):**
  `ns=2;s=EQ-3686c0272279/parts-count` + `/parts-required` read **Good**; FixedTree Identity/Axes/Program
  nodes present with live values; (timers/servo-load good once Phases 4–5 land).

## Phase 11 — Commit + push
- Commit source + tests + docs on a branch `feat/focas-pdu-v3` (keep it separate from the unrelated
  pre-existing local edits in the tree). Push to gitea per the repo's flow. The Akka-roles host fix is a
  separate concern (see deployment doc) — note it but it's a box config change, not repo code.

---

## Test strategy
- **Offline (CI-safe):** unit tests over the Phase-1 captured v3 byte fixtures for every parser
  (`FocasWireProtocolTests` + new `FocasWireModels`/parse tests). Keep the docker mock (v1) green.
- **Live (env-gated):** the `Driver.FOCAS.Cli` (`probe`/`read`) + the status harness, against
  `10.201.31.5`. Gate behind an env var / `[Trait]` so CI without a CNC skips.

## Sequencing notes
- Phase 1 (capture) unblocks 4/5/7. Phase 2 (servo-load safety) gates enabling FixedTree on v3. Phases 4–7
  are independent and parallelizable once captures exist. Phase 10 depends on whichever surfaces you want
  live (macro tags already work after Phase 0, so a minimal deploy could happen now; full FixedTree wants
  Phases 2/5/6).
- **Keep emitting v1 requests** unless Phase 3 proves otherwise — it's validated and minimal.

## File map
- `src/Drivers/.../Wire/FocasWireProtocol.cs` — version gate (done), request-version policy (Phase 3).
- `src/Drivers/.../Wire/FocasWireClient.cs` — CT-bound reads (Phase 2), per-command requests.
- `src/Drivers/.../Wire/FocasWireModels.cs` + parse helpers — per-command v3 struct fixes (Phases 4–7).
- `src/Drivers/.../FocasDriver.cs` — FixedTree axis iteration (Phase 6), FixedTree enable gating (Phase 2).
- `src/Drivers/.../FocasDriverProbe.cs` — wire-client probe (Phase 8).
- `scripts/focas/capture-initiate.py` — extend to data PDUs (Phase 1).
- `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/` + `Fixtures/v3/` — fixtures + parser tests.
- `docs/v2/focas-version-matrix.md`, `docs/drivers/FOCAS.md` — docs (Phase 9).
