beffroi-tools/docs/midra-layout/aquilon_support.task.md

216 lines
13 KiB
Markdown

# Aquilon / LivePremier support — agent handoff
Status: **not implemented**. Prepared 2026-11-15. Work in
`crates/midra-layout/`; read the repository `AGENTS.md` before editing.
## Objective
Add a separate Aquilon adapter to the existing layout editor, initially targeting
**AQL Cmax firmware 6.2.79**. Deliver useful geometry import first, then mapped
position/size transfers, crop conversion and input previews. Preserve existing
Midra behavior and reuse the editor, transfer scopes, mapping review and transport
where their semantics actually match. Do not claim support for every Aquilon
firmware/model based on this one emulator.
This file is an implementation brief, not a request to start a second agent.
The current task only prepares the handoff; the implementing agent should execute
the stages below when assigned the implementation.
## Known target and evidence
- User-supplied emulator: `192.168.10.146:3000` (HTTP and expected WebSocket
authority; verify that it is still this emulator before diagnostic writes).
- Read-only `GET /api/tpp/v1/system` returned:
`{"type":"AQL Cmax","label":"AQUILON","isLinked":false,"linkName":"","version":{"major":6,"minor":2,"patch":79,"beta":false}}`.
- `GET /api/stores/device` returned **124,076,981 bytes**, approximately 118 MiB.
The existing 32 MiB Midra response cap cannot accommodate it.
- The probe wrote `/tmp/aquilon-system.json` and `/tmp/aquilon-device-state.json`.
These are temporary, private local artifacts and may no longer exist. Re-read
if necessary; do not commit the raw state or assume it is current.
- Commit `0c37ad6` added identity validation before downloading state. Aquilon
currently reports that its adapter is unimplemented. Replace this refusal only
when a supported profile can actually parse it; merely accepting the model name
or raising the cap does not enable compatibility.
- [Protocol investigation](aquilon-compatibility.md) records the upstream evidence,
exact Companion revision and source links. Review those before implementing.
AWJ TCP and WebRCS WebSocket transport are distinct; do not mix their framing.
The user previously authorized device testing, including Program changes, and
rejected extra confirmation rituals in the product. Preserve the actual product
contract: Program destinations require the **Allow sending to program** preference;
opening mapping options does not send; the explicit Send action sends. Use Preview
for initial diagnostics. No implicit TAKE or input routing changes. Keep hardware
writes out of automated CI. Do not turn old agent-facing cautions into new dialogs.
## Code map and contracts to preserve
| Area | Current implementation |
| --- | --- |
| Identity, HTTP reads, screen/layer parsing | `src/device.rs` (`Snapshot`, `Screen`, `Layer`, `fetch`) |
| Send planning, WebSocket writes, apply/readback | `src/device_send.rs` (`Target`, `Sizing`, `Plan`) |
| Connection/history, scope, mapping, direct send/load | `src/device_ui.rs` |
| Snapshot endpoints and input discovery | `src/device_capture.rs` |
| Pooled low-rate captures and preview state | `src/capture_ui.rs` |
| Geometry, layer identities and saved links | `src/lib.rs` (`MidraLink` currently has decimal-only screen/layer strings) |
| Source/crop math and property windows | `src/formats.rs`, `src/format_ui.rs` |
| Project persistence and recovery | `src/project.rs`, `src/project_ui.rs`, `src/recovery_ui.rs` |
| Connection/application preferences | `src/settings.rs` |
| Existing regression fixtures | `tests/device.rs`, `tests/project.rs`, in-module send/capture/UI tests |
Read [device import](../interfaces/midra-device-import.md),
[send/crop conversion](../interfaces/midra-device-send.md),
[project schema](../interfaces/midra-layout.md),
[application settings](../interfaces/midra-layout-settings.md) and
[input previews](../interfaces/midra-input-preview.md).
## Staged implementation checklist
### 1. Establish a bounded, usable Aquilon state reader
- [ ] Confirm identity/firmware, authentication requirements and root structure.
Inspect `/auth/status` if supported; avoid logging credentials or session tokens.
- [ ] Inventory actual screens, auxiliary screens, layer allocations, source IDs,
transition/bank state and any linked-unit identifiers in the captured data.
- [ ] Investigate documented subtree reads or subscriptions. Prefer small reads
sufficient for a coherent operation over repeatedly fetching the full store.
Do not invent subtree URLs without testing them.
- [ ] If a full-store fallback is necessary, give it an explicit, measured size
budget and timeout, and bound decoded data as well as wire bytes. Account for
JSON allocation and cloning costs; retain only the state needed by the adapter.
- [ ] Keep network/parse work off the UI thread. Support cancellation, progress,
timeouts, malformed responses and authentication errors without stale-online state.
- [ ] Derive small sanitized fixtures. Record field meanings and uncertainty;
do not check in the 118 MiB dump.
Acceptance: the target can be identified and read without the misleading size
error, UI blocking or unbounded allocations. Unsupported profiles fail clearly.
### 2. Separate transport from device-family semantics
- [ ] Introduce explicit device family/profile and capability information. Keep
existing Midra profiles working; avoid scattered `if Aquilon` path substitutions.
- [ ] Normalize screen/layer geometry into the current editor model while keeping
native destination identity. Profiles own paths, bank resolution and apply pulses.
- [ ] Model Preview and Program banks explicitly. The current “not UP means DOWN”
logic is Midra-specific and cannot resolve Aquilon A/B banks.
- [ ] Resolve banks per screen/group and handle active transitions explicitly.
Candidate differences from upstream, **to verify against 6.2.79**:
| Concern | Aquilon candidate behavior |
| --- | --- |
| Screen identity | `S1`, `A1`; firmware 4+ separates screen/auxiliary lists |
| Allocated layer count | Screen `status/pp/layerCount` |
| Position and size | Both under layer `position/pp`; positions are centers |
| Crop/mask | `cropping/classic/pp` and `cropping/mask/pp` |
| Apply | Firmware 4+ `device/screenAuxGroupList/control/pp/xUpdate`, false then true |
| Older profiles | Different roots/apply path; explicitly out of initial scope |
### 3. Import geometry and expose accurate capabilities
- [ ] Import actual allocated layers, independently of whether they have a source.
Inputs and layer slots are different resources; never infer layer count from inputs.
- [ ] Convert center position and size into editor top-left boxes; retain fractional
values internally. Preserve disabled-screen handling and error reporting.
- [ ] Support screen/frame selection and explicit destination mapping using the
existing dedicated device-import workflow, not the generic geometry-import dialog.
- [ ] Preserve default All / Selected / Folder scopes and linked-load behavior.
- [ ] Detect crop/mask/fit combinations not yet understood; report their limitation
rather than silently importing incorrect visible bounds.
Acceptance: multiple differently sized screens, unassigned layers, A/B swaps,
empty/disabled slots and malformed state have regression coverage. Imported boxes
match the emulator's displayed positions and sizes for the verified simple case.
### 4. Persist family-aware destination links
- [ ] Design destination identity including family, screen/auxiliary identity and
layer; include unit identity where the verified linked topology requires it.
Never collapse `S1` and `A1` into one numeric destination.
- [ ] Update validation, mapping selectors, conflict detection and linked send/load.
Multiple editor layers may share a destination, but a single send scope with
duplicate destinations must be rejected with the conflicting layer names.
- [ ] Preserve remapping/unmapping, saved screen selection and folder-based memories.
Do not revive the removed multi-link-per-layer or nested-folder proposals.
- [ ] Version any breaking project schema change (current baseline is v12), migrate
existing numeric Midra links explicitly, and test save/load/recovery and undo.
- [ ] Update interface docs, examples and embedded-export snapshot behavior in the
same change. Keep temporary device state out of saved projects.
### 5. Send position/size and apply changes
- [ ] Implement profile-specific write planning for the chosen Preview/Program bank.
Validate destinations against actual capabilities, not hard-coded Midra limits.
- [ ] Preserve both `OutputBox` and `SourceAspect` sizing strategies; enable only
combinations whose interpretation has been verified.
- [ ] Use the verified Aquilon apply pulse. Resolve bank state afresh when needed
so a stale snapshot does not select the wrong preset.
- [ ] Read back affected fields and verify the emulator rendering, not just WebRCS
values. Previously Midra accepted writes without visibly applying them until
the missing apply pulse was sent.
- [ ] Preserve direct Send linked layers and Load linked layers, mapping review,
selection/folder scope, error reporting and Program preference behavior.
Acceptance: change a known layer, apply, read back and observe the intended box;
record the tested destination/bank and restore diagnostic geometry afterward.
Partial writes and disconnects must be reported without claiming success.
### 6. Verify crop, zoom and advanced source behavior
- [ ] Determine crop units, rounding, fit modes, masks and source correction from
the actual firmware. Do not reuse Midra's normalized crop units without evidence.
- [ ] Test both send sizing strategies against asymmetric and extreme crops,
non-16:9 sources, custom input dimensions, content offsets and zoom >= 100%.
- [ ] Verify inverse import conversion and export/import round trips. The final
visible layer box must remain consistent with the editor's geometry contract.
- [ ] Leave shared input settings untouched unless explicitly enabled and edited
in the Advanced Source section. Do not change source routing as a side effect.
- [ ] Keep unsupported fit/mask modes explicit until verified.
### 7. Add low-resource input previews
- [ ] Verify capture endpoints, IDs, availability/no-signal reporting and sizes.
Remove Midra-only input limits through discovered capabilities plus resource caps.
- [ ] Reuse serialized/throttled requests, pooling when layers share an input,
opt-in refresh, immediate-but-throttled capture on selection and cancellation.
- [ ] Preserve input preselection on device load without auto-capturing until enabled,
source assignment/stills in projects, and paused refresh after project restore.
- [ ] Keep reference captures still-only and preserve preview/crop-guide controls.
### 8. Acceptance, documentation and delivery
- [ ] Add sanitized parser/plan fixtures and mock HTTP/WebSocket tests, including
correct apply pulse, no implicit TAKE, no routing writes and opt-in source edits.
- [ ] Exercise existing Midra fixtures to prove this adapter has not changed them.
- [ ] Test mapping persistence, duplicate destinations, folder sends, reconnect,
custom port, history/autoconnect, stale bank state and failure recovery.
- [ ] Record emulator acceptance separately from physical-output acceptance.
Linked units, older firmware and untested models remain explicitly unverified.
- [ ] Update the investigation, main plan, user manual, affected interface contracts
and Unreleased changelog with what actually works and remaining limitations.
- [ ] Commit each completed task with only its relevant changes; do not push.
Required repository checks:
```sh
cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
python3 scripts/ci.py coverage
```
Run relevant default-feature tests too when touching native exchange or embedded
project snapshots: all-features includes `no_proprietary` and disables those codecs.
Local mock-server tests need permission to bind loopback sockets in a restricted
sandbox. Actual-device write diagnostics are separate manual checks, never CI.
## Reporting checkpoints
After each stage, report the implemented capability, exact emulator/model/firmware
checked, test results and remaining gaps. Distinguish “state read”, “geometry
import”, “position/size transfer”, “crop conversion” and “preview capture”; do not
summarize a partial implementation as complete Aquilon support. If the target is
unavailable, continue fixture/refactoring/documentation work and state which
acceptance checks require the emulator rather than inventing protocol behavior.