beffroi-tools/docs/interfaces/device-adapters.md

6.3 KiB
Raw Blame History

Device adapters and Aquilon exchange

Canvas Pilot's device-neutral snapshot contains a profile, screens with native IDs, output pixel resolutions, explicit Preview/Program banks, and allocated layers with source identity, visible/container geometry, optional source/crop framing and unsupported-mode explanations. It is transient, never a save format. The small profile registry selects family implementations; UI, scopes, history, transport and editor geometry do not contain native path substitutions.

Persistent destinations use project version 13: family + screen + layer. Midra links migrate explicitly from versions 1–12. Neither bank roles nor credentials nor raw device state are persisted. Current standalone 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. Other firmware/models are rejected before downloading the state. /api/tpp/v1/system supplies identity; /api/stores/device supplies native state. The emulator has authentication disabled. Authenticated devices currently report their HTTP/auth failure rather than saving credentials or attempting a login.

No smaller supported read route was found in the installed WebRCS client. Tested /api/stores/device/device/screenList/items/S1/status and /api/device/screenList/items/S1/status return 404. The fallback streams the observed 124,077,157-byte store with a 160 MiB wire limit, one million decoded nodes, 16 MiB aggregate retained/key text budget, 1024 bytes per string, 256 entries per retained map/array, and bounded nesting. Unrelated trees are skipped rather than materialized. Unallocated layers and disabled screens are removed before the snapshot is retained. Network connection timeout is 5 seconds; request timeout is 45 seconds. Worker cancellation is checked between reads; a blocked read retains its timeout. No state enters project files.

Enabled screenList and auxiliaryList entries supply status.pp.layerCount (0–128) and status.size.pp.sizeH/sizeV. Canvas dimensions also obey editor limits (1–16384 integer pixels per side). status.pp.mode: DISABLED excludes an entry even if it retains nonzero stored dimensions. Layer IDs are numbered slots, not inputs; native/background layers are omitted.

Each screen's status.pp.transitionGroup identifies a screenAuxGroupList item. At AT_UP, its control.pp.presetUp is Program and presetDown Preview; AT_DOWN reverses roles. Distinct A/B/C bank identities are validated. Other transition states block import/send planning. Roles are not assumed from bank names.

Geometry, crop and writes

Layer path: device/{screenList|auxiliaryList}/items/{S1|A1}/presetList/items/{bank}/layerList/items/{layer}. Position and size share position.pp: posH, posV are centers; sizeH, sizeV are pixel sizes. Editor geometry is top-left based. Firmware accepts/stores f32 values, but WebRCS 6.2.79 throws oldAnchorRect are not integers when rendering fractional position/size fields. Therefore sends round sizes and centers to whole pixels (sizes 1–1000000). Saved/editor geometry retains double precision; imported half-pixel/top-left geometry is not rounded. Conversion rejects a rounded visible size error above one pixel. Center rounding contributes at most half a pixel. Strict readback checks the quantized values rather than silently accepting clamps. Only MIDDLE_CENTER anchors are currently accepted. Source routing is source.pp.inputNum (LIVE_n, NONE, etc.); production geometry sends omit it.

cropping.classic.pp.{left,right,top,bottom} are integer fractions 0–65535. Layer crop combines the editor input crop and dynamic crop in native source pixels, then rounds edge/native_axis*65535. Exhausted axes are rejected. Sends set cropping.classic.pp.aspectOverride to CENTERED. Masked destinations are rejected; mask fields are never cleared implicitly. Crop decreases precede increases.

Live input LIVE_n resolves inputList.items.IN_n and its active plug. The plug's status.signal.pp.imageWidth/imageHeight supply native dimensions. Shared input cropping and aspect transforms are explicitly unsupported for visible-bound conversion in this initial profile; their controls remain in WebRCS and are never sent by the adapter. Unrouted/color layers with zero crop can still import container geometry. Unknown source dimensions with nonzero crop do not silently produce a visible-box estimate.

Both Output-sized and Source aspect use the existing editor sizing contract. The retained cropped source fits inside the chosen container with a uniform minimum-axis scale. Quantized crop must reproduce the requested visible size within one output pixel. Import reverses this conversion for centered framing; unsupported fit/mask modes are reported on each layer and block its import.

Explicit sends refresh state first and reject stale banks, source/framing values or changed destinations before writing. They use the shared root WebSocket DEVICE framing documented in Midra exchange, then pulse device/screenAuxGroupList/control/pp/xUpdate false → true. No TAKE, routing, shared input, mask or effect writes occur. Changed fields are read back; partial writes, failed applies and mismatches report uncertain outcomes without automatic retry writes or rollback. The emulator diagnostic explicitly restores its baseline.

Input previews and acceptance limits

Discovery uses available IN_n entries, current-plug signal validity and snapshot.pp.enable. The adapter resource limit is 256 inputs; unavailable inputs remain excluded. GET /api/device/snapshots/inputs/n returns PNG data. Inputs 1 and 17 on the emulator returned 256 × 144 PNGs. The existing 16 MiB image limit, decoder bounds, serialized five-second minimum and pooling apply unchanged. No polling setting or snapshot size is written to the device.

Sanitized native fields are recorded in tests/fixtures/aquilon-6.2.json; no raw emulator dump, labels, network settings or credentials are committed. Synthetic variations cover auxiliaries, multiple banks, malformed states and unsupported modes. Emulator readback and WebRCS rendering are separate acceptance checks from physical output. Older firmware, other models, linked units and physical-output behavior remain unverified.