Joseph Doherty
@@ -43,3 +43,98 @@ The history projection emits each unseen entry through
|
||||
reported wall-clock — keep CNC clocks on UTC so the dedup key
|
||||
`(OccurrenceTime, AlarmNumber, AlarmType)` stays stable across DST
|
||||
transitions.
|
||||
|
||||
## Write safety — issue #269, plan PR F4-b
|
||||
|
||||
The FOCAS driver supports `cnc_wrparam` and `cnc_wrmacro` writes behind
|
||||
multiple independent opt-ins. A misdirected parameter write can put the
|
||||
CNC in a bad state, so the runbook below MUST be followed before flipping
|
||||
the granular kill switches on.
|
||||
|
||||
### Operator pre-checks (every deployment, every change)
|
||||
|
||||
1. **CNC must be in MDI mode.** Most parameter writes fail with `EW_PASSWD`
|
||||
(surfaces as `BadUserAccessDenied`) unless the CNC is in MDI. The
|
||||
server-side write returns immediately with the access-denied status; no
|
||||
value reaches the wire.
|
||||
2. **Parameter-write switch enabled on the CNC pendant.** Even in MDI mode
|
||||
protected parameters require the operator to physically enable the
|
||||
parameter-write switch. Without it `cnc_wrparam` returns `EW_PASSWD`.
|
||||
Plan PR F4-d will land an OPC UA-side unlock workflow; today the only
|
||||
path is the pendant.
|
||||
3. **Verify each tag's address against the FANUC manual.** Ranges vary per
|
||||
CNC series; the
|
||||
[`focas-version-matrix`](./focas-version-matrix.md) capability matrix
|
||||
rejects out-of-range numbers at startup, but address-vs-meaning is the
|
||||
operator's job.
|
||||
4. **Dry run with `Writable = true` but `Writes.AllowParameter = false`.**
|
||||
Staged opt-in catches mis-mapped tags: every PARAM write returns
|
||||
`BadNotWritable` until you flip the granular flag, so you can confirm
|
||||
the tag list before any wire write fires.
|
||||
|
||||
### LDAP group requirements
|
||||
|
||||
Per [`docs/security.md`](../security.md) the server-layer ACL maps
|
||||
`SecurityClassification` to LDAP groups. Post-F4-b:
|
||||
|
||||
| Tag kind | LDAP group required |
|
||||
| --- | --- |
|
||||
| `PARAM:N` (writable) | **`WriteConfigure`** — heaviest write tier; matches commissioning roles |
|
||||
| `MACRO:N` (writable) | `WriteOperate` — standard HMI recipe / setpoint group |
|
||||
| PMC R/G/F (writable) | `WriteOperate` |
|
||||
| Read-only | `ReadOnly` |
|
||||
|
||||
Per the `feedback_acl_at_server_layer` design note, the FOCAS driver
|
||||
declares the classification but does NOT enforce it; `DriverNodeManager`
|
||||
applies the gate before the driver's `WriteAsync` ever runs. A user
|
||||
without `WriteConfigure` who attempts a `PARAM:` write gets
|
||||
`BadUserAccessDenied` from the server with no driver-level audit entry —
|
||||
the OPC UA layer's audit log catches it.
|
||||
|
||||
### Audit-log expectations
|
||||
|
||||
Every successful write produces:
|
||||
|
||||
- An OPC UA AuditWriteEvent (server layer — see
|
||||
[`docs/security.md`](../security.md) "Audit logging").
|
||||
- A FOCAS driver-level Serilog entry tagged `Driver=FOCAS DriverInstanceId=...
|
||||
TagName=... Address=... ResultStatus=...`.
|
||||
- A `Writes/LastWriteAt` and `Writes/LastWriteStatus` diagnostic counter
|
||||
refresh on the device's `Diagnostics/` fixed-tree node (planned;
|
||||
populated as F4-c lands).
|
||||
|
||||
Failures to write (`BadUserAccessDenied`, `BadCommunicationError`, etc.)
|
||||
produce the same audit entries with the failure status code so a
|
||||
post-incident reviewer sees the same shape regardless of whether the write
|
||||
succeeded.
|
||||
|
||||
### Granular config example
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"Drivers": {
|
||||
"FOCAS": {
|
||||
"Devices": [
|
||||
{ "HostAddress": "focas://10.0.0.5:8193", "Series": "Series30i" }
|
||||
],
|
||||
"Writes": {
|
||||
"Enabled": true,
|
||||
"AllowMacro": true, // recipe / setpoint writes — operator role
|
||||
"AllowParameter": false // commissioning only — keep locked except during planned work
|
||||
},
|
||||
"Tags": [
|
||||
{ "Name": "Recipe.PartCount", "DeviceHostAddress": "focas://10.0.0.5:8193",
|
||||
"Address": "MACRO:500", "DataType": "Int32",
|
||||
"Writable": true, "WriteIdempotent": true },
|
||||
{ "Name": "MaxFeedrate", "DeviceHostAddress": "focas://10.0.0.5:8193",
|
||||
"Address": "PARAM:1815", "DataType": "Int32",
|
||||
"Writable": false /* keep read-only until commissioning window */ }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Flipping `AllowParameter` on for the commissioning window (and back off
|
||||
afterward) is the recommended deployment cadence — the granular kill
|
||||
switch is a lightweight runtime toggle, not a config-DB redeploy.
|
||||
|
||||
@@ -29,6 +29,8 @@ command ids (and their request/response payloads) don't drift between the
|
||||
| `0x0010` | `pmc_rdpmcrng` | reads PMC byte ranges |
|
||||
| `0x0020` | `cnc_modal` | reads cached modal MSTB per profile |
|
||||
| ... | ... | ... |
|
||||
| **`0x0102`** | **`cnc_wrparam`** | **mutates per-profile parameter map; returns `EW_PASSWD` (`11`) when the profile's `unlock_state` is off (sets up F4-d's unlock workflow) — issue #269, plan PR F4-b** |
|
||||
| **`0x0103`** | **`cnc_wrmacro`** | **mutates per-profile macro map; integer-only writes for now (decimalPointCount=0) — issue #269, plan PR F4-b** |
|
||||
| **`0x0F1A`** | **`cnc_rdalmhistry`** | **dumps the per-profile alarm-history ring buffer (issue #267, plan PR F3-a)** |
|
||||
|
||||
## `cnc_rdalmhistry` mock behaviour
|
||||
@@ -100,3 +102,94 @@ Integration test `Series/AlarmHistoryProjectionTests.cs` will assert:
|
||||
These tests are blocked on the focas-mock + integration-test project
|
||||
landing; the unit-test coverage in `FocasAlarmProjectionTests` already
|
||||
exercises every same-process invariant.
|
||||
|
||||
## `cnc_wrparam` / `cnc_wrmacro` mock behaviour — issue #269, plan PR F4-b
|
||||
|
||||
When the focas-mock fixture lands, it MUST implement the contract below.
|
||||
The .NET side already ships against this contract (`FwlibFocasClient.cs`
|
||||
write helpers, `FakeFocasClient` round-trip support); writing the simulator
|
||||
to the same shape lets the existing integration-test scaffolds at
|
||||
`tests/.../IntegrationTests/Series/ParameterWriteTests.cs` and
|
||||
`MacroWriteTests.cs` (when they materialise) light up without driver
|
||||
changes.
|
||||
|
||||
### Per-profile state
|
||||
|
||||
Each profile owns:
|
||||
|
||||
- `parameters: Dict[int, int]` — map from parameter number to current value.
|
||||
- `macros: Dict[int, int]` — map from macro number to current scaled-int
|
||||
value (decimal-point count fixed at 0 for F4-b).
|
||||
- `unlock_state: bool` — defaults `False`. When `False`, every
|
||||
`cnc_wrparam` returns `EW_PASSWD` (numeric `11`) regardless of
|
||||
parameter. Macro writes are NOT gated by `unlock_state`.
|
||||
- `last_write: Optional[LastWrite]` — most-recent successful
|
||||
`(kind, number, value, ts)` tuple, surfaced via the admin endpoint
|
||||
below for audit-log assertions.
|
||||
|
||||
### `cnc_wrparam` request decode
|
||||
|
||||
```
|
||||
[int16 LE datano][int16 LE axis][int8|int16|int32 LE value]
|
||||
```
|
||||
|
||||
Width of the value field is determined by the request frame trailer
|
||||
length per the table in
|
||||
[`focas-wire-protocol.md`](./focas-wire-protocol.md). On
|
||||
`unlock_state == False` short-circuit to `[int16 LE 11]` (`EW_PASSWD`).
|
||||
Otherwise mutate `parameters[datano] = value`, set `last_write`, return
|
||||
`[int16 LE 0]`.
|
||||
|
||||
### `cnc_wrmacro` request decode
|
||||
|
||||
```
|
||||
[int16 LE number][int16 LE length=8][int32 LE mcr_val][int16 LE dec_val]
|
||||
```
|
||||
|
||||
Always accept (no `unlock_state` gate). Mutate
|
||||
`macros[number] = mcr_val` (we ignore `dec_val` for F4-b — integer-only).
|
||||
Return `[int16 LE 0]`. Round-trip: a subsequent `cnc_rdmacro(number)`
|
||||
returns `(mcr_val, 0)`.
|
||||
|
||||
### Admin endpoint — `POST /admin/mock_set_unlock_state`
|
||||
|
||||
Toggles `unlock_state` for the F4-d unlock workflow tests. Without this,
|
||||
F4-b parameter-write integration tests can't reproduce the
|
||||
`EW_PASSWD` → `BadUserAccessDenied` mapping.
|
||||
|
||||
```
|
||||
POST /admin/mock_set_unlock_state
|
||||
{ "profile": "Series30i", "unlocked": true }
|
||||
```
|
||||
|
||||
### Admin endpoint — `GET /admin/mock_get_last_write`
|
||||
|
||||
Returns the simulator's view of the most-recent successful write, used by
|
||||
F4-b audit-log integration assertions ("did the write actually reach the
|
||||
fixture, and is the audit log capturing the right kind/number/value?").
|
||||
|
||||
```
|
||||
GET /admin/mock_get_last_write?profile=Series30i
|
||||
->
|
||||
{
|
||||
"kind": "param", // "param" | "macro"
|
||||
"number": 1815,
|
||||
"value": 100,
|
||||
"writtenAt": "2026-04-25T13:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
When no write has happened the endpoint returns `null` rather than 404 so
|
||||
the test helper can assert "no writes since fixture reset" without
|
||||
exception handling.
|
||||
|
||||
### Status
|
||||
|
||||
focas-mock simulator has not landed yet (tracked separately from F4-b).
|
||||
F4-b lands the .NET-side wire encoders + dispatch + status mapping
|
||||
unconditionally; the integration-test scaffolds at
|
||||
`tests/.../IntegrationTests/Series/ParameterWriteTests.cs` and
|
||||
`MacroWriteTests.cs` are deferred until the simulator + integration-test
|
||||
project land. Until then unit-test coverage in
|
||||
`FocasWriteParameterTests` / `FocasWriteMacroTests` exercises every
|
||||
same-process invariant against the in-memory `FakeFocasClient`.
|
||||
|
||||
@@ -19,6 +19,8 @@ Each FOCAS-equivalent call gets a stable wire-protocol command id. Ids are
|
||||
| `0x0003` | `cnc_rdmacro` | macro variable value |
|
||||
| `0x0004` | `cnc_rddiag` | diagnostic value |
|
||||
| ... | ... | ... |
|
||||
| **`0x0102`** | **`cnc_wrparam`** | **IODBPSD parameter-write packet (issue #269, plan PR F4-b)** |
|
||||
| **`0x0103`** | **`cnc_wrmacro`** | **ODBM macro-write packet (issue #269, plan PR F4-b)** |
|
||||
| `0x0F1A` | **`cnc_rdalmhistry`** | **ODBALMHIS alarm-history ring-buffer dump (issue #267, plan PR F3-a)** |
|
||||
|
||||
## ODBALMHIS — alarm history (`cnc_rdalmhistry`, command `0x0F1A`)
|
||||
@@ -74,3 +76,81 @@ DST transitions. The .NET decoder
|
||||
unstable anyway.
|
||||
- `msg_len` overrunning the payload truncates the entry list at the
|
||||
malformed entry rather than throwing.
|
||||
|
||||
## IODBPSD — parameter write (`cnc_wrparam`, command `0x0102`)
|
||||
|
||||
Issue #269, plan PR F4-b. The write-side payload is the **byte-symmetric
|
||||
inverse of the `cnc_rdparam` read** — the same `IODBPSD` struct shape, and
|
||||
the .NET wire client uses the read-side decoder reversed (`EncodeParamValue`
|
||||
in `FwlibFocasClient.cs`) so the encoder/decoder are guaranteed to stay in
|
||||
lock-step.
|
||||
|
||||
### Request
|
||||
|
||||
| Offset | Width | Field |
|
||||
| --- | --- | --- |
|
||||
| 0 | `int16 LE` | `datano` — parameter number (e.g. `1815`) |
|
||||
| 2 | `int16 LE` | `type` — axis index (1-based; `0` = whole-CNC parameter) |
|
||||
| 4 | `length` | `data` payload — width depends on parameter type |
|
||||
|
||||
`length` (request frame trailer, drives `data` width):
|
||||
|
||||
| FocasDataType | `length` | Payload encoding |
|
||||
| --- | --- | --- |
|
||||
| `Byte` | `4 + 1` | one signed byte at offset 4 |
|
||||
| `Int16` | `4 + 2` | int16 LE at offset 4 |
|
||||
| `Int32` | `4 + 4` | int32 LE at offset 4 |
|
||||
|
||||
Bit-addressed parameters (`PARAM:1815/0` form) are not supported by F4-b
|
||||
and surface as `BadNotSupported`; F4-c will land the read-modify-write
|
||||
helper alongside the PMC bit RMW path.
|
||||
|
||||
### Response
|
||||
|
||||
Single `int16 LE` return code per the standard FWLIB convention:
|
||||
|
||||
- `0` → `Good`
|
||||
- `11` (`EW_PASSWD`) → **`BadUserAccessDenied`** (was `BadNotWritable`
|
||||
pre-F4-b — see `FocasStatusMapper`). Means the parameter-write switch is
|
||||
off or the CNC isn't in MDI mode; the F4-d unlock workflow will close
|
||||
the loop on this from the OPC UA side.
|
||||
- Other `EW_*` codes map per
|
||||
[`FocasStatusMapper.MapFocasReturn`](../../src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasStatusMapper.cs).
|
||||
|
||||
## ODBM — macro write (`cnc_wrmacro`, command `0x0103`)
|
||||
|
||||
Issue #269, plan PR F4-b. The write-side payload mirrors the
|
||||
`cnc_rdmacro` read shape: the same `(mcr_val, dec_val)` (integer +
|
||||
decimal-point count) split, but emitted from the .NET side rather than
|
||||
decoded.
|
||||
|
||||
### Request
|
||||
|
||||
| Offset | Width | Field |
|
||||
| --- | --- | --- |
|
||||
| 0 | `int16 LE` | `number` — macro variable number (e.g. `500`) |
|
||||
| 2 | `int16 LE` | `length` — fixed at `8` for ODBM |
|
||||
| 4 | `int32 LE` | `mcr_val` — scaled integer value |
|
||||
| 8 | `int16 LE` | `dec_val` — decimal-point count |
|
||||
|
||||
F4-b ships **integer-only writes** (`dec_val = 0`) to match the most
|
||||
common HMI pattern; a future `WriteMacroScaled` overload will land if the
|
||||
field calls for fractional macro setpoints. Read-side decoders apply
|
||||
`mcr_val / 10^dec_val`, so a `dec_val = 0` write surfaces back as the
|
||||
integer it was emitted as.
|
||||
|
||||
### Response
|
||||
|
||||
Same single-int16 envelope as `cnc_wrparam`. `EW_PASSWD` is rare on macro
|
||||
writes (the gate-switch protection is parameter-specific) but the mapper
|
||||
treats both kinds identically.
|
||||
|
||||
### Symmetry note
|
||||
|
||||
The plan carries a "byte layout symmetry" requirement — the encoder for
|
||||
each kind is the read-side decoder reversed. Adding a new parameter type
|
||||
(e.g. `Int64` parameters, when they ship) means extending both sides in
|
||||
the same PR; the unit test
|
||||
`FocasWriteParameterTests.ParameterWrite_round_trip_stores_value_visible_to_subsequent_read`
|
||||
exercises encode → store → decode with the fake wire client and is the
|
||||
canary for symmetry regressions.
|
||||
|
||||
Reference in New Issue
Block a user