fds-os/docs/hardware-setup.md

# Run FDS on a Raspberry Pi 5

[User manual](README.md) · [Dasung wiring and diagnostics](dasung.md) · [Recovery](recovery.md)

This guide takes a partly assembled Pi from prepared disks to its first FDS
console, then adds monitor control and physical bay numbering. Start with one
SYSTEM cartridge; the twelve-bay assembly and a desktop are not prerequisites.
These are instructions for physical testing, not a record of a successful Pi
boot. Existing QEMU results do not establish HDMI compatibility, USB power
stability, monitor recovery or physical boot times.

Follow steps 1–6 to reach the first console. Steps 7–9 check the monitor, install
bay mappings and save results. If the screen stays blank, jump to
[first-boot troubleshooting](#when-the-first-boot-fails).

Commands marked **workstation** run on the Linux build computer, **maintenance
OS** means a separate Raspberry Pi OS rescue installation, and **FDS** means the
console on the Pi. FDS does not start SSH or networking automatically.

## 1. Prepare the minimum hardware

You need:

- A Raspberry Pi 5 with cooling and a suitable USB-C power supply.
- A PCIe NVMe adapter/HAT and NVMe drive for internal boot and recovery storage.
- One USB storage device for SYSTEM, a USB keyboard, and the Paperlike 13K.
- HDMI video cabling, a USB-A-to-USB-C **data** cable for the monitor controller,
  and the monitor's supplied power adapter.
- A Linux workstation and an NVMe enclosure/adapter for writing the disks.
  A separate maintenance microSD card is useful for EEPROM and display diagnosis.

The current FDS installation uses **two disks**:

| Disk | Contents | When it is needed |
| --- | --- | --- |
| Internal PCIe NVMe | `FDS_BOOT`, `FDS_RECOVERY`, `FDS_INTERNAL` | Every FDS boot; also recovery without SYSTEM |
| USB SYSTEM cartridge | `FDS_SYSTEM` | Normal FDS operation |

PROGRAM, DATA and ENVIRONMENT cartridges can wait until the console works.
If only microSD is connected today, use it for Raspberry Pi OS maintenance and
cable checks. This guide's complete FDS installation requires NVMe: persistent
machine settings deliberately accept PCIe NVMe only. Writing the internal image
to microSD or leaving NVMe in a USB enclosure does not provide that supported
layout. A SYSTEM image alone contains no Pi firmware boot partition.

Connect or reseat the PCIe ribbon and HAT with power disconnected, following the
adapter's instructions. For the first boot, attach SYSTEM directly to a Pi USB
port if the cartridge hubs are not ready. Changing the hub wiring later requires
a fresh bay calibration.

## 2. Wire HDMI video, USB control and power separately

The Pi's micro-HDMI ports are **video outputs**; the monitor receives that video.
The Pi 5's USB-C socket supplies power to the Pi and does not provide DisplayPort
Alt Mode video. A USB-C display cable alone cannot replace HDMI on this board.
See [Raspberry Pi's display connection guide](https://www.raspberrypi.com/documentation/computers/getting-started.html#display).

| Connection | Purpose |
| --- | --- |
| Pi micro-HDMI output → Paperlike HDMI video input | Picture; use the correct HDMI connector sizes for both ends |
| Pi USB-A host port → Paperlike USB-C data port | Candidate USB control path for `dasungd`; verify enumeration in step 7 |
| Supplied Dasung power adapter → monitor power input | Monitor power, separate from USB control |
| Pi power supply → Pi USB-C power input | Pi power |

Use the monitor's HDMI input selection, if its controls offer one. A charging-only
USB cable will not expose the controller. This HDMI-plus-USB arrangement is the
route to test; whether this unit exposes both controller interfaces while HDMI
is active still needs observation. HDMI can show a picture even when USB control
is missing, and USB replies do not prove the picture is correct.

Use the supplied Dasung DC power connection: the manufacturer specifically warns
that ordinary USB power is insufficient for reliable 13K operation.
[DASUNG power guidance](https://shop.dasung.com/pages/q-a).
For Pi 5, a supply supporting 5 V/5 A permits a larger USB power budget; a 3 A
supply limits downstream peripherals to 600 mA. Use powered hubs for the cartridge
assembly rather than budgeting the monitor and twelve cartridges from the Pi.
[Raspberry Pi power guidance](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#power-supply).

The shipped FDS boot configuration forces this monitor's recorded 3200 × 2400
timing at about 37 Hz. That timing was established on the original workstation.
DASUNG documents that some HDMI hosts instead use 27 Hz. FDS's forced EDID means
you should not assume automatic fallback. If HDMI is blank or unstable, use the
[native-EDID diagnostic boot](dasung.md#try-the-monitors-own-hdmi-edid) before
changing monitor identity or USB matching rules.
[DASUNG HDMI refresh-rate guidance](https://shop.dasung.com/pages/dasung-paperlike-13k-the-worlds-first-13-3-inch-37hz-3k-e-ink-monitor).

## 3. Build a matching image set on the workstation

Complete [Prepare the workstation](getting-started.md#prepare-the-workstation),
including bootstrap, smoke test and build checks. From the repository root, run
the following commands **sequentially**, stopping if any fails:

```sh
make rootfs PROFILE=cli
make system-card PROFILE=cli
make recovery
make initramfs
make boot-volume BOOT_MODE=production
make internal-image
```

This builds one normal SYSTEM and independent recovery, then combines the current
kernel, initramfs and recovery into the internal disk. The CLI rootfs includes
the matching kernel modules, native s6 and the base Dasung controller. Rebuild
the complete sequence after a source change; existing convenience links in
`out/` can otherwise point to components from different builds.

`BOOT_MODE=production` puts the interactive console on the HDMI display with
USB keyboard input. It is suitable for first bring-up without a serial cable.
`PROFILE=development` is a separate choice that adds compilers and debugging
tools to SYSTEM; it does not select the console transport. The smaller CLI
profile is sufficient here, and includes the optional desktop too.

| Output | Write it to |
| --- | --- |
| `out/fds-internal.img` | Whole NVMe disk |
| `out/fds-system-cli.img` | Whole USB SYSTEM disk |
| `out/fds-boot.img` | Raw FAT partition payload; already included in the internal image |
| `out/fds-recovery.img` | Raw EROFS partition payload; already included in the internal image |

Do not write the last two files as whole disks. `make all` builds additional
profiles and release tooling; it is unnecessary for this first-boot image set.
Use [cleanup](cleanup.md) to review retained build trees when space is tight.

Record the inputs before flashing. On the **workstation**, choose a new session
directory and retain the printed build logs/manifests with it:

```sh
mkdir out/hardware-first
cp tests/hardware/session-template.json out/hardware-first/session.json
git rev-parse HEAD > out/hardware-first/source-commit.txt
git diff --binary HEAD > out/hardware-first/source-changes.patch
./tools/version > out/hardware-first/build-version.txt
sha256sum out/fds-internal.img out/fds-system-cli.img \
  out/fds-boot.img out/fds-recovery.img out/fds-initramfs.img \
  out/kernel/boot/kernel_2712.img > out/hardware-first/images.sha256
cp out/boot-volume/files/cmdline.txt out/hardware-first/cmdline-built.txt
```

Keep any untracked build inputs separately too. These checksums identify your
local build; they are not a release signature. For a downloaded release, follow
[signature verification](releases.md) and use its matching complete image set.
The historical `0.1.0` release and its acceptance records remain separate from
new local builds.

## 4. Check NVMe boot configuration

If the Pi already boots from this NVMe adapter, first record its EEPROM settings;
changing firmware is not a prerequisite just to try FDS. Otherwise, use a
separate Raspberry Pi OS maintenance microSD with the official EEPROM utilities.
Keep that rescue medium available throughout bring-up.

In the **maintenance OS**, before editing:

```sh
rpi-eeprom-config > pi-current.conf
rpi-eeprom-update > pi-eeprom-status.txt
```

Copy these files to the workstation and preserve the matching original firmware
as described in [EEPROM preparation and rollback](eeprom.md). To review the
installed boot configuration, the official editor is:

```sh
sudo rpi-eeprom-config --edit
```

For initial FDS bring-up, `BOOT_ORDER=0xf16` means NVMe first, SD fallback, then
repeat (read from the right). A non-HAT+ NVMe adapter may also require
`PCIE_PROBE=1`; follow the adapter's instructions and the
[official PCIe boot procedure](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#boot-from-pcie).
Preserve unrelated board settings, follow the updater's restart instructions,
then read the configuration back. FDS already supplies `dtparam=pciex1` in
`config.txt`; EEPROM discovery and the kernel's PCIe enablement are separate.

The [FDS EEPROM development profile](eeprom.md#profile-behavior) also keeps SD
fallback and enables firmware UART logging. Its offline preview is not a backup
of your board and does not apply itself. Do not switch to NVMe-only production
boot order until the rescue and normal boot paths have been checked.

## 5. Write the two disks

On the **workstation**, follow the complete
[guarded disk-writing procedure](internal-storage.md#install-the-internal-disk).
It includes disk identification by model/serial, an explicit erase confirmation,
readback, and backup-GPT relocation. Run it separately for these assignments:

| Pass | `fds_image` | `fds_disk` |
| --- | --- | --- |
| Internal disk | `$PWD/out/fds-internal.img` | The verified NVMe enclosure's whole-disk `/dev/disk/by-id/…` path |
| SYSTEM | `$PWD/out/fds-system-cli.img` | A different, verified USB cartridge's whole-disk `/dev/disk/by-id/…` path |

Both writes erase the selected disk. Follow all checks in that procedure; a
`-part1` path is not a whole-disk destination. The disks must use 512-byte logical
sectors and be at least as large as their respective images.

Confirm the three internal partition labels and the USB's single `FDS_SYSTEM`
label after writing. Safely disconnect the disks, install NVMe on the powered-off
Pi, and connect exactly one SYSTEM. Do not leave the NVMe enclosure connected as
a duplicate source of FDS partitions.

## 6. Power on and reach the console

Power the monitor and any required hub, attach video, USB control, keyboard and
SYSTEM, then power the Pi. Remove the maintenance SD for this attempt so an SD
fallback cannot be mistaken for an FDS boot.

The expected sequence is Pi firmware → kernel and stage0 from NVMe → read-only
SYSTEM from USB → native s6 → `FDS>`. The production image is quiet, so a missing
splash or scrolling kernel log is not by itself a failure. At **FDS**, run:

```sh
fds info
cat /usr/share/fds/image-profile
cat /proc/cmdline
findmnt -no SOURCE,FSTYPE,OPTIONS /
ps -p 1 -o pid,comm,args
fds machine status
fds bays
fds topology
fds boot-profile
```

Expect the intended version/profile, an EROFS root mounted read-only, and native
s6 as PID 1. `fds machine status` should report `internal_nvme` for valid internal
settings; `image_defaults` means settings loading fell back and needs diagnosis.
An empty initial map still legitimately reports `UNCONFIGURED` bays. Stage0
discovers SYSTEM by its GPT partition label before bay mapping, so that does not
prevent reaching the console. Do not unplug the running SYSTEM even if it has
not yet acquired a bay number.

If no SYSTEM is found, stage0 waits for media. Its prompt accepts `list`,
`rescan`, `recovery`, `reboot` and `poweroff`; inserting one valid SYSTEM should
resume boot. Two matching SYSTEMs are ambiguous: remove the unintended one.
This prompt is an early-boot command interface, not Bash.

The normal console is the ordinary `fds` user (UID 1000), with a temporary home
and locked account passwords. For root diagnostics, shut down with `fds poweroff`,
remove SYSTEM after shutdown, boot again and type `recovery` at stage0's
missing-SYSTEM prompt. The independent recovery image opens `RECOVERY#`.
Use that root console for monitor diagnostics and initial machine configuration;
there is no default root password to enter at `FDS>`.

## 7. Verify HDMI and the Dasung controller

At **`RECOVERY#`**, with both HDMI and USB data connected:

```sh
lsusb
lsusb -t
dasungd status
dasungd query
tail -80 /run/log/dasungd/current
```

The existing profile expects UART `1a86:7523` and companion bridge `1a86:5512`
under the same USB hub, plus a connected DRM output matching the configured
monitor serial. Query again and check status after replies arrive: `connected`
alone is not the same as `responsive`. See [Dasung diagnostics](dasung.md) for
DRM capture, blank HDMI, missing USB interfaces and the 37 Hz override.

Confirm visible text entry, a refresh, and parameter readback separately. Once
basic operation works, test a **monitor-only** off/on cycle while retaining Pi
power, SYSTEM and hub power; record the picture, USB re-enumeration and daemon
reconnection. This is not permission to unplug writable storage. A passing VM
controller test cannot establish physical monitor recovery.

## 8. Install the first bay map without a DATA cartridge

Stay at **`RECOVERY#`**. Keep the hubs in their intended final ports. Insert one
identifiable test USB device at a time and record `fds topology` for each physical
slot. Test USB 2 and USB 3 connections separately where supported. Map only the
slots currently assembled; unmapped slots can remain unconfigured.

Create editable settings in RAM:

```sh
fds machine export /tmp/my-machine
cat /tmp/my-machine/machine.toml
fds topology
```

Recovery includes Bash but no full-screen editor. Use a here-document to enter
the measured map. **The path below is a syntax example, not a Pi port identity**:
replace it and the port number with your actual observation before installing.
If the observed device path ends in `:usb2/1/3`, the parent hub ends in
`:usb2/1` and downstream port `3` maps to your chosen bay number:

```sh
cat > /tmp/my-machine/bays.toml <<'EOF'
[first_usb2]
hub = "platform/REPLACE_WITH_OBSERVED_CONTROLLER:usb2/1"
[first_usb2.ports]
3 = 1
EOF
```

Add separate groups for the measured USB 3 aliases and other hubs following
[the mapping reference](developer/cartridges.md#calibrate-the-physical-bay-map).
Do not map keyboard/monitor connections as cartridge bays or copy the emulator's
map. Validation checks syntax and conflicts; only your insertion tests establish
that a mapping matches the physical labels.

```sh
cat /tmp/my-machine/bays.toml
fds machine validate /tmp/my-machine
fds machine install /tmp/my-machine
fds reboot
```

Installation writes the complete settings bundle to NVMe and retains the previous
one; it does not change the active mapping during this boot. With SYSTEM still
absent, select `recovery` again after reboot. Verify `fds machine status`, then
`fds bay 01` as you move the test device through the configured slots. Use
`fds eject N` and wait for SAFE before removing storage managed in a mapped bay.

Later, [export a backup and update settings from DATA](internal-storage.md#update-settings-from-recovery).
Do not reflash the whole NVMe merely to change bay numbering: that would replace
saved settings and diagnostics. For normal boot, shut down, insert SYSTEM,
and power on again.

## 9. Save evidence and shut down

At **`RECOVERY#`**, collect a fresh capture and explicitly save it to NVMe before
losing the RAM filesystem:

```sh
bash /usr/share/fds/capture-hardware /tmp/hardware-first
cat /tmp/hardware-first/status.tsv
dasungd status > /tmp/hardware-first/dasung-status.json
cp /run/log/dasungd/current /tmp/hardware-first/dasung.log
tar -C /tmp -czf /tmp/hardware-first.tar.gz hardware-first
fds machine store hardware-first.tar.gz /tmp/hardware-first.tar.gz
fds power status
fds poweroff
```

Stored names must be new and files must be at most 16 MiB. The collector's
`SHA256SUMS` covers its own original outputs; the two manually added Dasung files
are additional evidence. Retrieve the archive later with
`fds machine fetch hardware-first.tar.gz /tmp/retrieved-hardware-first.tar.gz`
from recovery, then copy it to healthy, explicitly activated DATA and safely eject.
This capture describes the recovery boot; collect another capture in normal FDS
on DATA when that path is ready. `/tmp`, `/run`, logs and the normal home are
otherwise lost at shutdown.

Fill the workstation session record with observed results, wiring, EEPROM version,
image hashes and remaining failures. Leave unperformed cases `not_run`. Log
events measure software stages; physical power-on-to-picture and power-off timing
need an external observation. Follow [physical acceptance testing](developer/stress-testing.md#physical-acceptance-sequence)
when the complete assembly is ready.

Use `fds poweroff` and wait for shutdown before disconnecting power or swapping
SYSTEM. If shutdown is blocked, inspect `fds power status` and resolve the
reported storage problem. An E-Ink picture can remain visible after power is
removed, so the retained picture is not proof that the Pi is still running.
After basic console/display checks, try the [optional desktop](desktop.md) and
[cartridge workflow](cartridges.md).

## When the first boot fails

| Observation | Next check |
| --- | --- |
| Firmware cannot find NVMe | Adapter/ribbon seating, supply, EEPROM boot order, and conditional `PCIE_PROBE=1`; return to the maintenance SD |
| Stage0 says SYSTEM is missing | Whole GPT SYSTEM image, exactly one `FDS_SYSTEM`, USB power and `list`; bay calibration is not required at this stage |
| HDMI is blank or unstable | Monitor input/power, cable connector sizes, then [native HDMI EDID](dasung.md#try-the-monitors-own-hdmi-edid) or the serial console below |
| Kernel text appears but keyboard cannot reach a prompt | Check whether `BOOT_MODE=development` made UART the primary console |
| Picture works, `dasungd` does not | USB data cable, both USB IDs, DRM serial, permissions and daemon log; see [Dasung diagnostics](dasung.md) |
| `fds bays` is unconfigured | Complete step 8 using physical topology observations |
| `fds machine status` uses image defaults | Check the reported reason, NVMe transport, partition layout and clean internal ext4; do not run DATA repair against internal NVMe |
| USB resets or disappears under load | Reduce attached devices and check the Pi, monitor and hub supplies separately |

### Use a serial console when HDMI is unavailable

Use the Pi 5's dedicated debug UART connector and a compatible 3.3 V UART/debug
probe, following the [official UART documentation](https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-uarts).
Connect the probe's host USB to the workstation, then open its serial terminal at
**115200 baud, 8 data bits, no parity, 1 stop bit, no flow control**. This is a
separate connection from the monitor's USB cable. Save the terminal log.

For an initial, still-disposable disk build, replace step 3's boot mode with
`make boot-volume BOOT_MODE=development` before `make internal-image`. This
enables verbose kernel output and selects `ttyAMA10` as the primary userspace
console. The development EEPROM profile separately enables firmware UART output.
Boot mode does not grant root; select recovery for a root shell.

For an already provisioned NVMe, use the
[offline BOOT edit procedure](dasung.md#edit-the-boot-command-line-offline) and
copy the single line from [cmdline-development.txt](../image/pi5/cmdline-development.txt)
into the disk's `cmdline.txt`; preserve any deliberate native-EDID diagnostic
change. This avoids overwriting settings to switch consoles. Restore the saved
command line to return to display/keyboard operation after debugging.