196 lines
7.0 KiB
Markdown
196 lines
7.0 KiB
Markdown
# FOCAS simulator (focas-mock) plan
|
|
|
|
Notes on the focas-mock simulator that the FOCAS driver's integration
|
|
tests will eventually talk to. Today there is no FOCAS integration-test
|
|
project; this doc is the contract the future fixture will be built
|
|
against. Keeping the contract tracked in repo means the wire-protocol
|
|
command ids (and their request/response payloads) don't drift between the
|
|
.NET wire client and a future Python implementation.
|
|
|
|
## Ground rules
|
|
|
|
- Append-only command ids. Mirror
|
|
[`focas-wire-protocol.md`](./focas-wire-protocol.md) verbatim.
|
|
- Per-profile state. The simulator hosts N CNC profiles concurrently
|
|
(`Series0i`, `Series30i`, `PowerMotion`, ...). Each profile has its own
|
|
alarm-history ring buffer + its own override map.
|
|
- Admin endpoints under `POST /admin/...` mutate state without going
|
|
through the wire protocol; integration tests use these to seed canned
|
|
inputs.
|
|
|
|
## Protocol surface (current scope)
|
|
|
|
| Cmd | API | State impact |
|
|
| --- | --- | --- |
|
|
| `0x0001` | `cnc_rdcncstat` | reads cached ODBST per profile |
|
|
| `0x0002` | `cnc_rdparam` | reads parameter map per profile |
|
|
| `0x0003` | `cnc_rdmacro` | reads macro variables per profile |
|
|
| `0x0004` | `cnc_rddiag` | reads diagnostic map per profile |
|
|
| `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
|
|
|
|
The simulator keeps a per-profile ring buffer of alarm-history entries.
|
|
Default fixture seeds 5 profiles with 10 canned entries each (per the F3-a
|
|
plan).
|
|
|
|
### Request decode
|
|
|
|
```
|
|
[int16 LE depth]
|
|
```
|
|
|
|
### Response encode
|
|
|
|
Use `FocasAlarmHistoryDecoder.Encode` semantics in reverse: emit the
|
|
count followed by `ALMHIS_data` blocks padded to 4-byte boundaries. The
|
|
.NET-side decoder consumes the same format verbatim, so a Python encoder
|
|
written against the table in
|
|
[`focas-wire-protocol.md`](./focas-wire-protocol.md) interoperates without
|
|
extra glue.
|
|
|
|
### Admin endpoint — `POST /admin/mock_patch_alarmhistory`
|
|
|
|
Replaces the alarm-history ring buffer for a profile.
|
|
|
|
```
|
|
POST /admin/mock_patch_alarmhistory
|
|
{
|
|
"profile": "Series30i",
|
|
"entries": [
|
|
{
|
|
"occurrenceTime": "2025-04-01T09:30:00Z",
|
|
"axisNo": 1,
|
|
"alarmType": 2,
|
|
"alarmNumber": 100,
|
|
"message": "Spindle overload"
|
|
},
|
|
...
|
|
]
|
|
}
|
|
```
|
|
|
|
`entries` order is interpreted as ring-buffer order (most-recent first to
|
|
match FANUC's natural surface).
|
|
|
|
### `FocasSimFixture.SeedAlarmHistoryAsync`
|
|
|
|
The future test-support helper wraps the admin endpoint:
|
|
|
|
```csharp
|
|
await fixture.SeedAlarmHistoryAsync(
|
|
profile: "Series30i",
|
|
entries: new []
|
|
{
|
|
new FocasAlarmHistoryEntry(
|
|
new DateTimeOffset(2025, 4, 1, 9, 30, 0, TimeSpan.Zero),
|
|
AxisNo: 1, AlarmType: 2, AlarmNumber: 100, Message: "Spindle overload"),
|
|
});
|
|
```
|
|
|
|
Integration test `Series/AlarmHistoryProjectionTests.cs` will assert:
|
|
|
|
- historic events fire once with the seeded timestamps
|
|
- second poll yields zero new events (dedup honoured end-to-end)
|
|
- active-alarm raise/clear still works alongside the history poll
|
|
|
|
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`.
|