fds-os/docs/hardware-setup.md

Run FDS on a Raspberry Pi 5

User manual · Dasung wiring and diagnostics · Recovery

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.

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.

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. 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.

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 before changing monitor identity or USB matching rules. DASUNG HDMI refresh-rate guidance.

3. Build a matching image set on the workstation

Complete Prepare the workstation, including bootstrap, smoke test and build checks. From the repository root, run the following commands sequentially, stopping if any fails:

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 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:

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 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:

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. To review the installed boot configuration, the official editor is:

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. 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 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. 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:

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:

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 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:

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:

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. 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.

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. 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:

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 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 and cartridge workflow.

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 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
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. 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 and copy the single line from 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.