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

4.9 KiB
Raw Blame History

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:

{"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.

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 and hides Program unless the persisted allow_sending_to_program preference is enabled. Turning it off resets the exporter to Preview, including quick Apply. Mappings, plans and raw snapshots are not saved in projects or preferences. The device address is saved in application settings, 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.

Snapshot layer lists omit unassigned source slots (NONE or empty), before geometry validation. Assigned layers remain available even when OFF.