lmxopcua/docs/plans/2026-06-25-focas-pdu-v3-30i-b-support.md

FOCAS wire-protocol PDU v3 — finding + support analysis (Makino Pro 5 / FANUC 30i-B)

Date: 2026-06-25 Author: field investigation against a live CNC (first real FOCAS hardware contact) Status: RESOLVED + live-validated on a real 31i-B (10.201.31.5) 2026-06-25 — version gate, timer, PMC range, servo-meter, alarms, probe all fixed and verified live; cnc_rdparam found unsupported on this control (see Resolution). See 2026-06-25-focas-pdu-v3-implementation-plan.md for the per-phase record. Components: ZB.MOM.WW.OtOpcUa.Driver.FOCAS (Wire/FocasWireProtocol.cs, Wire/FocasWireClient.cs)

---

TL;DR

The pure-managed WireFocasClient only implements FOCAS Ethernet wire-protocol PDU version 1 and hard-rejects every other version. A real Makino Pro 5 (FANUC 30i-B) at 10.201.31.5:8193 speaks PDU version 3, so the driver fails the session with BadCommunicationError / "Unsupported FOCAS PDU version 3" and no tag ever produces a value.

A live experiment (relaxing the version gate to accept v3) showed the v3 initiate handshake and the macro-read data framing are already compatible — MACRO:* reads returned correct values from the real machine. PMC and Parameter reads still failed and need per-command v3 work. So v3 support is not a rewrite, but it is also not a one-line version bump if PMC/PARAM/FixedTree are required.

This was the first time the driver has ever been pointed at real FOCAS hardware — the wire implementation was written from strangesast/fwlib + public docs with an explicit "needs Wireshark traces to validate" caveat (see docs/v2/implementation/focas-wire-protocol.md). This finding is those traces.

---

Resolution (2026-06-25 — implemented + live-validated)

A full v3 data-PDU capture (scripts/focas/capture-v3.py, fixtures under tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/Fixtures/v3/) substantially corrected the initial diagnosis — 4 of the 6 "v3 framing failures" were not framing problems at all. The block envelope is byte-identical to v1; only specific payload structs / request-range math / a client-side robustness gap were wrong. Every fix below was re-validated by reading the live 31i-B through the fixed driver.

Surface	Root cause (from the capture)	Fix	Live result
version gate	hard version != 1 reject	accept {1,3} inbound (FocasWireProtocol)	macros + all reads work on v3
cnc_rdtimer	8-byte {minute,msec} payload is little-endian (only decode with an in-range msec)	FocasWireClient.ParseTimer reads LE	cutting = 1,110,700 min / 41,872 ms
pmc_rdpmcrng	request asked for end=start (1 byte) but a Word needs its byte width → 0 values → spurious BadOutOfRange	WireFocasClient.ReadPmcAsync sets end = start + width − 1; decode extracted to ParsePmcRange	R0 = 7873, R100 = 0, status Good
cnc_rdsvmeter	(a) no wire hang — CNC answers fully + promptly; the "hang" was NetworkStream.ReadAsync not aborting a genuinely stalled socket. (b) per-axis LOADELM is 8 bytes, not 12 → 12-byte stride misaligned (→ 655360 garbage); names live in the 0x0089 block	(a) ReadExactlyAsync dispose-on-cancel abort. (b) ParseServoMeters 8-byte stride + name correlation	7 axes X,Y,Z,B,C,AA,AA, aligned values (≈0 idle)
cnc_rdalmmsg2	not broken — empty payload = no active alarms	none (parser already handles empty)	returned active alarm #3080 WRONG PALLET IN MACHINE
cnc_rddynamic2 axis 0	not a driver bug — the FixedTree poll already iterates 1..N; only a direct harness call used 0	contract guard in ReadDynamicAsync (reject axisIndex < 1)	axes 1..N read clean
Test-Connect probe	degraded to Ok=true "TCP reachability only" when FWLIB absent → any TCP listener looked HEALTHY	FocasDriverProbe now runs a real wire session (initiate + cnc_statinfo)	Ok=true vs real CNC, Ok=false vs bare listener

cnc_rdparam — unsupported on this control (blocked)

The one genuine v3 problem. A live matrix of 14 request-framing variants × 4 known-present parameters (8130 / 1320 / 1825 / 3201) — every combination of arg ordering, axis, length, request-class, and extra payload (scripts/focas/param-probe.py) — returned EW_FUNC(1) uniformly. That is not a tweakable-framing bug. 0x000e is also the ignored post-connect setup command, which makes it a doubtful parameter opcode. Either parameter read is genuinely restricted on this control via the wire path, or the v3 command id differs from 0x000e and cannot be recovered without a reference FWLIB Wireshark trace (the long-blocked "Stream C.2"). Parameter support is parked on that reference; the deployed config uses macros, not parameters, so nothing live depends on it.

Open caveats

• Servo-load magnitude/scaling (data / 10^dec; dec read as 10 → idle loads ≈ 0) is inferred from the wire and unconfirmed against the machine's servo-meter screen — confirm at commissioning.
• Timer type→counter mapping: power-on / operating / cycle read 0 while cutting is non-zero on this control. The decode is correct; whether type 0/1/3 map to populated counters here is a CNC-configuration question for commissioning.

Environment

• CNC: Makino Pro 5, FANUC 30i-B control, 10.201.31.5:8193 (ZTag Z-34184). FOCAS Ethernet reachable (TCP 8193 open from both the OtOpcUa host wonder-app-vd03 and a dev laptop over VPN).
• Driver backend: wire (the default and now only real backend — fwlib/ipc were retired in the Wire migration; see FocasDriverFactoryExtensions.BuildClientFactory). FANUC FWLIB is NOT installed on the host, and is not used for reads.
• Deployment using this CNC: see docs/deployments/wonder-app-vd03-makino-z-34184.md.

Symptom

Equipment tags backed by this device never leave OPC UA Bad_WaitingForInitialData (0x80320000), and the FOCAS FixedTree emits no nodes (capability detection against the CNC never succeeds).

Reproduction (driver CLI, straight to the CNC — no OPC UA server involved)

dotnet run --project src/Drivers/Cli/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Cli -- \
  probe -h 10.201.31.5 -s Thirty_i --timeout-ms 6000 --verbose

CNC:        10.201.31.5:8193
Series:     Thirty_i
Health:     Degraded
Last error: Unsupported FOCAS PDU version 3.
R100 →      0x80050000 (BadCommunicationError)

Root cause (exact)

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Wire/FocasWireProtocol.cs

• Line 22: public const ushort Version = 1;
• ReadPduAsync (~line 102) and ReadPdu (~line 125): if (version != Version) throw new FocasWireException($"Unsupported FOCAS PDU version {version}.");

The 10-byte PDU header is A0 A0 A0 A0 magic + u16 version + type byte + direction byte + u16 body length. The client emits version 1 and rejects any response whose version field != 1. The 30i-B answers the initiate with version 3.

What the wire actually shows (captured live, read-only initiate handshake)

Request the driver sends (socket-1 initiate, exactly as today):

a0 a0 a0 a0 00 01 01 01 00 02 00 01
^magic------ ^v=1  ^t ^d ^len  ^sockIdx=1

Response from the real 30i-B:

a0 a0 a0 a0 00 03 01 02 01 68  + 360-byte body
^magic------ ^v=3  ^t ^d ^len=0x0168(360)
body[0..]: 00 08 00 05 00 03 00 20 00 08 00 0a 00 03 00 03 00 0f 00 0f 00 01 00 02 00 01 00 00 00 01 02 00 ...

Key observations:

• The 10-byte header framing is byte-identical to v1 — same magic, same type=0x01 (initiate), same direction=0x02 (response). Only the version field differs (3 vs 1).
• The initiate-response body is 360 bytes (v3 carries a larger capability/version descriptor block; it parses as a run of big-endian u16 words). The current client doesn't deeply parse the initiate body, so its size/shape did not block the handshake once the version gate was relaxed.
• No version negotiation: sending version 3 in our request header produced the identical response — the CNC speaks v3 unconditionally.

(Capture is reproducible with scripts/focas/capture-initiate.py <host>.)

Implemented + validated — accept v3 on inbound PDUs

Shipped change (Wire/FocasWireProtocol.cs): the hard version != Version reject is replaced by a supported-read-version set {1, 3} (SupportedReadVersions + IsSupportedReadVersion). We still emit Version (v1) on requests — the 30i-B accepts v1 request framing — and now accept v1 or v3 on inbound PDUs. Covered by FocasWireProtocolTests.ReadPduAsync_accepts_supported_version (v1 + v3 theory) with the existing v99-rejection test still green; full FOCAS unit suite 218/218.

Validated live against 10.201.31.5 (30i-B) with the change in source — reading several addresses:

Address	Type	Result
MACRO:500	Float64	0.02 — Good (0x0)
MACRO:3901 (parts total)	Float64	0 — Good (0x0)
MACRO:3902 (parts required)	Float64	Good
R100 (PMC R-file)	Int16	0x803C0000 BadOutOfRange
PARAM:1320/0	Int32	0x803D0000 BadNotSupported

Interpretation:

• Initiate handshake + macro command (cnc_rdmacro, cmd path) data framing are already v3-compatible. Macro reads returned correct, plausible values from the real machine. The deployed equipment tags (MACRO:3901/3902) would go Good with nothing more than the version-gate relaxation.
• PMC (pmc_rdpmcrng) and Parameter (cnc_rdparam) reads still fail. Two candidate causes, not yet separated: (a) the v3 response block/struct framing for these specific commands differs from the v1-shaped parser (so the return-code/value lands at the wrong offset → spurious BadOutOfRange / BadNotSupported); or (b) genuine CNC restrictions (PMC path/range, parameter not present). Macro working argues the envelope is fine, so this is per-command struct work, not a framing rewrite.

Status-command validation on v3 (the FixedTree surface) — 2026-06-25

Drove every IFocasClient status call directly against the live control (v3 accepted). Most of the FixedTree lights up on v3. Note: sysinfo reveals the control is actually a 31i (CncType=31, Series G431, MaxAxis 32, 7 axes, MtType MM) — the deployment declared Thirty_i; same family, reads fine.

Call (FOCAS fn)	Result on v3
GetSysInfoAsync (cnc_sysinfo) → Identity	✅ real — CncType 31, Series G431, 7 axes, MtType MM
GetAxisNamesAsync (cnc_rdaxisname)	✅ real — X,Y,Z,B,C,A,A
GetSpindleNamesAsync (cnc_rdspdlname)	✅ real — S1
GetProgramInfoAsync (program/mode)	✅ real — //CNC_MEM/USER/LIBRARY/O1111, Mode 1
ReadDynamicAsync(n) (cnc_rddynamic2)	✅ real for axes 1..N (feed 4200, spindle ~15000, live positions). axis 0 → EW_4 — the call is 1-based; FixedTree must iterate 1..N, not 0
GetTimerAsync(*)	⚠️ misparsed — a running machine shows PowerOn/Operating/Cycle = 0 and Cutting = garbage; the v3 timer struct differs
GetServoLoadsAsync (cnc_rdsvmeter)	❌ hangs — blocks awaiting bytes that never arrive (v3 framing differs) and ignores the cancellation token (poll-loop-stalling robustness bug; the read must honor CT regardless)
ReadAlarmsAsync (cnc_rdalmmsg2)	❓ untested — ServoLoads hung ahead of it; validate once the hang is fixed

Remaining v3 work, now scoped concretely: timer struct; 1-based axis iteration for dynamic; the cnc_rdsvmeter framing + a cancellation-honoring read; and the PMC (pmc_rdpmcrng) + Parameter (cnc_rdparam) struct diffs. Identity / axes / positions / feed / spindle / program-mode already work.

Implementation analysis — what "support PDU v3" actually involves

1. Accept v3 at the framing layer (cheap, validated). — ✅ DONE. Replaced the version != Version hard reject with the supported-set {1, 3}. This alone makes the initiate handshake + all macro reads work on a real 30i-B (validated live; deployed MACRO:3901/3902 read Good). We still emit v1 on requests (the CNC accepts it). If a future command turns out to need the request version echoed, thread the negotiated version from the initiate response onto the connection.
2. Validate each command family against v3 response framing. Capture v3 0x21 data-PDU responses for cnc_rdparam, pmc_rdpmcrng, cnc_statinfo, cnc_rddynamic2, cnc_rdaxisname, and the timer reads (the FixedTree set), and diff the block/struct offsets vs the v1 assumptions in FocasWireModels.cs / the ParseX helpers. Where they differ, add v3 parsing. Capture by extending scripts/focas/capture-initiate.py to complete the handshake and issue one data request per command.
3. FixedTree depends on (2). Identity/Axes/Timers/Program nodes only emit if cnc_sysinfo + cnc_rdaxisname + dynamic/timer reads succeed at discovery — so they come online once cnc_statinfo / cnc_rddynamic2 / timer framing is v3-validated.
4. Don't let the gate lie. Shipping only step 1 makes the driver accept v3 while PMC/PARAM/FixedTree silently misbehave. Either gate macro-only configs as "supported on v3" with the others explicitly flagged, or land steps 1–3 together.

Alternative considered: reinstate an FWLIB-backed client

The official FANUC FWLIB (Fwlib64.dll) handles all protocol versions natively. But the fwlib/ipc backends were deliberately retired in the Wire migration (native Windows component, x86/x64 + STA, and licensing — the exact coupling the managed client removed). Reintroducing it reverses that decision and is heavier than completing v3 in the wire client; recommend only if multiple controls need surfaces the managed client can't reach.

Secondary finding — the Test-Connect / health probe is misleading without FWLIB

FocasDriverProbe Phase 2 (the real cnc_allclibhndl3 FWLIB handshake) catches the FWLIB-absent load failure and degrades to Ok=true ("TCP reachability only"). On a host with no FWLIB (the normal case for the managed wire client), the driver therefore reports HEALTHY off a bare TCP connect — which is exactly how this CNC looked "healthy" while no data flowed. The probe should exercise the wire-client path (open a WireFocasClient session + one sample read) so health reflects real FOCAS reachability, not just an open socket.

Recommended next steps

1. Land step 1 (accept v3) + capture/validate PMC + Parameter + FixedTree command framing (step 2), ideally in one change, tested against 10.201.31.5 while access lasts.
2. Fix the probe to use the wire client so HEALTHY means "FOCAS session + read OK," not "TCP open."
3. Add a real-hardware row to docs/v2/focas-version-matrix.md (currently hardware-free) recording that 30i-B = PDU v3, macro reads validated.