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

54 lines
3.2 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 device snapshot and container SVG bridge
Implementation: [`tools/midra_probe.py`](../../tools/midra_probe.py).
Tests: [`tests/test_midra_probe.py`](../../tests/test_midra_probe.py).
Hardware evidence and usage: [Eikos check](../midra-layout/device-check.md).
## Snapshot
`--save-snapshot` writes UTF-8 JSON containing the raw object from
`GET /api/stores/device`; the root key is `device`. No editor project version
or custom wrapper is added. This is **vendor state**, not a Midra Layout project.
The firmware owns its schema. The Rust adapter accepts Eikos 4K, Pulse 4K,
QuickVu 4K and QuickMatrix 4K identities and validates the shared state fields.
Reads were checked on Eikos 4K 3.3.10 hardware and the Pulse 4K 3.3.7 emulator
(one 1920 × 1080 screen with four allocated layers). QuickVu and QuickMatrix
have synthetic parser coverage; physical acceptance remains outstanding.
The Rust connection accepts an IP with optional port, shared across HTTP and
WebSocket; see [connection syntax](../midra-layout/guide/device.md#connect-a-device-or-emulator).
`--snapshot` reads it offline, at most 32 MiB, and rejects missing required fields
when extracting geometry. Unknown vendor fields are preserved on capture.
Snapshots can contain private configuration. They are never sent back to a unit.
Geometry extraction uses these paths below `device`:
- `transition/screenList/items/{screen}/status/pp/transition`: only `AT_DOWN`
(Preview `UP`) or `AT_UP` (Preview `DOWN`) is accepted. Transitional states fail.
- `screenList/items/{screen}/canvas/status/size/pp/{sizeH,sizeV}`: canvas pixels.
- `screenList/items/{screen}/presetList/items/{bank}/liveLayerList/items/{layer}`:
`position/pp/{posH,posV}` is the center in canvas pixels;
`size/pp/{sizeH,sizeV}` is the device container size in pixels.
- `crop/pp` and `mask/pp`: all four edges must be zero for SVG extraction.
Their nonzero units/semantics are intentionally not converted yet.
## Container SVG
This uses the existing [geometry SVG marker](midra-layout.md#legacy-svg-geometry-exchange-version-1),
`data-midra-layout-geometry="1"`, so a full-screen container is not mistaken for
an ignorable background. Root `width`, `height`, and `viewBox` come from the device
canvas. One or two rectangles are emitted in explicit `--layers` order, with IDs
`screen-{screen}-layer-{layer}`, opaque fill and no stroke. Duplicate selections
are refused. Missing slots fail rather than being skipped.
Rectangle x/y = center minus half-size. Values are not rounded: this is an import
bridge preserving device measurements, not the editor's rounded export. SVG
imports accept fractional pixels. Numeric values must be finite, non-boolean,
within ±1,000,000; widths/heights must be positive. The editor performs its own
validation again before applying. Existing destinations are refused.
Only container position/size round-trips. No source association, aspect fitting,
input crop, zoom, visibility, borders, effects or device connection is encoded.
The desktop SVG mapping dialog must be reviewed before applying; the image's
visible bounds are not guaranteed to equal the container. This format must not
be presented as a full device/project backup or as validated crop conversion.