Joseph Doherty
5f0a52864c
First real FOCAS hardware contact (Makino Pro 5 / 31i-B @ 10.201.31.5). A full
v3 data-PDU capture corrected the initial diagnosis: the v3 block envelope is
identical to v1, so only specific payload structs / request math / one client
robustness gap were wrong — not "framing rewrites".
Fixes (all re-validated live through the fixed driver):
- version gate: accept inbound PDU {1,3}, keep emitting v1 (FocasWireProtocol).
- cnc_rdtimer: 8-byte {minute,msec} payload is little-endian (ParseTimer) — the
only decode with an in-range msec field.
- pmc_rdpmcrng: request range widened to the data-type byte width
(end = start + width - 1) so a Word/Long isn't truncated to 0 values
(was spurious BadOutOfRange); decode extracted to ParsePmcRange.
- cnc_rdsvmeter: per-axis LOADELM is 8 bytes (not 12) and names come from the
0x0089 block — ParseServoMeters fixes the misaligned 655360 garbage. Also the
"hang" was NetworkStream.ReadAsync not aborting a stalled socket: ReadExactlyAsync
now disposes the stream on cancellation so a stalled peer can't wedge a poll loop.
- cnc_rddynamic2: contract guard rejecting axis < 1 (driver poll already 1-based).
- FocasDriverProbe: run a real wire session (initiate + cnc_statinfo) instead of
degrading to Ok=true "TCP reachability only" when FWLIB is absent — a bare TCP
listener no longer reports HEALTHY.
cnc_rdparam (0x000e) is unsupported on this control — EW_FUNC across 14
request-framing variants x 4 known-present params; needs a reference FWLIB trace
or is restricted. Deferred (deployed config uses macros, not parameters).
Tests: FOCAS suite 234 green (+16), full solution builds 0 errors. Raw v3
captures checked in under tests/.../Fixtures/v3/. Capture tools under scripts/focas/.
Docs: docs/plans/2026-06-25-focas-pdu-v3-{30i-b-support,implementation-plan}.md,
docs/drivers/FOCAS.md, docs/v2/focas-version-matrix.md,
docs/deployments/wonder-app-vd03-makino-z-34184.md.
168 lines
7.5 KiB
Markdown
168 lines
7.5 KiB
Markdown
# FOCAS version / capability matrix
|
||
|
||
Authoritative source for the per-CNC-series ranges that
|
||
[`FocasCapabilityMatrix`](../../src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs)
|
||
enforces at driver init time. Every row cites the Fanuc FOCAS Developer
|
||
Kit function whose documented input range determines the ceiling.
|
||
|
||
**Why this exists** — we have no FOCAS hardware on the bench and no
|
||
working simulator. FWLIB (Fwlib64, or Fwlib32 on legacy deployments) returns `EW_NUMBER` / `EW_PARAM` when you
|
||
hand it an address outside the controller's supported range; the
|
||
driver would map that to a per-read `BadOutOfRange` at steady state.
|
||
Catching at `InitializeAsync` with this matrix surfaces operator
|
||
typos + mismatched series declarations as config errors before any
|
||
session is opened, which is the only feedback loop available without
|
||
a live CNC to read against.
|
||
|
||
**Who declares the series** — `FocasDeviceOptions.Series` in
|
||
`appsettings.json`. Defaults to `Unknown`, which is permissive — every
|
||
address passes validation. Pre-matrix configs don't break on upgrade.
|
||
|
||
---
|
||
|
||
## Series covered
|
||
|
||
| Enum value | Controller family | Typical era |
|
||
| --- | --- | --- |
|
||
| `Unknown` | (legacy / not declared) | permissive fallback |
|
||
| `Sixteen_i` | 16i / 18i / 21i | 1997-2008 |
|
||
| `Zero_i_D` | 0i-D | 2008-2013 |
|
||
| `Zero_i_F` | 0i-F | 2013-present, general-purpose |
|
||
| `Zero_i_MF` | 0i-MF | 0i-F lathe variant |
|
||
| `Zero_i_TF` | 0i-TF | 0i-F turning variant |
|
||
| `Thirty_i` | 30i-A / 30i-B | 2007-present, high-end |
|
||
| `ThirtyOne_i` | 31i-A / 31i-B | 30i simpler variant |
|
||
| `ThirtyTwo_i` | 32i-A / 32i-B | 30i compact |
|
||
| `PowerMotion_i` | Power Motion i-A / i-MODEL A | motion-only controller |
|
||
|
||
## Macro variable range (`cnc_rdmacro` / `cnc_wrmacro`)
|
||
|
||
Common macros `1-33` + `100-199` + `500-999` are universal across all
|
||
series. Extended macros (`#10000+`) exist only on higher-end series.
|
||
The numbers below reflect the extended ceiling per series per the
|
||
DevKit range tables.
|
||
|
||
| Series | Min | Max | Notes |
|
||
| --- | ---: | ---: | --- |
|
||
| `Sixteen_i` | 0 | 999 | legacy ceiling — no extended |
|
||
| `Zero_i_D` | 0 | 999 | 0i-D still at legacy ceiling |
|
||
| `Zero_i_F` / `Zero_i_MF` / `Zero_i_TF` | 0 | 9999 | extended added on 0i-F |
|
||
| `Thirty_i` / `ThirtyOne_i` / `ThirtyTwo_i` | 0 | 99999 | full extended set |
|
||
| `PowerMotion_i` | 0 | 999 | atypical — limited macro coverage |
|
||
|
||
## Parameter range (`cnc_rdparam` / `cnc_wrparam`)
|
||
|
||
| Series | Min | Max |
|
||
| --- | ---: | ---: |
|
||
| `Sixteen_i` | 0 | 9999 |
|
||
| `Zero_i_D` / `Zero_i_F` / `Zero_i_MF` / `Zero_i_TF` | 0 | 14999 |
|
||
| `Thirty_i` / `ThirtyOne_i` / `ThirtyTwo_i` | 0 | 29999 |
|
||
| `PowerMotion_i` | 0 | 29999 |
|
||
|
||
## PMC letters (`pmc_rdpmcrng` / `pmc_wrpmcrng`)
|
||
|
||
Addresses are letter + number (e.g. `R100`, `F50.3`). Legacy
|
||
controllers omit the `F`/`G` signal groups that 30i-family ladder
|
||
programs use, and only the 30i-family exposes `K` (keep-relay) +
|
||
`T` (timer).
|
||
|
||
| Letter | 16i | 0i-D | 0i-F family | 30i family | Power Motion-i |
|
||
| --- | :-: | :-: | :-: | :-: | :-: |
|
||
| `X` | yes | yes | yes | yes | yes |
|
||
| `Y` | yes | yes | yes | yes | yes |
|
||
| `R` | yes | yes | yes | yes | yes |
|
||
| `D` | yes | yes | yes | yes | yes |
|
||
| `E` | — | yes | yes | yes | — |
|
||
| `A` | — | yes | yes | yes | — |
|
||
| `F` | — | — | yes | yes | — |
|
||
| `G` | — | — | yes | yes | — |
|
||
| `M` | — | — | yes | yes | — |
|
||
| `C` | — | — | yes | yes | — |
|
||
| `K` | — | — | — | yes | — |
|
||
| `T` | — | — | — | yes | — |
|
||
|
||
Letter match is case-insensitive. `FocasAddress.PmcLetter` is carried
|
||
as a string (not char) so the matrix can do ordinal-ignore-case
|
||
comparison.
|
||
|
||
## PMC address-number ceiling
|
||
|
||
PMC addresses are byte-addressed on read + bit-addressed on write;
|
||
`FocasAddress` carries the bit index separately, so these are byte
|
||
ceilings.
|
||
|
||
| Series | Max byte | Notes |
|
||
| --- | ---: | --- |
|
||
| `Sixteen_i` | 999 | legacy |
|
||
| `Zero_i_D` | 1999 | doubled since 16i |
|
||
| `Zero_i_F` family | 9999 | |
|
||
| `Thirty_i` family | 59999 | highest density |
|
||
| `PowerMotion_i` | 1999 | |
|
||
|
||
## Error surface
|
||
|
||
When a tag fails validation, `FocasDriver.InitializeAsync` throws
|
||
`InvalidOperationException` with a message of the form:
|
||
|
||
```
|
||
FOCAS tag '<name>' (<address>) rejected by capability matrix: <reason>
|
||
```
|
||
|
||
`<reason>` is the verbatim string from `FocasCapabilityMatrix.Validate`
|
||
and always names the series + the documented limit so the operator
|
||
can either raise the limit (if wrong) or correct the CNC series they
|
||
declared (if mismatched). Sample:
|
||
|
||
```
|
||
FOCAS tag 'X_axis_macro_ext' (MACRO:50000) rejected by capability
|
||
matrix: Macro variable #50000 is outside the documented range
|
||
[0, 9999] for Zero_i_F.
|
||
```
|
||
|
||
## How this matrix stays honest
|
||
|
||
- Every row is covered by a parameterized test in
|
||
[`FocasCapabilityMatrixTests.cs`](../../tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasCapabilityMatrixTests.cs)
|
||
— 46 cases across macro / parameter / PMC-letter / PMC-number
|
||
boundaries + unknown-series permissiveness + rejection-message
|
||
content + case-insensitivity.
|
||
- Widening or narrowing a range in the matrix without updating this
|
||
doc will fail a test, because the theories cite the specific row
|
||
they reflect in their `InlineData`.
|
||
- The matrix is not comprehensive — it encodes only the subset of
|
||
FOCAS surface the driver currently exposes (Macro / Parameter /
|
||
PMC). When the driver gains a new capability (e.g. tool management,
|
||
alarm history), add its series-specific range tables here + matching
|
||
tests at the same time.
|
||
|
||
## Follow-up
|
||
|
||
This validation closes the cheap half of the FOCAS hardware-free
|
||
stability gap — config errors now fail at load instead of per-read.
|
||
The expensive half is Tier-C process isolation so that a crashing
|
||
`Fwlib64.dll` doesn't take the main OPC UA server down with it. See
|
||
[`docs/v2/implementation/focas-isolation-plan.md`](implementation/focas-isolation-plan.md)
|
||
for that plan (task #220).
|
||
|
||
## Real-hardware validation (first live FOCAS contact)
|
||
|
||
**2026-06-25 — FANUC 31i-B (Makino Pro 5), `10.201.31.5:8193`.** The first time the managed wire
|
||
client met real FOCAS hardware. The control answers **PDU version 3**; the 10-byte header framing and
|
||
response block envelope are byte-identical to v1 (only the version field differs). `cnc_sysinfo`
|
||
reports CncType 31, Series `G431`, 7 axes (X Y Z B C A A), MtType MM.
|
||
|
||
| Command family | v3 result | Notes |
|
||
| --- | --- | --- |
|
||
| `cnc_sysinfo`, `cnc_rdaxisname`, `cnc_rdspdlname` | ✅ validated | identity / axis / spindle names |
|
||
| `cnc_rddynamic2` (positions, feed, spindle, program/seq) | ✅ validated | 1-based axis iteration; program O-number reads via big-endian |
|
||
| `cnc_rdopmode`, `cnc_exeprgname2` | ✅ validated | mode + executing program |
|
||
| `cnc_rdmacro` | ✅ validated | deployed `MACRO:3901/3902` tags read Good |
|
||
| `cnc_rdtimer` | ✅ validated | 8-byte {minute, msec} payload is **little-endian** (unlike the big-endian envelope) |
|
||
| `pmc_rdpmcrng` | ✅ validated | request range must be widened to the data-type byte width (`end = start + width - 1`) |
|
||
| `cnc_rdsvmeter` | ✅ validated | per-axis LOADELM is **8 bytes**, not 12; names come from the 0x0089 block; load *scaling* unconfirmed |
|
||
| `cnc_rdalmmsg2` | ✅ validated | read a live active alarm (`#3080`) |
|
||
| `cnc_rdparam` | ❌ **unsupported** | `EW_FUNC` across 14 request-framing variants × 4 known-present params — likely wrong v3 command id (`0x000e`) or restricted on this control; needs a reference FWLIB trace |
|
||
|
||
Full finding + captured wire bytes + the fix per surface:
|
||
[`../plans/2026-06-25-focas-pdu-v3-30i-b-support.md`](../plans/2026-06-25-focas-pdu-v3-30i-b-support.md).
|