Installing the player OS image

Flashing the dedicated player OS image onto signage hardware.

What you need

A downloaded installer ISO, and the SHA-256 checksum shown next to it — get both from the Downloads page (Linux → installer-iso).
A USB flash tool (e.g. balenaEtcher).
A USB stick (8 GB+).
Target hardware with the firmware boot menu accessible (typically F12, F10, F8, or Esc at boot).

Steps

Verify the download before flashing. Paste the SHA-256 shown for that release on the Downloads page, keeping the two spaces before the filename:
```
echo "<sha256-from-downloads-page>  vision-player-installer_<version>_amd64.iso" \
  | sha256sum -c -
```
Expect vision-player-installer_<version>_amd64.iso: OK. Anything else means a corrupt or truncated download — fetch it again rather than flashing it.

To script this, the same digest is published beside the ISO at <iso-url>.sha256. That file holds the bare hash with no filename, so feed it in rather than passing it to sha256sum -c:
```
iso=vision-player-installer_<version>_amd64.iso
echo "$(curl -fsS "https://downloads.zenglobal.au/vision/installers/<channel>/${iso}.sha256")  ${iso}" \
  | sha256sum -c -
```
Flash the ISO to USB with balenaEtcher: Flash from file → select the ISO → select the target USB drive → Flash.
Boot the target machine from USB. Insert the stick, power on, and hit the firmware boot-menu key to select the USB device.
Run the installer TUI. Pick the destination disk, type YES to confirm (this erases the disk), wait for it to finish, remove the USB stick, and reboot.
Observe first boot. The device shows one of three states on its attached display:
- A 6-digit pair code (large centred digits on a dark background) — the normal case. Enter this code in the portal to claim the device.
- "Requesting pairing code…" with a spinner — transient, should resolve to a pair code within a few seconds.
- "No network" / "Broker unreachable" — the device can't reach the portal. Check its network connection before proceeding.

Any of the three states means the OS image booted and paired correctly; only the third needs network troubleshooting before the device is usable.

Switching channels after install

The OS image's channel (stable / unstable) is baked in at build time and cannot be switched in place. Moving a device to a different image channel means re-imaging it from that channel's installer ISO — this is intentional, since an image channel change is a high-touch operation. The app's update channel (apt) can be switched without a re-image; see visionctl config on the device.