Register validated Aquilon profile as first-class supported

This commit is contained in:
Dandaedre 2026-11-15 17:18:09 +01:00
parent 5e6ee08273
commit dc522c6ec3
7 changed files with 72 additions and 224 deletions

View File

@ -1,11 +1,15 @@
# Aquilon compatibility investigation
# Aquilon support and acceptance
[Canvas Pilot plan](plan.md) · [Device workflows](guide/device.md) · [Agent implementation task](aquilon_support.task.md)
[Canvas Pilot plan](plan.md) · [Device workflows](guide/device.md) · [Completed implementation](aquilon_support.task.md)
Implemented and tested 2026-11-15. **Canvas Pilot now includes an Aquilon adapter**
Implemented and tested 2026-11-15. **Aquilon is a first-class supported adapter**
for standalone AQL Cmax firmware 6.2.x; the tested emulator is **6.2.79** at the
user-provided custom port. See the [current adapter contract](../interfaces/device-adapters.md).
The supported profile is complete for its documented scope. Physical-output
acceptance remains outstanding; other models, linked units and unsupported
framing modes require separate validation or implementation.
## Current acceptance
- Identity, bounded targeted AWJ reads, screen/layer allocations and

View File

@ -1,222 +1,58 @@
# Aquilon / LivePremier support — agent handoff
# Aquilon / LivePremier support — completed
Status: **initial standalone AQL Cmax 6.2 adapter implemented**, now using
batched targeted AWJ reads instead of full-store downloads. See
[acceptance and limitations](aquilon-compatibility.md) and the
[adapter contract](../interfaces/device-adapters.md). 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.
Status: **first-class supported adapter for standalone AQL Cmax firmware 6.2.x**.
Implementation and emulator acceptance completed on 2026-11-15, using firmware
**6.2.79**. This record replaces the original implementation handoff and its
stale unchecked checklist. It does not extend compatibility to the entire
Aquilon range.
Prepared 2026-11-15. Work in
`crates/canvas-pilot/`; read the repository `AGENTS.md` before editing.
“First-class” means this profile participates in the normal connection, mapping,
project, load/send and capture workflows alongside Midra, with regression tests
and documented limitations. It does not mean every firmware patch or physical
output has been tested.
## Objective
## Completed implementation and acceptance
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.
- [x] Identify the supported model/firmware and reject unsupported or linked profiles.
- [x] Read bounded, targeted AWJ state with cancellation, timeouts, consistency
checks and explicit errors; no full-store fallback.
- [x] Discover enabled screens, auxiliaries, allocated layers and source IDs;
resolve Preview/Program roles per transition group.
- [x] Keep Aquilon paths, geometry conversion and apply behavior in a separate
adapter around the shared screen/layer representation.
- [x] Import container geometry and supported centered crop/zoom framing;
report unsupported modes rather than silently approximate them.
- [x] Persist family-aware screen/auxiliary/layer destinations in project v13;
migrate older projects and recovery data with regression coverage.
- [x] Integrate mapping review, linked load/send, scopes and destination-conflict
checks with the existing editor workflow.
- [x] Implement both sizing strategies for Preview/Program, fresh preflight,
selective writes, the apply pulse and verified readback.
- [x] Quantize transmitted sizes/centers for WebRCS compatibility while retaining
editor precision and checking the resulting visible geometry.
- [x] Pass twelve emulator geometry/crop/zoom transfer cases and restore the
baseline; separately inspect rounded geometry rendered in WebRCS.
- [x] Discover input snapshots beyond input 16 and reuse pooled, throttled,
opt-in capture behavior.
- [x] Cover parsing, conversion, persistence, malformed responses, stale state
and transport behavior with sanitized fixtures and regression tests.
- [x] Complete the recorded workspace validation and update the guide,
interface contracts, acceptance evidence and changelog.
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.
## Explicit support boundaries
## Known target and evidence
- Supported profile: standalone **AQL Cmax 6.2.x**; emulator-tested patch **6.2.79**.
- Physical-output acceptance remains outstanding. Emulator rendering/readback
is the current evidence, not a claim of physical-hardware certification.
- Auxiliaries and independent screen groups have synthetic regression coverage;
the recorded emulator baseline allocates S1 only.
- Linked units, other models/firmware, masks, non-centered fit/anchor modes and
shared input aspect/crop corrections are not additional completed features.
They require separately scoped work and validation before support is expanded.
- HTTP authentication was not validated on the authentication-disabled emulator;
authentication failures remain explicit. AWJ TCP 10606 must be reachable.
- 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/canvas-pilot.md),
[application settings](../interfaces/canvas-pilot-settings.md) and
[input previews](../interfaces/midra-input-preview.md).
## 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.
### 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.
See [acceptance evidence and performance](aquilon-compatibility.md),
[adapter contract](../interfaces/device-adapters.md),
[user workflow](guide/device.md#aquilon--livepremier) and
[remaining project acceptance checks](plan.md#remaining-acceptance-and-release-checks).

View File

@ -4,6 +4,11 @@
## Unreleased
- Register standalone Aquilon AQL Cmax 6.2.x as first-class supported, based on
the recorded 6.2.79 emulator acceptance. Replace the stale implementation
handoff with completed milestones and explicit scope boundaries; physical
output, other models/firmware and unsupported modes remain unverified.
- Record user-confirmed working clipboard workflows for Illustrator, draw.io and
Figma. Narrow remaining clipboard acceptance to Inkscape; QCAD and PowerPoint
remain file-exchange workflows for this scope.

View File

@ -161,8 +161,9 @@ undoable; they do not change physical input routing.
## Aquilon / LivePremier
Canvas Pilot includes a separate adapter for standalone AQL Cmax firmware 6.2.x,
verified on the 6.2.79 emulator. Connect using the same Device connection window.
Aquilon is a first-class supported adapter for standalone AQL Cmax firmware 6.2.x,
verified on the 6.2.79 emulator; physical-output acceptance remains outstanding.
Connect using the same Device connection window.
The device identifies its family automatically. Screens use `S1`, `S2`, …;
auxiliaries use `A1`, `A2`, … and stay distinct in saved mappings. Only enabled
screens and allocated numbered layers appear; empty/unrouted layers remain available.

View File

@ -67,9 +67,9 @@ device readback and physical-screen acceptance.
- [x] **Export/workflow cleanup.** Shared transfer scopes, mapping review and
direct linked send/load are implemented. Marked solved by the user on 2026-11-15.
## Remaining feature work
- [x] **Aquilon / LivePremier: first-class supported (standalone AQL Cmax 6.2.x).** Device-neutral snapshots, family-aware v13 links, bounded targeted AWJ reads, geometry/crop import, mapped Preview/Program sends and pooled input previews. See [adapter contract](../interfaces/device-adapters.md) and [emulator acceptance](aquilon-compatibility.md). Linked units, other models/firmware, shared input corrections and non-centered/masked import remain explicitly unsupported.
- [x] **Aquilon / LivePremier adapter (standalone AQL Cmax 6.2).** Device-neutral snapshots, family-aware v13 links, bounded targeted AWJ reads, geometry/crop import, mapped Preview/Program sends and pooled input previews. See [adapter contract](../interfaces/device-adapters.md) and [emulator acceptance](aquilon-compatibility.md). Linked units, other models/firmware, shared input corrections and non-centered/masked import remain explicitly unsupported.
## Remaining feature work
- [ ] **Inkscape clipboard acceptance.** Obtain a sample and validate actual
copy/paste before claiming support. Illustrator, draw.io and Figma clipboard

View File

@ -33,7 +33,7 @@ Preset recall, TAKE, routing or tally alone do not meet that requirement.
| Tier | Family / representative models | Documentation evidence | Canvas Pilot feasibility and next step |
| --- | --- | --- | --- |
| A | **LivePremier / Aquilon**: C/C+, Cmax and RS variants | Public [AWJ 6.2 programmer's guide](https://dwn01.analogway.com/Site+Internet/Series/Aquilon/Common/AWJ+Protocol/AW_Aquilon_AWJ_ProgrammersGuide_V6.2.pdf). | **Already implemented for standalone AQL Cmax 6.2.x only.** Extend model/firmware profiles after fixtures and acceptance checks; linked systems need explicit unit identity and topology handling. See [current acceptance limits](aquilon-compatibility.md). |
| A | **LivePremier / Aquilon**: C/C+, Cmax and RS variants | Public [AWJ 6.2 programmer's guide](https://dwn01.analogway.com/Site+Internet/Series/Aquilon/Common/AWJ+Protocol/AW_Aquilon_AWJ_ProgrammersGuide_V6.2.pdf). | **First-class supported for standalone AQL Cmax 6.2.x only; emulator-validated on 6.2.79.** Extend model/firmware profiles after fixtures and acceptance checks; linked systems need explicit unit identity and topology handling. See [current acceptance limits](aquilon-compatibility.md). |
| A | **Midra 4K**: Eikos 4K, Pulse 4K, QuickVu 4K, QuickMatrix 4K | AWJ and REST guides in the [official downloads](https://www.analogway.com/downloads); [vendor FAQ](https://www.analogway.com/midra-4k-faqs) documents control options and simulator. | **Existing adapter.** Broaden tested coverage deliberately; current Eikos hardware evidence does not certify every model/mode. See [hardware checks](device-check.md). |
| B | **Alta 4K**: Zenith 100 / 200 | AWJ v1.2 and REST guides plus simulator listed in [official downloads](https://www.analogway.com/downloads); [family overview](https://www.analogway.com/alta-4k-faqs). | **Best next new AW family to investigate.** Likely reuse transport and normalized geometry, but audit native paths, layers, banks and apply behavior. No Alta protocol package or device was exercised here. |
| B | **LiveCore**: Ascender 16/32/48 and LE/4K variants; NeXtage 08/16; SmartMatriX Ultra | [NeXtage support page](https://www.analogway.com/products/nextage-08-livecore) lists the LiveCore programmer's guide and simulator; [Ascender page](https://www.analogway.com/products/ascender-16) lists the family documentation. | **Plausible separate legacy adapter.** Inspect the programmer package and firmware-specific command tables; do not assume AWJ compatibility. Validate linked processors and output expanders separately. |

View File

@ -14,7 +14,9 @@ profiles do not support linked-unit identity; linked Aquilon devices are refused
## Aquilon profile and reads
Initial profile: standalone **AQL Cmax, firmware 6.2.x**, exercised on **6.2.79**.
Supported profile: standalone **AQL Cmax, firmware 6.2.x**, exercised on the
**6.2.79 emulator**. This is a first-class adapter; physical-output acceptance
remains outstanding.
Other firmware/models are rejected before reading geometry. `/api/tpp/v1/system`
on the configured HTTP port supplies identity. Aquilon geometry uses **AWJ TCP
10606 on the same IP**, independently of the HTTP/WebSocket port. AWJ model and