lmxopcua/docs/v2/implementation/focas-simulator-plan.md

# FOCAS Docker simulator — implementation plan

> **Status**: **IN PROGRESS** 2026-04-23. **Streams A + B shipped.** Stream C (real Fwlib64 wire compat) + Stream D (e2e + docs) still open — both require a Windows rig with licensed Fwlib64.dll + captured Wireshark traces. Stream B shipped the full architectural scaffold (Docker image, 9 per-series compose profiles, asyncio TCP server, handler dispatch, profile-driven range enforcement, local validation harness) — exercised end-to-end against both `thirtyone_i` and `powermotion_i` profiles.

## Goal

Close the one remaining FOCAS gap (`#222` follow-up — "wire-level live-boot against real hardware") with a hardware-free fixture that:

1. Runs in Docker, matches the per-driver fixture pattern (`docker compose up -d` in the test project).
2. Exposes the FOCAS TCP port (`8193` by default) to the host.
3. Speaks enough of the FOCAS wire protocol that **a Windows test rig running our unmodified `Driver.FOCAS.Host` + licensed `Fwlib64.dll` can open a session and exercise the 9 FWLIB functions the driver actually uses.**
4. Supports **version profiles** — one container per Fanuc series (0i-D, 0i-F, 30i, 31i, 32i, PowerMotion-i) — so driver-side range validation, error-code mapping, and per-series quirks get exercised against a server that actually behaves differently per series.
5. Plugs into the existing e2e infrastructure (`scripts/e2e/test-focas.ps1` loses the `FOCAS_TRUST_WIRE=1` gate when the fixture is up).

## Non-goals

- **Not a full FOCAS emulator.** Fanuc's FOCAS spec is closed; faithfully reproducing every function across every controller model would be a years-long project. We implement the narrow subset the driver uses (see §Protocol surface).
- **Not a CNC behavioural model.** We return plausible values for PMC/param/macro reads; we do NOT simulate axis motion, program execution, or alarm generation. The mock exists to exercise the driver's marshalling + IPC + status-code paths, not to prove the CNC behaves correctly.
- **Not a replacement for a bench CNC.** A physical controller still catches timing-dependent bugs (Fwlib-internal thread-pool exhaustion, handle-recycle pathologies, vendor-firmware quirks) that a mock can't reproduce. Mock covers ~80% of value; real-hardware smoke stays as a final gate.

## Constraint that shapes the design

`Fwlib64.dll` is a proprietary closed-source library that speaks FOCAS to the CNC. **Our driver never touches raw TCP** — it calls `cnc_allclibhndl3` / `pmc_rdpmcrng` / etc. and Fwlib encodes the wire frames internally.

This means the mock has two possible architectures:

| Option | Where the mock lives | Exercises Fwlib? |
|---|---|---|
| **A. IPC-layer fake** (already shipped as `FakeFocasBackend`) | Between `FwlibFrameHandler` and the FWLIB call | ❌ No — bypasses Fwlib entirely |
| **B. TCP wire mock** (this plan) | Listens on port 8193; Fwlib connects to it | ✅ Yes — Fwlib encodes real frames |

Option B is the only one that validates the driver's actual production wire path (driver → Host → `FwlibFocasClient` → `Fwlib64.dll` → TCP → mock).

**Prerequisite reading** the implementer needs before starting Option B:
- `strangesast/fwlib` on GitHub — reverse-engineered FOCAS2 Linux client, has frame-format notes
- `GalvinGao/opcua-server-fanuc` — another OSS FOCAS client with wire-format traces
- `jdegre/focas-python` (if it still exists) — previous Python FOCAS stub, starting point
- Our own `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FwlibNative.cs` — the 9-function surface we need to satisfy

## Protocol surface (what the mock must speak)

From `FwlibNative.cs`, our driver makes exactly 9 FWLIB calls:

| FWLIB function | What it does | Wire complexity |
|---|---|---|
| `cnc_allclibhndl3` | Open Ethernet handle (connect) | **High** — initial handshake, version negotiation, session state |
| `cnc_freelibhndl` | Close handle | Low |
| `pmc_rdpmcrng` | PMC range read (byte/word/long + optional bit) | **Medium** — 40-byte buffer with type-dependent layout |
| `pmc_wrpmcrng` | PMC range write | **Medium** — same buffer shape inverted |
| `cnc_rdparam` | Parameter read (axis-aware) | Medium — 32-byte buffer |
| `cnc_wrparam` | Parameter write | Medium |
| `cnc_rdmacro` | Macro variable read (value + decimal-point count) | Low |
| `cnc_wrmacro` | Macro variable write | Low |
| `cnc_statinfo` | Status info (for probe) | Low — fixed-shape response |

**Coverage target**: all 9 functions return plausible responses for the address ranges declared in each series profile. Out-of-range addresses return `EW_NUMBER` / `EW_PARAM`. Unknown PMC letters return `EW_DATA`. Session state (handle validity, unknown handle detection) is enforced.

## Version profiles

The driver has `FocasCncSeries` + `FocasCapabilityMatrix` already — we mirror that matrix into JSON profiles the mock loads at start:

```
fixture/
├── Dockerfile
├── requirements.txt
├── server/
│   ├── focas_server.py          # asyncio TCP server + frame parser
│   ├── handlers/
│   │   ├── allclibhndl3.py
│   │   ├── pmc.py
│   │   ├── param.py
│   │   ├── macro.py
│   │   └── status.py
│   ├── state.py                 # in-memory "CNC" state
│   └── frames.py                # FOCAS frame encode/decode
└── profiles/
    ├── zero_i_d.json
    ├── zero_i_f.json
    ├── zero_i_mf.json
    ├── zero_i_tf.json
    ├── sixteen_i.json
    ├── thirty_i.json
    ├── thirtyone_i.json
    ├── thirtytwo_i.json
    └── powermotion_i.json
```

Each profile captures:

```json
{
    "series": "ThirtyOne_i",
    "api_version": "0x30",
    "pmc_ranges": {
        "X": [0, 127], "Y": [0, 127], "F": [0, 767], "G": [0, 767],
        "R": [0, 1499], "D": [0, 2999], "C": [0, 199], "K": [0, 31],
        "A": [0, 24], "T": [0, 79], "E": [0, 9999]
    },
    "param_ranges": [[1000, 9999], [10000, 15999]],
    "macro_range": [100, 999],
    "extended_macros": false,
    "axes": 3,
    "quirks": {
        "crash_after_handle_cycles": null,
        "edit_mode_rejects_connection": false,
        "allclibhndl3_blocks_during_alarm": false,
        "param_bit_index_max": 7
    },
    "alarm_default": false,
    "emergency_default": false
}
```

**Differences that actually matter** for driver coverage:

| Series | Meaningful difference vs baseline |
|---|---|
| 0i-D / 0i-F / 0i-MF / 0i-TF | PMC range narrower; no E-relay; macro range `100-999` strict |
| 16i | Older Fwlib version; `cnc_allclibhndl3` extra-slow on first connect (artificial delay in mock) |
| 30i | Full PMC range; extended macros (`#10000+`) supported |
| 31i / 32i | 5-axis; larger parameter ranges |
| PowerMotion-i | No PMC `T` timer; motion-only controller quirks |

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│  Windows test rig (net10.0 x64)                                 │
│                                                                 │
│  FocasDriver ──► FwlibFocasClient ──► Fwlib64.dll ──► TCP ──┐   │
│                       (real P/Invoke)                       │   │
└─────────────────────────────────────────────────────────────┼───┘
                                                              │
                              port 8193                       │
                                                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Docker container: otopcua-focas-sim-{series}                   │
│                                                                 │
│  Python asyncio TCP server                                      │
│    ├─ frames.py: parse + encode FOCAS frames                    │
│    ├─ handlers/: one module per FWLIB function                  │
│    ├─ state.py: per-session handle registry + simulated memory  │
│    └─ profiles/{series}.json: range + quirk table loaded at     │
│                               boot via env var OTOPCUA_FOCAS_   │
│                               PROFILE=thirtyone_i               │
└─────────────────────────────────────────────────────────────────┘
```

Python choice rationale: the existing OSS FOCAS implementations are Python-first; asyncio's `StreamReader`/`StreamWriter` maps cleanly to FOCAS's length-prefixed frame model; one Dockerfile covers every profile because profile-switching is an env-var.

`docker-compose.yml` exposes one service per profile as a `--profile`:

```yaml
services:
  focas-thirtyone:
    profiles: ["thirtyone"]
    image: otopcua-focas-sim:latest
    environment: { OTOPCUA_FOCAS_PROFILE: "thirtyone_i" }
    ports: ["8193:8193"]

  focas-zerod:
    profiles: ["zerod"]
    image: otopcua-focas-sim:latest
    environment: { OTOPCUA_FOCAS_PROFILE: "zero_i_d" }
    ports: ["8193:8193"]
  # ... one per supported series ...
```

Users pick a profile with `docker compose --profile thirtyone up -d`. Only one profile runs at a time (port collision on 8193) — matching the other driver fixtures' single-image pattern.

## Delivery plan — three streams

### Stream A — Version-aware fake backend (C#, 2-3 days) — ✅ **SHIPPED 2026-04-23**

**What landed**:

- `FakeFocasBackend` gained a second ctor `(FocasCncSeries series, FakeFocasBackendQuirks? quirks)`; default ctor preserves the pre-Stream-A permissive behaviour.
- `ValidateAddress` delegates to the existing `FocasCapabilityMatrix.Validate` so mock + driver share one source of truth. Out-of-range reads/writes/PMC-bit-writes return `BadOutOfRange` (0x803C0000 — matching what the real driver maps `EW_NUMBER`/`EW_PARAM` to).
- `FakeFocasBackendQuirks` record carries four opt-in quirks: `EditModeRejectsConnection`, `CrashAfterHandleCycles`, `SlowFirstConnectDelay`, `EmergencyAtStartup`.
- `Program.cs` reads `OTOPCUA_FOCAS_SERIES` (case-insensitive FocasCncSeries enum value) + `OTOPCUA_FOCAS_QUIRKS` (comma-separated token list: `EditMode`, `Emergency`, `SlowFirstConnect[=ms]`, `CrashAfterCycles=N`). Unknown tokens log-and-ignore. Values surface in Host log at startup.
- 19 new tests in `FakeFocasBackendSeriesTests.cs` covering: Unknown-permissive baseline, Zero_i_D macro rejection, ThirtyOne_i extended-macro acceptance, PowerMotion_i T-timer rejection, Write+PmcBitWrite parallel rejection, all four quirks, + 8 theory cases for the env-var parser.

**Deliverable shipped**:
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Backend/FakeFocasBackend.cs` — extended
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Program.cs` — `BuildFakeBackend` local fn + `ParseFakeQuirks` helper
- `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Tests/FakeFocasBackendSeriesTests.cs` — new, 19 tests
- 38/38 Host tests green post-Stream-A.

### Stream B — Python FOCAS TCP server (scaffold) — ✅ **SHIPPED 2026-04-23**

**What landed** under `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/Docker/`:

- `Dockerfile` — Python 3.12-slim image; stdlib-only, no external deps
- `docker-compose.yml` — 9 `--profile` entries, one per Fanuc series (`thirtyone`, `thirtytwo`, `thirty`, `sixteen`, `zerod`, `zerof`, `zeromf`, `zerotf`, `powermotion`). All share one image + one port (8193).
- `server/focas_server.py` — asyncio entry point, per-connection session loop, graceful-shutdown signal handling
- `server/frames.py` — length-prefixed frame codec (scaffold — see Stream C note below)
- `server/state.py` — per-session handle registry + in-memory PMC/param/macro dictionaries
- `server/profile.py` — JSON profile loader
- `server/handlers/` — one module per FWLIB function (9 total): open/close, PMC read/write, param read/write, macro read/write, statinfo. Profile-driven range validation; error responses use a `FLAG_ERROR` bit on the response header.
- `profiles/*.json` — 9 series profiles mirroring `FocasCapabilityMatrix`. Quirks (`slow_first_connect_ms`, `alarm_default`, `emergency_default`, `crash_after_handle_cycles`, `edit_mode_rejects_connection`) declared per profile.
- `validate_harness.py` — scaffold-protocol TCP client that opens a session, round-trips a macro, triggers range-rejection, asserts the expected error reasons surface.
- `README.md` — operator-facing usage + Stream C next-steps checklist.

**Exit criterion met**: validated end-to-end against two profiles (`thirtyone_i`, `powermotion_i`) via the local harness. Session handshake → statinfo → macro round-trip → out-of-range rejection → PMC round-trip → bad-letter rejection → clean close — all PASS. Profile-switching confirmed working: 31i API 0x0030 → PowerMotion 0x0040, macro range [0,99999]→[0,999], letter set {A,C,D,E,F,G,K,M,R,T,X,Y}→{D,R,X,Y}.

**⚠️ The wire *framing* is a scaffold — NOT Fwlib64-compatible yet.** `server/frames.py` uses a plausible length-prefixed framing (big-endian header: uint32 length, uint16 function_id, uint16 flags) that satisfies the harness but has never been validated against the real Fanuc DLL. Stream C is the iterative refinement cycle where a Windows rig drives that convergence.

**The response payload shapes inside those frames ARE authoritative** (refined 2026-04-23 after `fwlib32.h` review):
- `ODBM` (macro read) = 10 bytes: `short datano, short dummy, int32 mcr_val, short dec_val`
- `ODBST` (statinfo) = 18 bytes: 9 × `short` (dummy/tmmode/aut/run/motion/mstb/emergency/alarm/edit)
- `IODBPSD` (param read) = 36 bytes: `short datano, short type, bytes[32]` (union = 8 axes × 4 bytes)
- `IODBPMC` (PMC range read) = 48 bytes: `short type_a, short type_d, uint16 datano_s, uint16 datano_e, bytes[40]`

Validate harness asserts exact byte sizes + header field round-trip. When Stream C's Wireshark traces arrive, the payload layer should already match — only framing needs iteration.

See [`focas-wire-protocol.md`](focas-wire-protocol.md) for the authoritative-vs-guessed breakdown.

**C# integration test scaffold** also shipped (`tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/`) — `FocasSimFixture` probes port 8193 + skips when the container's down; three smoke tests pass against a running container (TCP reachability, clean connect-close, profile parsing). A `Series/WireCompatGatedTests.cs` skeleton gates Fwlib64-dependent tests behind `OTOPCUA_FOCAS_SIM_WIRE_COMPAT=1`, ready for Stream C activation.

### Stream C — FWLIB compat + version profiles (2-3 weeks) — **blocked on Windows rig + Wireshark traces**

See `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/Docker/README.md` §"Stream C — what's required to reach wire compatibility" for the concrete implementer checklist.

**Goal**: real Fwlib64.dll running on a Windows test rig can open a session against the mock and round-trip the 9 FWLIB calls our driver makes.

Sub-tasks:

1. **Handshake** (`handlers/allclibhndl3.py`) — the hardest piece. FOCAS session open negotiates protocol version + controller type. Incorrect negotiation → Fwlib disconnects. Start from `strangesast/fwlib`'s handshake trace.
2. **PMC read/write** (`handlers/pmc.py`) — 40-byte buffer with type-dependent layout. Must match `FwlibNative.IODBPMC` struct layout exactly. Implement per-profile range checks.
3. **Parameter read/write** (`handlers/param.py`) — 32-byte axis-aware buffer. Similar to PMC but simpler (no sub-address bit indexing beyond `param_bit_index_max`).
4. **Macro read/write** (`handlers/macro.py`) — straightforward; value + decimal-point count as `ODBM`.
5. **Status info** (`handlers/status.py`) — fixed `ODBST` shape; profile declares defaults for `Aut` / `Run` / `Motion` / `Alarm`.
6. **State management** (`server/state.py`) — per-session handle registry, in-memory PMC/param/macro dictionaries, persistent across one session, reset on session close.
7. **Profile loader** — reads `OTOPCUA_FOCAS_PROFILE` env var, loads matching JSON, injects into handlers.
8. **Windows validation rig** — one-time setup: a Windows VM (or dev box) with licensed `Fwlib64.dll` + a tiny test driver that calls the 9 FWLIB functions + asserts round-trip. This is the first live-wire validation the plan asks for.
9. **Per-series test matrix** — `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/` new project, one test class per series, each class's `[Fact]` runs against that profile's container.

**Exit criterion**: live Fwlib64.dll on a Windows rig opens a session, reads + writes across all 9 FWLIB functions, against each of the 9 profiles. Integration test suite green.

### Stream D — e2e integration + doc close-out (1-2 days)

- Update `scripts/e2e/test-focas.ps1` to accept `-ProfileName` and skip `FOCAS_TRUST_WIRE` gate when the matching container is up.
- Add the FOCAS simulator to `docs/v2/test-data-sources.md` + `docs/drivers/FOCAS-Test-Fixture.md` (flip the "hardware-gated" caveat to "fixture or hardware").
- Update `exit-gate-phase-3.md` — final FOCAS deferral closes.

## Test integration

The new project `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/` mirrors `Driver.OpcUaClient.IntegrationTests`:

```
tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/
├── Docker/
│   ├── docker-compose.yml           # references the 9 series profiles
│   ├── Dockerfile                   # Python image
│   ├── requirements.txt
│   ├── server/
│   └── profiles/
├── FocasSimFixture.cs               # probes 8193 at collection init, skips if down
├── FocasSimSeriesProfile.cs         # test-side mirror of the JSON profile
└── Series/
    ├── ThirtyOneITests.cs
    ├── ZeroIDTests.cs
    └── ... one file per series ...
```

The existing `FocasDocker`-less skip pattern applies: if the container isn't running, tests skip with a clear message pointing at `docker compose up -d`. Matches Modbus / S7 / OpcUaClient.

## Risks + mitigations

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| FOCAS wire protocol is more complex than the OSS traces suggest → Stream C slips weeks | **Medium** | High | Stream A delivers 70% value with zero protocol risk. If Stream C stalls, ship A + schedule C as a follow-up. |
| Fwlib64.dll version differs from what `strangesast/fwlib` reverse-engineered → handshake fails | Medium | High | Capture Wireshark trace of a real CNC session against our actual licensed Fwlib64 version before coding. One-time investment, catches drift early. |
| Profile differences that matter at the wire level aren't captured in `FocasCapabilityMatrix` | Medium | Medium | Stream C exit criterion includes validating each profile against live Fwlib — any mismatch is a profile-table bug we fix then. |
| Docker container startup time breaks PR-CI budget | Low | Low | Each profile is one Python container + profile JSON — sub-5s cold start. Matches opc-plc. |
| Windows validation rig availability blocks Stream C | Medium | High | Use the existing TCBSD-class approach: a dedicated ESXi VM with Windows + licensed Fwlib64.dll, provisioned once, shared by the team. Cost ~1 dev-day to set up; unblocks all future FOCAS work forever. |
| Fanuc licence audit surfaces our mock as an "unlicensed FOCAS implementation" | **Low** | **High** | The mock doesn't ship the Fanuc DLL or reproduce any of Fanuc's code. Reverse-engineered wire formats from OSS research are fair use; the mock is our code. Consult legal before open-sourcing, not before internal use. |

## Timeline estimate

Assuming one dev full-time:

| Stream | Duration | Dependencies |
|---|---|---|
| A — Version-aware fake backend | 2-3 days | none |
| B — TCP server scaffold | 1 week | Windows rig not required yet |
| C — FWLIB compat + profiles | 2-3 weeks | Windows rig with Fwlib64 + Wireshark trace |
| D — e2e + docs | 1-2 days | C done |

**Total**: ~4-5 weeks to full coverage. Ship A immediately (independent value), start C in parallel with Windows-rig setup.

## Exit criteria (what closes #222)

- [ ] All 9 series profiles containerized + pass startup health check
- [ ] Live Fwlib64.dll round-trips all 9 FWLIB calls against every profile (Stream C validation rig)
- [ ] Per-series integration test suite green in CI
- [ ] `test-focas.ps1` runs end-to-end against the simulator without `FOCAS_TRUST_WIRE=1`
- [ ] Docs updated: `FOCAS-Test-Fixture.md` flipped from "hardware-only" to "fixture or hardware"
- [ ] One live-CNC smoke still runs during v2 release readiness, as a belt-and-braces final check

## Open questions

1. **Licence clarity**: is reverse-engineered FOCAS2 wire-format documentation (from `strangesast/fwlib` etc.) compatible with our Fanuc FOCAS developer-kit licence? Legal check required before starting Stream C.
2. **Windows rig**: do we dedicate an existing VM (like the TCBSD box) or provision a new one? Cost difference is small; decision affects who owns maintenance.
3. **Profile source of truth**: if `FocasCapabilityMatrix.cs` and `profiles/*.json` ever disagree, which wins? Proposal: profiles win (wire behavior is authoritative), driver's matrix is regenerated from profiles as a build step.
4. **Alarm events**: the driver doesn't currently use `cnc_rdalmmsg2` / alarm subscription, so the mock doesn't need to simulate alarms beyond the `statinfo.Alarm` flag. If we add `IAlarmSource` to FOCAS later, Stream C expands.

## References

- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FwlibNative.cs` — 9-function P/Invoke surface the mock must satisfy
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs` — per-series range tables (profile seed data)
- `docs/v2/focas-version-matrix.md` — human-readable version matrix the profiles mirror
- `docs/drivers/FOCAS-Test-Fixture.md` — current test-fixture doc (flips post-Stream-D)
- `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/` — pattern this plan mirrors for the Docker compose + fixture-skip shape
- `strangesast/fwlib` (GitHub, OSS) — primary FOCAS wire-format reverse-engineering reference