beffroi-tools/docs/interfaces/midra-device-send.md

78 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Midra reviewed layer exchange
This is a transient device protocol, not a project/save schema. Project v4 remains
unchanged. Compatibility exercised: Eikos 4K firmware 3.3.10, installed WebRCS
`app.e42fce4879f318b28cde.js`. Other firmware needs verification.
## Addressing and fields
HTTP GET `/api/tpp/v1/system` and `/api/stores/device` supply identity and snapshots.
A WebSocket at `ws://DEVICE_IP/` accepts JSON text:
```json
{"channel":"DEVICE","data":{"path":["device","screenList","items","2","presetList","items","UP","liveLayerList","items","1","position","pp","posH"],"value":162}}
```
Reviewed fields under the mapped live layer are only:
- `size.pp.sizeH`, `size.pp.sizeV`: integer container pixels, 1–65535.
- `position.pp.posH`, `position.pp.posV`: integer center coordinates, −67268–67268.
- `crop.pp.left`, `right`, `top`, `bottom`: normalized integers, 0–65535.
- `crop.pp.aspectOverride`: `CENTERED`.
At `AT_DOWN`, Preview is UP and Program DOWN; `AT_UP` reverses those roles.
The selected configuration captures one physical bank. Send writes directly without a preflight read or stale-snapshot refusal. Commands do not retarget halfway through. No TAKE or source routing,
mask, effect, opacity, shared input crop or output setting is sent.
## Conversion
The editor native source dimensions must equal the destination layer's reported
`status.pp.contentWidth/contentHeight`. These describe the incoming content used
for this layer, not an instruction to change input hardware configuration.
Combine each local input crop edge with its advanced layer crop edge, in native
source pixels. Quantize each combined edge to `round(edge / native_axis * 65535)`.
Reject exhausted retained regions, invalid geometry, masked destinations and
source-resolution mismatch. Input correction is folded into the layer crop,
so it affects only the mapped destination.
For **Output-sized**, round the requested visible width/height to container pixels.
For **Source aspect**, compute `k = max(visible_width/native_width,
visible_height/native_height)` and round `native * k` as the container size. The
post-crop retained source fits inside this container with Centered aspect. Both
modes center the container at the rounded requested visible center.
Reconstruct the retained size from quantized crop fractions, then use
`min(container_width/retained_width, container_height/retained_height)` to derive
visible bounds. Reject size errors above one output pixel. Center rounding has
at most half a pixel of error. Stored editor coordinates retain full precision;
review values use one decimal and transmitted geometry uses whole pixels.
## Import and round trip
Centered layers with zero masks and valid content dimensions reconstruct their
visible geometry with the same fit calculation. Imported sources are independent
local sources with the device content dimensions, zero input correction, and all
combined cropping stored in advanced crop. Thus the visual framing survives;
the original separation into input correction and layer crop cannot be recovered.
Imports are atomic and undoable, including creation of new layers/sources.
Other aspect modes retain container-only import and reject nonzero crop/mask.
The Python snapshot-to-SVG bridge remains container-only under its existing
[contract](midra-device-import.md).
## Execution and failure semantics
Only an explicit Send click creates a worker. Read/refresh, editing, project load,
import, undo and redo never write. Requests run off the UI thread with bounded
socket operations. After preflight, changed fields are written sequentially once. Crop decreases precede increases
to avoid temporarily exhausting the retained area while moving a crop.
Readback checks every changed field. No-op plans are disabled. Failure reports
partial/uncertain outcomes without blind retries or automatic rollback.
Program selection is explicit. The application defaults to Preview. Mappings,
plans and raw snapshots are not saved in projects or preferences. The device address is saved in [application settings](midra-layout-settings.md), never in projects. Refresh and screen changes reset destination review. Physical display
validation remains separate from the successful device-field and import round trips.
The status-bar and Export-menu **Apply to Midra** actions prepare a fresh plan for the current editor selection using the session mappings, target and sizing mode. Valid changed plans send immediately with readback verification, without a preflight refusal. Missing or invalid mappings open the configuration window without writing; no-op plans and busy/offline actions are disabled. No persistent schema changes are involved.