felis/fds-os

Fork 0

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.

Table of Contents

Run FDS on a Raspberry Pi 5

1. Prepare the minimum hardware
2. Wire HDMI video, USB control and power separately
3. Build a matching image set on the workstation
4. Prepare USB maintenance and select SD boot
5. Write the two disks
6. Power on and reach the console
7. Verify HDMI and the Dasung controller
8. Install the first bay map without a DATA cartridge
9. Save evidence and shut down
When the first boot fails

Use a serial console when HDMI is unavailable

Verify the SD and maintenance paths on hardware

include_toc

include_toc
true

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 32 GB microSD card for boot files, recovery and persistent machine settings.
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 SD card reader for flashing.
A separate USB drive for Raspberry Pi OS maintenance; it is not the SYSTEM cartridge.

The current FDS installation uses two disks:

Disk	Contents	When it is needed
Native microSD slot	`FDS_BOOT`, `FDS_RECOVERY`, `FDS_INTERNAL`	Every FDS boot; also recovery without SYSTEM
USB SYSTEM cartridge	`FDS_SYSTEM`	Normal FDS operation

The roughly 1.75 GiB internal image fits comfortably on a 32 GB card. The remaining card capacity stays unallocated; FDS does not expand it or put SYSTEM there. PROGRAM, DATA and ENVIRONMENT cartridges can wait until the console works. A SYSTEM image alone contains no Pi firmware boot partition.

Use the Pi's native microSD slot during FDS operation. A USB card reader is fine for flashing on the workstation, but FDS deliberately rejects USB copies as persistent machine settings storage. Disconnect the old NVMe/HAT with Pi power removed; leaving another complete FDS internal disk attached causes ambiguous settings and recovery discovery. For the first boot, connect SYSTEM directly to a Pi USB port if the cartridge hubs are not ready. Changing hub wiring later requires 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. When upgrading an existing NVMe-era build, refresh any stale generated kernel overlay and run ./tools/build-kernel --rebuild once so the package includes the current SD driver requirements. 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 microSD card
`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.

When moving from the old NVMe setup, rebuild and flash SYSTEM as well as the internal SD image. The earlier machine-settings loader accepts NVMe only; changing just the boot card cannot update the loader on an old SYSTEM cartridge. The frozen 0.1.0 images retain that earlier behavior.

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. Prepare USB maintenance and select SD boot

On the workstation, use Raspberry Pi Imager to write Raspberry Pi OS (64-bit) for Raspberry Pi 5 to the separate maintenance USB drive. Select that drive carefully: Imager erases it. Set your own username/password and, if wanted, SSH access in Imager. fds-flash accepts FDS images; use Imager for Raspberry Pi OS.

Before overwriting your working rescue SD, boot that existing Raspberry Pi OS installation and record its EEPROM settings:

rpi-eeprom-config > pi-current.conf
rpi-eeprom-update > pi-eeprom-status.txt
sudo rpi-eeprom-config --edit

Save the reports outside the card being replaced. Change BOOT_ORDER in the editor, preserving unrelated settings. Boot order is read right to left:

Choice	Value	Behavior
Convenient maintenance	`0xf14`	USB first, then SD, repeat; plug in Raspberry Pi OS to override the FDS SD
SD first	`0xf41`	SD first, then USB, repeat; remove the SD to force a maintenance boot
FDS production	`0xf1`	SD only, repeat; no firmware USB scan and no USB rescue fallback

This EEPROM choice is independent of BOOT_MODE=production (HDMI console) and the CLI/development SYSTEM profile.

For this SD-plus-rescue-USB setup, 0xf14 is the convenient starting choice. With maintenance USB unplugged, firmware scans USB then boots FDS from SD. FDS SYSTEM is not firmware-bootable, so it cannot replace the maintenance OS in that sequence. Firmware USB scanning adds startup work; switch to SD-only only if that tradeoff and the external rescue procedure are acceptable.

Follow the editor/updater's restart instructions and read rpi-eeprom-config back after restart. The updater can also change firmware version; preserve the original configuration and matching firmware before applying changes, following EEPROM preparation and rollback. There is no requirement to blindly flash a new EEPROM release just to use SD. The offline FDS profile previews do not apply themselves to a board. No NVMe entry (6) or PCIE_PROBE=1 is required for the new storage arrangement, and the shipped SD configuration does not force external PCIe enablement.

Test the maintenance USB before erasing the working rescue SD: power off, remove that SD, unplug SYSTEM for this test, insert maintenance USB and power on. In Raspberry Pi OS, confirm findmnt -no SOURCE / and lsblk -p identify the USB root disk. Shut down cleanly before reconnecting the FDS media. A USB-first configuration also lets you later boot maintenance with the FDS SD still inserted, so its partitions can be inspected or repaired while inactive.

A USB fallback only applies while firmware is looking for boot files. It does not rescue a Linux boot that has already started and then hangs. The Pi 5 may also refuse USB boot with a 3 A supply until its power warning is acknowledged; Raspberry Pi documents a one-boot power-button override. A suitable 5 V/5 A supply provides a larger USB power budget for the attached devices. See official boot order and USB power guidance.

5. Write the two disks

On the workstation, build the native tools and run fds-flash once per disk:

make workstation-binaries
sudo ./out/workstation/fds-flash --image out/fds-internal.img
sudo ./out/workstation/fds-flash --image out/fds-system-cli.img

Each invocation lists disks by model, serial and capacity. Select the SD card reader for the internal image and a different USB disk for SYSTEM, review the plan, and enter the displayed erase phrase. Both writes replace the selected media. The tool refuses mounted/occupied disks and non-512-byte logical sectors; it writes, flushes, verifies readback and relocates the backup GPT automatically. Wait for VERIFIED before proceeding.

Use --device /dev/disk/by-id/... to preselect a whole disk while retaining interactive confirmation. The flashing guide covers dry runs and unattended mode with explicit image checksum and target identity.

Confirm the three internal partition labels and the USB's single FDS_SYSTEM label with lsblk -o NAME,PARTLABEL,FSTYPE,MOUNTPOINTS. Unmount any automatic desktop mounts after flashing, safely disconnect the disks, insert microSD into the native slot of the powered-off Pi, and connect exactly one SYSTEM. Remove the card reader and maintenance USB before the first FDS boot.

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. Keep the FDS SD inserted and maintenance USB unplugged so Raspberry Pi OS cannot be mistaken for an FDS boot.

The expected sequence is Pi firmware → kernel and stage0 from SD → 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_sd 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 SD 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 SD 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 SD 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 boot SD	Native slot seating, complete `fds-internal.img` rather than a partition payload, `FDS_BOOT` contents and SD-enabled EEPROM order; use maintenance USB
Firmware still reports NVMe timeouts	Its active boot order still contains `6`; read back the EEPROM configuration and remove NVMe from the selected order
Maintenance USB will not boot	Check `0xf14`/`0xf41`, Raspberry Pi OS image, USB power warning and whether a bootable SD took priority
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, native SD placement, matching rebuilt SYSTEM, partition layout and clean internal ext4; do not run DATA repair against the SD
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 SD, 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.

Verify the SD and maintenance paths on hardware

Record the card model/capacity, image hashes and observed results in the hardware session. These checks are still pending on the physical Pi:

With maintenance USB absent, cold-boot SD plus SYSTEM and confirm EROFS /, native s6, fds machine status reporting internal_sd, and working input.
Shut down, remove SYSTEM, then boot SD and enter recovery. Confirm the same storage source, install a measured settings bundle, save a diagnostic, and reboot to verify both persist. Normal loading must not require ext4 repair.
Shut down and attach maintenance USB. With 0xf14, keep FDS SD inserted and confirm Raspberry Pi OS runs from USB while the SD remains a separate disk. Use the offline BOOT edit procedure if display diagnosis is needed. Unmount any SD filesystems before shutdown.
Remove maintenance USB after shutdown, restore SYSTEM and confirm normal FDS boot. Recheck the settings and diagnostic saved in step 2.

Do not remove the SD while FDS is running: it is also the recovery and settings medium. An SD card does not remove the need for backups or controlled power-off.

FDS/OS

Home · Overview · All pages

Start here

Use the computer

Install and maintain

Build and contribute

Home · All pages · Edit the wiki · Source repository

Maintained directly in the fds-os.wiki repository. Historical acceptance applies only to the source and artifacts identified in each record.