rk1/README.md

# Turing RK1 media-center image

This project now produces a complete, flashable home-theater image for a
Turing RK1 on a Jetson Orin Nano/NX-compatible HDMI carrier. It uses Debian 13
(Trixie) userspace on Armbian Community with the Rockchip vendor 6.1.115 kernel,
then starts Kodi directly on DRM/KMS through GBM—there is no desktop or display
manager in the way.

The intentionally non-obvious choice is the kernel. Armbian also offers newer
mainline kernels, but the vendor 6.1 branch is currently the coherent path for
RK3588 HDMI, RKMPP VPU, RGA, and RKNPU support. “Newest kernel number” and “most
complete RK3588 appliance” are not the same target.

## Ready artifact

- `dist/rk1-media-20260817-r4-trixie-vendor-6.1.115-turing-rk1-emmc.img.xz`
- SHA-256: `bb4fc337f1293fb2b2423b34e8fff370ed69e9ec8709c7da87fdfeea2a516f04`
- Compressed size: 591,529,876 bytes; raw image: 4 GiB
- Initial target: whole eMMC (the included guarded helper can then move `/`
  to NVMe while retaining RK1 U-Boot and `/boot` on eMMC)
- Login: `rkadmin` using the sole public key whose fingerprint is recorded in
  the adjacent manifest
- Hostname after first boot: `rk1-media.local`

There is no password login and no root login. The image contains no SSH private
key and no image-time SSH host key. Unique host keys are generated before SSH
can start. `rkadmin` has passwordless sudo because its only authentication path
is a supplied public key.

Read [FLASHING.md](FLASHING.md) before writing eMMC. The included flasher
requires the target path twice, rejects mounted targets, verifies the compressed
image, and reads the written bytes back.

## Hardware stack

- GPU: Panthor kernel DRM plus Mesa Panfrost/PanVK (OpenGL ES/OpenGL/Vulkan).
- Video: matched RKMPP decode/encode and RGA zero-copy/scaling stack isolated
  under `/opt/rkmedia`; system FFmpeg libraries are not replaced.
- Kodi: direct GBM/GLES appliance service on tty1, running as a locked `kodi`
  user rather than root.
- Decode: H.264, HEVC, VP9, AV1, and MJPEG RKMPP paths.
- Encode: H.264, HEVC, and MJPEG RKMPP paths.
- NPU: pinned RKNN Runtime 2.3.2, RK3588 model, per-core inference test, and
  local diagnostics.
- HDMI support: exact `rk3588-turing-rk1.dtb`, HDMI PHY/audio nodes, Panthor
  overlay, ALSA, CEC utilities, and IR keymap support.

The open Panthor/Mesa GPU route does not provide Mali OpenCL. Proprietary
libMali/OpenCL requires the mutually incompatible Mali kbase stack; it is not
mixed into this media image. The RK3588 NPU remains available through RKNN.

## Build it again

On an ARM64 build host:

```bash
cd /home/ubuntu/rk1-media-image
./build.sh --ssh-public-key /absolute/path/to/authorized_keys
```

The key file can hold multiple plain OpenSSH public-key lines. Private keys and
authorized-key options are rejected. The build needs no root access, mounts, or
loop devices. It verifies/downloads locked inputs, verifies 140 locked Debian
dependency packages, reproducibly repacks the Kodi bundle, installs the RKNN
runtime into the filesystem, expands the GPT/ext4 image, and emits checksums and
a manifest under `dist/`.

Validation:

```bash
./tests/run-static.sh
./tests/validate-image.sh \
  dist/rk1-media-20260817-r4-trixie-vendor-6.1.115-turing-rk1-emmc.img
```

The produced image uses a checksum-locked Armbian release asset. `armbian/`
also contains a source-level base-image recipe pinned to the Armbian framework,
kernel, U-Boot, RKBin, and firmware commits. Archive package versions are
captured separately; true byte-for-byte source rebuilds additionally require a
package-repository snapshot.

## First boot

Connect Ethernet and HDMI before powering on. Armbian expands the root
filesystem, creates the unique machine/SSH identity, and makes SSH available.
An offline one-shot service then installs the 141-package graphics/media bundle,
reloads device permissions, enables Avahi, and starts Kodi. This can take a few
minutes; do not remove power while `rk1-media-provision.service` is active.

```bash
ssh rkadmin@rk1-media.local
systemctl status rk1-media-provision.service kodi-rk.service
journalctl -u rk1-media-provision.service -u kodi-rk.service -b
```

Revision r4 includes the SSH runtime-directory correction introduced in r2,
fixes first-boot offline APT acquisition and Kodi service ordering, and contains
only the dedicated `rk1-media` public key. Its fingerprint is
`SHA256:12b/wcqo8/yLfZ2OnLYga9baOt6tIlOSVZWrnjXtuN4`. The superseded
unrevisioned image could leave port 22 closed, while r3 could fail during its
offline package transaction and then deadlock while starting Kodi. Neither
should be used for a new flash; the repaired live r3 system does not need to be
reflashed.

The provisioner retries on the next boot if it does not reach its success
marker. Platform kernel/DTB/U-Boot packages are held; Debian security updates
are automatic, while platform/media upgrades require an intentionally tested
image rebuild.

Continue with [ACCEPTANCE.md](ACCEPTANCE.md). Static validation cannot prove
the carrier’s physical HPD/DDC/TMDS path, the TV’s EDID, DRM-master acquisition,
or sustained 4K acceleration.

## Move the root filesystem to NVMe

Flash and boot the image from eMMC first. After first-boot provisioning has
completed, the image includes a guarded migration helper that keeps U-Boot and
`/boot` on eMMC, creates a fresh ext4 filesystem on the selected NVMe, copies
the live root, and validates the UUIDs, filesystem, `fstab`, and boot environment
before allowing a reboot:

```bash
findmnt -no SOURCE,FSTYPE /
lsblk -e7 -o NAME,PATH,SIZE,TYPE,FSTYPE,MOUNTPOINTS,MODEL,SERIAL
sudo rk1-media-migrate-root-to-nvme \
  --target /dev/nvme0n1 \
  --serial EXACT_SERIAL_FROM_LSBLK
sudo systemctl reboot
```

The selected NVMe is erased. Do not use Armbian's `split-emmc` mode for this
workflow: the eMMC is the boot medium and rollback copy. After reboot,
`findmnt /` should report the NVMe partition while `/boot` and
`/media/boot-media` resolve to eMMC. See [FLASHING.md](FLASHING.md) for the
rollback command.

## Project layout

- `image/`: rootless raw-image composition and first-boot services.
- `media/`: deterministic release repack and fully pinned native source recipe.
- `runtime/`: RKNN runtime installer, NPU test, hardware self-test, diagnostics.
- `packages/`: exact Debian dependency integrity lock and fetcher.
- `armbian/`: source-pinned Armbian base-image recipe.
- `tests/`: package, dependency, runtime, and loopless image validation.
- `scripts/`: locked input fetcher and guarded eMMC flasher.

See [DESIGN.md](DESIGN.md) for pins, trust boundaries, and tradeoffs.