beffroi-tools/docs/midra-layout/aquilon-compatibility.md

7.9 KiB
Raw Blame History

Aquilon compatibility investigation

Midra Layout plan · Device workflows

Investigated 2026-11-15. Aquilon is not yet enabled in the application. This review compared the current Rust adapter with upstream protocol references; The initial review did not connect to an Aquilon. A subsequent read-only emulator probe on 2026-11-15 confirmed the transport details below; no settings were changed.

Emulator response-size diagnosis

Read-only GETs at the user-supplied emulator confirmed /api/tpp/v1/system returns type: "AQL Cmax", firmware 6.2.79, and /api/stores/device returns 124,076,981 bytes (about 118 MiB). This exceeds the current Midra 32 MiB state limit. Raising that limit alone would still fail at the unsupported-family check. The connection now validates identity before requesting state and explains that Aquilon needs its separate adapter. The large private response is not committed. Future Aquilon transport work must account for this measured state size, ideally with targeted reads rather than repeated full-store downloads. These reads do not validate geometry, crop, bank resolution, capture or writes.

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

Analog Way's Aquilon downloads 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 emulator address and firmware are now known; next inspect the captured state and derive sanitized fixtures before implementing the family-specific adapter.