Document Aquilon protocol differences and adapter implementation plan
This commit is contained in:
parent
533173b42c
commit
3dff673d0d
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue