beffroi-tools/docs/midra-layout-device-check.md

133 lines
7.8 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.

# Eikos connectivity and Preview check
## Verified on 2026-11-13
User-authorized hardware check on an **Eikos 4K, firmware 3.3.10**. The unit
reported this identity through `GET /api/tpp/v1/system`. Its WebRCS bundle was
`app.e42fce4879f318b28cde.js`. The device address was supplied for this session;
it is not a compiled-in application default.
- HTTP read access and WebRCS WebSocket feedback worked without authentication
on this configured device. Do not assume other installations permit this.
- `GET /api/stores/device` returned the state tree used by WebRCS, including
screen canvas dimensions, layer center positions/container sizes, source
assignments, crop/mask fields and transition state.
- The explicit REST read
`/api/tpp/v1/screens/2/live-layers/1/presets/preview` reported input 4,
matching the internal Preview bank. That REST response contained source/status,
not the full geometry. Geometry was obtained from the WebRCS state endpoint.
- Screen 2's transition state was `AT_DOWN`: Program was `DOWN`, Preview `UP`.
WebRCS's own bank-selection code maps `AT_UP` the other way around. These
are physical banks, **not permanent Program/Preview identifiers**.
- A single Preview layer property was changed over the WebRCS WebSocket:
screen 2, bank `UP`, layer 1, `position.pp.posH`, **1436 → 1437 → 1436**.
Readback confirmed the intermediate change and restoration. The complete
tested layer matched its original state after restoration. All four screen
Program preset trees matched before, during and after this test.
- No TAKE, CUT, transition, Program, input/global crop, output configuration,
source-routing or preset-memory command was sent. Raw snapshots remain
temporary local artifacts and are not committed.
The message envelope observed and tested was `channel: "DEVICE"`, with
`data.path` an array of state-tree keys and `data.value` the new scalar value.
The read path for the tested property was:
```
device/screenList/items/2/presetList/items/UP/liveLayerList/items/1/position/pp/posH
```
This is evidence of a working bidirectional link, **not validation of either
advanced-crop export strategy**. Only horizontal center movement was exercised.
The WebRCS internal endpoint/protocol is firmware-specific, rather than a promise
of stable public REST geometry support. Manufacturer references are linked from
[the official Eikos downloads section](https://www.analogway.com/products/eikos-4k).
The linked API PDFs were not accessible during this check; protocol findings
above come from the installed device and its own WebRCS bundle.
## Read-only import bridge
The desktop app now has **Import → Midra Preview…**, also accessible from
**Preferences → Midra integration**. Enter the device IP and click **Read / refresh**.
Reads run in a worker thread; canceling discards late results. Choose a screen and
choose a destination beside each device layer: **Do not import**, **New layer**,
or an existing visible, unlocked editor layer. Click **Import layers** directly
in this window; no prior selection or matching layer count is required. Duplicate
or removed destinations are rejected without partial changes. The entire import,
including new layers, is one undo step. Output resolutions must match. Reading never
changes the document; only applying the reviewed import does. No automatic
connection or polling occurs, and no credentials or address are persisted. The
footer shows **ONLINE** after a successful read (last-read status, not continuous
monitoring), and **OFFLINE** when refreshing, after a failed read, or after editing
the address.
The Rust adapter was tested against the same Eikos 3.3.10: two 1920×1080 screens;
disabled zero-canvas screen slots are filtered. A CLI smoke check is available:
```sh
cargo run -p midra-layout --example read_midra -- DEVICE_IP
```
A standard-library Python helper remains available for snapshot capture/offline replay:
```sh
python3 tools/midra_probe.py --host DEVICE_IP --save-snapshot /tmp/eikos-state.json
python3 tools/midra_probe.py --host DEVICE_IP --screen 2 --layers 1 2 --svg /tmp/preview.svg
# Replay a saved snapshot without connecting:
python3 tools/midra_probe.py --snapshot /tmp/eikos-state.json --screen 2 --layers 1 2 --svg /tmp/replay.svg
```
Select the matching number of editor layers, choose **Import SVG**, and review
mapping before applying. Match the editor output resolution to the device canvas;
SVG geometry import does not replace the editor's screen settings.
The helper exports **container geometry only**: center minus half-size becomes
top-left x/y, preserving half pixels. Source aspect fitting can make the visible
picture differ from this container. Routing, source resolution, source cropping,
effects, borders, opacity and zoom are not imported. Nonzero layer crop or mask
is refused rather than silently imported as final visible bounds. Device slots
are explicitly selected; unused slots are not assumed to be available layers.
The helper has no device write operation, bypasses system proxies, refuses
redirects, bounds reads to 32 MiB and never overwrites an existing output file.
Snapshots may contain network/private configuration; keep them out of Git and
sanitize before sharing. Its exchange contract is documented in
[interfaces](interfaces/midra-device-import.md).
## Remaining integration work
- Extend the implemented reviewed GUI container import to full source/framing
conversion after the corresponding hardware mapping is verified.
- Verify source/input and layer crop units and Centered aspect behavior. Observed
crop edge values such as `18350` must not be interpreted as editor source pixels.
- Validate size, vertical position, odd dimensions and both export strategies
independently before enabling their device commands.
- Production writes need explicit Preview targeting, transition-state monitoring,
fresh before/after review and stale-state rejection. A GET followed by a
physical-bank write is not atomic: another controller can TAKE between them.
Do not expose this diagnostic write technique as a generally safe send button.
- Never write shared input/output configuration to implement a Preview-only edit.
No Program or TAKE operation belongs in this layout tool's Preview adapter.
## Selected-layer send preparation
After a successful read, **Project → Prepare selected layers for Midra…** opens
an outbound review in the connection window. The **Prepare selected layers for
Preview** tab is also accessible there. Each selected local layer has an explicit
Midra destination, snapshot container values, requested visible bounds and local
zoom/offset. Duplicate targets are flagged; mappings are transient and reset when
refreshing or changing screens. No file interface changes are involved.
**Actual sending remains unavailable.** The review is preparation, not a device
payload: container geometry and visible bounds are not interchangeable when
cropping is involved. Both crop export strategies still require verification.
The manufacturer's [REST API guide v3.0.13](https://s3.eu-west-3.amazonaws.com/aw.store01/Site+Internet/Series/Midra+4k/Common/Rest+API+Programmer%27s+Guide/midra4k_rest_api_programmers_guide_v3_0_13.pdf)
was retrieved and inspected on 2026-11-13. Sections 3.5–3.6 document logical
Preview layer status/source operations, but the guide does not document layer
position/size writes. This does not establish a Preview-safe geometry endpoint.
The tested WebRCS geometry path addresses physical UP/DOWN banks, and a read
followed by a write cannot prevent a concurrent TAKE from making that bank Program.
No device writes were performed while adding the outbound review. Enabling the
send button requires verified logical Preview addressing or an atomic device-side
guard, in addition to conversion/readback tests. A client-side warning or a bank
check immediately before writing does not fulfill the user's never-Program rule.