From 3dff673d0deb74839238877c2b5becd23b143d46 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 15 Nov 2026 11:40:45 +0100 Subject: [PATCH] Document Aquilon protocol differences and adapter implementation plan --- docs/manuals/midra-layout/SUMMARY.md | 2 + docs/midra-layout/aquilon-compatibility.md | 94 ++++++++++++++++++++++ docs/midra-layout/changelog.md | 2 + docs/midra-layout/plan.md | 2 + 4 files changed, 100 insertions(+) create mode 100644 docs/midra-layout/aquilon-compatibility.md diff --git a/docs/manuals/midra-layout/SUMMARY.md b/docs/manuals/midra-layout/SUMMARY.md index 0229fc7..bd50f12 100644 --- a/docs/manuals/midra-layout/SUMMARY.md +++ b/docs/manuals/midra-layout/SUMMARY.md @@ -31,3 +31,5 @@ - [Plan and limitations](../../midra-layout/plan.md) - [Development](../../development/README.md) - [Changelog](../../midra-layout/changelog.md) + +- [Aquilon compatibility investigation](../../midra-layout/aquilon-compatibility.md) diff --git a/docs/midra-layout/aquilon-compatibility.md b/docs/midra-layout/aquilon-compatibility.md new file mode 100644 index 0000000..4ff3ffb --- /dev/null +++ b/docs/midra-layout/aquilon-compatibility.md @@ -0,0 +1,94 @@ +# Aquilon compatibility investigation + +[Midra Layout plan](plan.md) · [Device workflows](guide/device.md) + +Investigated 2026-11-15. **Aquilon is not yet enabled in the application.** +This review compared the current Rust adapter with upstream protocol references; +it did not connect to an Aquilon or alter the Midra emulator being tested. + +## Finding + +Aquilon (LivePremier) can reuse our HTTP state-read / WebSocket write approach, +but needs a separate, firmware-aware adapter. Adding its name to the Midra model +list would leave bank selection, geometry paths and the final apply command wrong. +Start with firmware 4.x and later as a candidate profile; validate the actual +firmware/state before extending that claim to later releases. Older firmware +needs a separate profile, not guessed aliases. + +The upstream [Companion integration](https://github.com/bitfocus/companion-module-analogway-awj) +explicitly separates Midra, LivePremier and LivePremier 4. Its name mentions AWJ, +but its implementation uses the web control transport. Analog Way's documented +AWJ TCP service is another transport, not the same socket or message framing as +our WebSocket connection. We do not need to introduce AWJ TCP for the first adapter. + +## Evidence and differences + +The source observations below are pinned to Companion revision +`4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2`. They are implementation evidence, +not a substitute for Aquilon emulator/hardware acceptance. + +| Area | Current Midra adapter | Aquilon evidence / required work | +| --- | --- | --- | +| Connection | IP plus optional port; HTTP state read and root WebSocket | Upstream uses `/auth/status`, `/api/stores/device` and root WebSocket, with authentication handling. Probe these separately from our `/api/tpp/v1/system` identity read. | +| Identity | Four Midra type strings | Upstream detects `NLC` device identifiers and firmware from system state, including linked-device roots. | +| Preset banks | `UP` / `DOWN` | Aquilon uses `A` / `B`; resolve Preview/Program from transition state, independently for each screen/group. | +| Screens | Numeric screen IDs | Screen and auxiliary IDs include `S1` and `A1`. Firmware 4 separates `screenList` and `auxiliaryList`. | +| Allocation | CURRENT preconfiguration layer count | Upstream reads each screen's `status/pp/layerCount`. Discover actual allocations and editable layers. | +| Size | Layer `size/pp/sizeH` and `sizeV` | Shared Aquilon constants put size under `position/pp`, beside position. | +| Coordinates | Center-based `posH` / `posV` | Upstream subtracts half-width/height to obtain top-left coordinates, matching our editor convention. | +| Crop | Layer `crop/pp` and `mask/pp` | Upstream constants use `cropping/classic/pp` and `cropping/mask/pp`. Units, source correction and fit semantics still need verification. | +| Apply pulse | `device/preset/control/pp/xUpdate` | Older Aquilon uses `device/screenGroupList/control/pp/xUpdate`; firmware 4 profile uses `device/screenAuxGroupList/control/pp/xUpdate`. Upstream pulses false then true. | + +Pinned implementation references: + +- [Connection, identity and authentication](https://github.com/bitfocus/companion-module-analogway-awj/blob/4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2/src/connection.ts). +- [Common geometry/crop paths](https://github.com/bitfocus/companion-module-analogway-awj/blob/4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2/src/awjdevice/constants.ts) + and [coordinate conversion](https://github.com/bitfocus/companion-module-analogway-awj/blob/4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2/src/awjdevice/actions.ts). +- [Firmware 4 constants](https://github.com/bitfocus/companion-module-analogway-awj/blob/4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2/src/livepremier4/constants.ts), + [allocation](https://github.com/bitfocus/companion-module-analogway-awj/blob/4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2/src/livepremier4/choices.ts), + [bank resolution](https://github.com/bitfocus/companion-module-analogway-awj/blob/4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2/src/livepremier4/subscriptions.ts) + and [apply pulse](https://github.com/bitfocus/companion-module-analogway-awj/blob/4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2/src/index.ts). + +Analog Way's [Aquilon downloads](https://www.analogway.com/products/aquilon-rs1) +list separate AWJ guides for firmware 2.2–3.x and 4.x onwards, plus a REST guide. +The current links resolve to AWJ guide V6.2 and REST guide v6.0, but their download +server returned HTTP 403 during this investigation; their full contents were not +verified. Use those guides alongside emulator state when implementing crop behavior. +No upstream code or new dependency was copied into the application. + +## Implementation sequence + +1. **Capture an Aquilon baseline.** Obtain emulator IP:port and firmware, read + identity/state, record screen and auxiliary allocation, and inspect authentication. + Keep raw configuration private; derive minimal sanitized regression fixtures. +2. **Separate adapters from transport.** Share address/history, bounded reads, + timeouts, worker scheduling and WebSocket framing. Give each profile its own + identity detection, screen enumeration, bank resolution, geometry paths, crop + conversion and apply pulse. Make Program bank explicit rather than assuming + the opposite of UP is DOWN. +3. **Import geometry first.** Test differently sized canvases, multiple screens, + inactive slots, unassigned inputs, A/B swaps and transitions. Preserve native + device IDs. Do not substitute zeros or default dimensions for missing fields. +4. **Generalize saved links.** `MidraLink::validate` currently accepts only positive + decimal strings. Introduce family-aware destination identity with an explicit + project migration and interface examples/tests; preserve existing Midra links. + Never collapse `S1` and `A1` into the same destination. Keep shared-destination + conflict checks and folder scopes working across the new identities. +5. **Send position/size with readback.** Resolve the chosen bank, use Aquilon's + position/size fields and its apply pulse. Verify both application state and the + emulator's rendered Preview before declaring the send path complete. +6. **Verify crop independently.** Compare source correction, classic crop, mask, + fitting, zoom/offset and both export sizing strategies against known layouts. + Reuse editor geometry math where appropriate; keep device conversion separate. +7. **Add capture and scale coverage.** Our snapshot input limit is currently 16, + and parsing caps allocated layers at 8. Replace family-specific limits with + discovered capabilities plus explicit resource bounds. Reuse pooled low-rate + capture scheduling; verify Aquilon snapshot IDs, endpoints and image dimensions. +8. **Acceptance matrix.** Cover single and linked units, each tested firmware + profile, multiple screens, mapping save/load, history/autoconnect, explicit + Program opt-in and folder sends. Record tested models/firmwares rather than + claiming the entire range from one identity string. + +No persistent schema or device-send contract changes are made by this research. +The next practical input is an Aquilon emulator address and firmware version; +there is no need to interrupt Midra testing to obtain it now. diff --git a/docs/midra-layout/changelog.md b/docs/midra-layout/changelog.md index 0316917..200518b 100644 --- a/docs/midra-layout/changelog.md +++ b/docs/midra-layout/changelog.md @@ -4,6 +4,8 @@ ## Unreleased +- Investigate Aquilon/LivePremier compatibility against the upstream web-control implementation; document firmware-specific geometry, bank and apply paths, saved-link constraints, and the staged adapter/acceptance plan. Research only: no Aquilon support or hardware verification claimed. + - Add a Recent machines picker for the last four successful connections, saved across restarts with distinct ports and most-recent-first ordering. Selecting an entry reads the device immediately; failed attempts do not displace history. Settings v8 migrates v1–v7 with empty history; tests cover ordering, deduplication, failures, persistence and validation. - Support optional device ports for HTTP state reads, input captures and WebSocket sends, preserving the address in preferences/autoconnect. Accept all four Midra 4K identities (Eikos, Pulse, QuickVu, QuickMatrix) with device-reported allocation. Read-checked Pulse 4K 3.3.7 at port 3000 (four layers); add address, model, capture and WebSocket port regressions. Other model hardware acceptance remains outstanding. diff --git a/docs/midra-layout/plan.md b/docs/midra-layout/plan.md index f933ca7..9f82160 100644 --- a/docs/midra-layout/plan.md +++ b/docs/midra-layout/plan.md @@ -67,6 +67,8 @@ device readback and physical-screen acceptance. ## Remaining feature work +- [ ] **Aquilon / LivePremier adapter.** [Protocol investigation and implementation sequence](aquilon-compatibility.md) completed. Next: emulator baseline, firmware-aware geometry import, family-aware saved links, send/apply/readback, then verified crop and capture support. Aquilon is not enabled yet. + - [ ] **Further export/workflow cleanup.** Shared transfer scopes, mapping review and direct linked send/load are implemented; further changes await specifications. - [ ] **Additional native clipboard adapters.** Obtain actual software/version