Document Aquilon protocol differences and adapter implementation plan

This commit is contained in:
Dandaedre 2026-11-15 11:40:45 +01:00
parent 533173b42c
commit 3dff673d0d
4 changed files with 100 additions and 0 deletions

View File

@ -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)

View File

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

View File

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

View File

@ -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