102 lines
6.3 KiB
Markdown
102 lines
6.3 KiB
Markdown
# 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](canvas-pilot.md): 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](midra-device-send.md), 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.
|