beffroi-tools/docs/canvas-pilot/aquilon_support.task.md

13 KiB

Aquilon / LivePremier support — agent handoff

Status: initial standalone AQL Cmax 6.2 adapter implemented. See acceptance and limitations and the adapter contract. The checklist below is the original implementation brief, retained for the remaining unverified profiles and modes; it is not a claim that all Aquilon firmware or features are supported.

Prepared 2026-11-15. Work in crates/canvas-pilot/; 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 initial implementation is now in the repository. Remaining extensions should use the same staged evidence and acceptance process.

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 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, send/crop conversion, project schema, application settings and input previews.

Original 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.

  • 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:

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.