update docs
This commit is contained in:
@@ -8,6 +8,7 @@ operating guides run at the FDS console unless stated otherwise.
|
||||
| Guide | What you will learn |
|
||||
| --- | --- |
|
||||
| [Overview](../README.md) | How the computer, internal storage and cartridges fit together |
|
||||
| [Run on a Raspberry Pi 5](hardware-setup.md) | Wire HDMI/USB/power, prepare NVMe and SYSTEM, reach the first console, calibrate bays and diagnose hardware |
|
||||
| [Build and start FDS](getting-started.md) | Prepare the OS build workstation, create images and boot the emulator |
|
||||
| [Software and emulator walkthrough](workstation.md) | Build Void source packages, assemble cartridges, insert them and write USB media |
|
||||
| [Using cartridges](cartridges.md) | Inspect bays, run applications, resolve command names and eject safely |
|
||||
|
||||
+150
-2
@@ -4,14 +4,42 @@ FDS includes `dasungd` for the configured Dasung Paperlike 13K grayscale monitor
|
||||
The controller starts during early boot and remains supervised in the base system,
|
||||
including console-only use. No GUI or ENVIRONMENT cartridge is required.
|
||||
|
||||
For installation, disk preparation and first power-on, start with
|
||||
[Run FDS on a Raspberry Pi 5](hardware-setup.md).
|
||||
|
||||
The supplied profile uses the dedicated monitor's EDID and USB companion identity,
|
||||
with raw mode 1 and contrast 4 as startup defaults. It is specific to that monitor;
|
||||
do not use its identity as a blanket match for other CH340 USB devices.
|
||||
|
||||
## HDMI plus USB-C on the Pi
|
||||
|
||||
Use the Pi's **micro-HDMI output** for video to the monitor's HDMI input. Use a
|
||||
separate **USB-A-to-USB-C data cable** from a Pi host port to the monitor for
|
||||
controller access, and power the monitor with its supplied DC adapter. The
|
||||
Pi's own USB-C connector is its power input; it does not output USB-C video.
|
||||
See the [wiring table](hardware-setup.md#2-wire-hdmi-video-usb-control-and-power-separately),
|
||||
[official Pi display guidance](https://www.raspberrypi.com/documentation/computers/getting-started.html#display),
|
||||
and [DASUNG's power guidance](https://shop.dasung.com/pages/q-a).
|
||||
|
||||
HDMI video and USB controller access are separate checks. The daemon talks USB
|
||||
regardless of the video cable, but the HDMI-plus-USB arrangement still needs to
|
||||
expose the expected UART and companion bridge on this monitor. HDMI alone does
|
||||
not carry the daemon's control protocol. A charge-only cable or a USB-C lead
|
||||
connected only to a charger cannot provide host USB control.
|
||||
|
||||
The image currently supplies a firmware EDID override for 3200 × 2400 at about
|
||||
37 Hz, recorded on the original workstation. DASUNG says some HDMI hosts need
|
||||
27 Hz instead; that does not establish which mode the Pi and this cable will
|
||||
accept. The forced profile can prevent using the monitor's native HDMI mode
|
||||
list. Use the diagnostic procedure below if needed; neither Pi HDMI compatibility
|
||||
nor physical power-cycle recovery is recorded as passed yet.
|
||||
[Manufacturer HDMI note](https://shop.dasung.com/pages/dasung-paperlike-13k-the-worlds-first-13-3-inch-37hz-3k-e-ink-monitor).
|
||||
|
||||
## Inspect the controller
|
||||
|
||||
The controller's socket is restricted to root. From a root maintenance console
|
||||
on FDS:
|
||||
The controller's socket is restricted to root. Use the local `RECOVERY#` console
|
||||
described in [Enter recovery](recovery.md#enter-recovery); the ordinary `FDS>`
|
||||
account cannot access it. On FDS recovery:
|
||||
|
||||
```sh
|
||||
dasungd status
|
||||
@@ -40,6 +68,126 @@ Inspect `/run/log/dasungd/current` and the reported status. Discovery requires
|
||||
the configured DRM EDID and matching USB companion topology. An ambiguous match
|
||||
is rejected. Set `usb_path` only after identifying the intended device topology.
|
||||
|
||||
At `RECOVERY#`, start with:
|
||||
|
||||
```sh
|
||||
lsusb
|
||||
lsusb -t
|
||||
dasungd status
|
||||
dasungd query
|
||||
tail -80 /run/log/dasungd/current
|
||||
```
|
||||
|
||||
The existing profile expects UART `1a86:7523` alongside SPI bridge `1a86:5512`
|
||||
under the same hub. If neither appears, check monitor power, its USB data port,
|
||||
the cable and the Pi host connection. If only one appears, preserve the USB tree
|
||||
and log: the cable/input combination has not yet satisfied the current profile.
|
||||
Do not disable companion checks or match every CH340 device to hide the failure.
|
||||
|
||||
`status` separates `connected` from `responsive` and includes `usb_error`,
|
||||
`display_error`, `displays`, `rx_frames` and `last_rx_ms_ago`. `query` queues
|
||||
requests; run `status` again after replies arrive. Keepalive packets being sent
|
||||
are not themselves evidence that the monitor answered.
|
||||
|
||||
Capture the actual DRM connector names and EDID at `RECOVERY#`:
|
||||
|
||||
```sh
|
||||
mkdir /tmp/dasung-hdmi
|
||||
cat /proc/cmdline > /tmp/dasung-hdmi/cmdline.txt
|
||||
for fds_connector in /sys/class/drm/card*-*; do
|
||||
[ -f "$fds_connector/status" ] || continue
|
||||
fds_connector_name=${fds_connector##*/}
|
||||
printf '%s: ' "$fds_connector_name"
|
||||
cat "$fds_connector/status"
|
||||
cat "$fds_connector/modes"
|
||||
cp "$fds_connector/status" "/tmp/dasung-hdmi/$fds_connector_name.status"
|
||||
cp "$fds_connector/modes" "/tmp/dasung-hdmi/$fds_connector_name.modes"
|
||||
cp "$fds_connector/edid" "/tmp/dasung-hdmi/$fds_connector_name.edid"
|
||||
done
|
||||
```
|
||||
|
||||
Use a new directory for each capture and save it before shutdown using
|
||||
[machine diagnostics](internal-storage.md#save-and-retrieve-diagnostics).
|
||||
An empty EDID on a disconnected connector is expected. The `modes` file lists
|
||||
available resolution names, not proof of the active refresh rate or picture
|
||||
quality. With `drm.edid_firmware` active, the EDID you read may be the supplied
|
||||
override; capture again without it to learn what HDMI actually advertises.
|
||||
|
||||
The configured DRM serial is `L56051794302`. Native HDMI EDID might identify the
|
||||
display differently from the recorded USB-C profile. With `require_display=true`,
|
||||
an identity mismatch can leave USB control disconnected even when HDMI video
|
||||
works. Retain the native EDID, USB topology and errors for a deliberate profile
|
||||
update; do not silently remove identity checks. Config changes must ultimately
|
||||
be rebuilt into both early boot and base/recovery images. The read-only
|
||||
`/etc/dasungd.toml` is not a persistent settings editor.
|
||||
|
||||
## Try the monitor's own HDMI EDID
|
||||
|
||||
Use this when the stock forced timing gives a blank or unstable picture, or when
|
||||
temporarily connecting a different HDMI display. The override currently applies
|
||||
to connected DRM outputs without a connector qualifier, so attaching another
|
||||
screen while retaining it is not an independent native-mode test.
|
||||
|
||||
Follow the offline edit procedure below. In the disk's **single-line**
|
||||
`cmdline.txt`, remove only this token for the EDID experiment:
|
||||
|
||||
```text
|
||||
drm.edid_firmware=edid/dasung-paperlike13k-37hz.bin
|
||||
```
|
||||
|
||||
For verbose diagnosis with a USB keyboard and display console, a complete
|
||||
command line based on the current production template is:
|
||||
|
||||
```text
|
||||
console=tty1 rdinit=/init ro loglevel=7 vt.global_cursor_default=0 fds.boot=normal fds.debug=1
|
||||
```
|
||||
|
||||
For the serial boot mode, retain `console=ttyAMA10,115200` after `console=tty1`
|
||||
instead. Use `fds.boot=recovery` in place of `fds.boot=normal` when intentionally
|
||||
booting recovery; never append a second conflicting `fds.boot` option. Do not add
|
||||
`fds.emulator=1` on real hardware or replace stage0 with a Raspberry Pi OS
|
||||
`root=…` command line.
|
||||
|
||||
Reboot and repeat the DRM/USB capture. Removing the override allows the monitor's
|
||||
HDMI EDID to supply modes; it does **not** guarantee 27 Hz or fix missing USB
|
||||
control. Record any change in picture and controller status. Restore the saved
|
||||
command line to return to the shipped profile. Keep both captures so a future
|
||||
HDMI profile change can be based on observed timings and identity.
|
||||
|
||||
### Edit the BOOT command line offline
|
||||
|
||||
Shut FDS down and disconnect Pi power. Connect NVMe to the Linux workstation, or
|
||||
boot the separate maintenance SD and access the inactive NVMe there. Identify
|
||||
the same disk by model/serial used when flashing it. Mount only its first
|
||||
partition, labeled `FDS_BOOT`; FDS does not normally mount it at
|
||||
`/boot/firmware` as Raspberry Pi OS does.
|
||||
|
||||
On that **workstation or maintenance OS**, replacing the partition path below:
|
||||
|
||||
```sh
|
||||
lsblk -p -o NAME,MODEL,SERIAL,SIZE,TYPE,PARTLABEL,MOUNTPOINTS
|
||||
sudo mkdir -p /mnt/fds-boot
|
||||
sudo mount -o nosuid,nodev,noexec \
|
||||
/dev/disk/by-id/REPLACE_WITH_VERIFIED_NVME-part1 /mnt/fds-boot
|
||||
sudo cp -n /mnt/fds-boot/cmdline.txt /mnt/fds-boot/cmdline.before-hardware.txt
|
||||
sudoedit /mnt/fds-boot/cmdline.txt
|
||||
cat /mnt/fds-boot/cmdline.txt
|
||||
sudo umount /mnt/fds-boot
|
||||
```
|
||||
|
||||
Check the identity before the mount and stop on any failed step. If the partition
|
||||
was automounted, unmount that instance first. Keep `/mnt/fds-boot` dedicated to
|
||||
this operation. The no-clobber copy retains an existing backup; if repeating the
|
||||
experiment, inspect that backup and skip the copy step if it already exists.
|
||||
Do not assume an older backup contains your latest settings. Keep `cmdline.txt`
|
||||
on one line and record its final contents with the
|
||||
test session. Safely disconnect the enclosure before moving NVMe back to the Pi.
|
||||
|
||||
To undo the edit, mount the same verified partition again, restore
|
||||
`cmdline.before-hardware.txt` over `cmdline.txt`, and unmount before rebooting.
|
||||
These edits change the flashed copy only; they do not change the source images
|
||||
or their recorded hashes. Reflashing restores the image's original command line.
|
||||
|
||||
FDS uses the daemon for USB control. Its configuration disables the original
|
||||
workstation-specific display hotplug procedure. Video mode and cabling are part
|
||||
of the machine's boot/display configuration. The detailed protocol, build
|
||||
|
||||
@@ -13,8 +13,9 @@ are never used as cartridge identities.
|
||||
|
||||
The software boot path has passed on an ARM virtual machine using the actual
|
||||
FDS Pi kernel. That does not verify Pi firmware, NVMe, RP1, display output, USB
|
||||
power or physical boot speed. Those checks are deferred until the machine is
|
||||
assembled. M5 now provides an ordinary-user `FDS>` console with a temporary home
|
||||
power or physical boot speed. Those checks still require physical testing; follow
|
||||
the [real-hardware setup guide](../hardware-setup.md). M5 now provides an
|
||||
ordinary-user `FDS>` console with a temporary home
|
||||
and measured boot events. Password login remains locked; this is an intentional
|
||||
local single-user session. The M2 test VM separately offers a temporary root
|
||||
development shell. See [native init](init.md) and [performance reports](performance.md).
|
||||
|
||||
@@ -105,6 +105,8 @@ No world-writable USB rule, systemd unit, or runit service is installed.
|
||||
The video timing was confirmed on the original AMD workstation, **not on a Pi**.
|
||||
The original USB-C video connection is not a Pi cabling prescription. Pi connector,
|
||||
cable/adapter, mode acceptance, and picture stability require hardware validation.
|
||||
For the current HDMI video plus USB control procedure, including separate monitor
|
||||
power and a reversible native-EDID experiment, use the [display guide](../dasung.md).
|
||||
Desktop 2× scaling is separate from EDID timing; a console uses its own font size.
|
||||
|
||||
FDS configures `display.enabled=false` and `hotplug="none"`: the daemon handles
|
||||
|
||||
@@ -6,6 +6,9 @@ cartridges on another Linux distribution, use the [workstation guide](workstatio
|
||||
A prepared set of kernel, initramfs and SYSTEM images can be run on a Linux
|
||||
workstation without building the OS locally.
|
||||
|
||||
For the physical computer, follow [Run FDS on a Raspberry Pi 5](hardware-setup.md).
|
||||
It covers HDMI-plus-USB monitor wiring, both disks, EEPROM, first boot and recovery.
|
||||
|
||||
## Prepare the workstation
|
||||
|
||||
Use a normal user account, a Git checkout with its submodule metadata, and a
|
||||
@@ -63,7 +66,7 @@ inputs needed by the emulator:
|
||||
builds a SYSTEM with compilers, Git, Vim, debuggers and display diagnostics.
|
||||
Both profiles include WindowMaker and the Dasung daemon. The desktop starts on
|
||||
request. `make all` also assembles recovery, boot and internal-storage images;
|
||||
see [internal installation](internal-storage.md) when preparing a physical machine.
|
||||
see [real-hardware setup](hardware-setup.md) when preparing a physical machine.
|
||||
|
||||
## Start the emulator
|
||||
|
||||
@@ -76,7 +79,9 @@ out/workstation/fds-emulator --session out/my-emulator console
|
||||
```
|
||||
|
||||
If QEMU is installed directly on the workstation, omit `--qemu-runner`.
|
||||
The session directory must be new. At the `FDS>` prompt:
|
||||
Use a new session directory for the first run; after `stop`, you can `start` the
|
||||
same session again. Logs and DATA overlays are retained, and bays start empty.
|
||||
At the `FDS>` prompt:
|
||||
|
||||
```sh
|
||||
fds info
|
||||
|
||||
@@ -0,0 +1,392 @@
|
||||
# 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.
|
||||
@@ -7,6 +7,9 @@ persistent machine settings. The operating system itself lives on a removable
|
||||
SYSTEM cartridge. This guide covers preparing the internal disk and updating
|
||||
its settings from recovery.
|
||||
|
||||
For the complete first-install sequence, including cabling, EEPROM and a first
|
||||
bay map without DATA, use [the real-hardware setup guide](hardware-setup.md).
|
||||
|
||||
## Build the complete disk image
|
||||
|
||||
Build the component images first, in this order:
|
||||
|
||||
@@ -5,6 +5,10 @@
|
||||
FDS recovery is an independent maintenance system on internal storage. It can
|
||||
inspect a failed SYSTEM, check DATA and help prepare replacement cartridges.
|
||||
|
||||
For a machine whose bays have never been configured, follow
|
||||
[initial bay calibration](hardware-setup.md#8-install-the-first-bay-map-without-a-data-cartridge)
|
||||
at the root recovery console before relying on a DATA cartridge for settings.
|
||||
|
||||
## Build the recovery image
|
||||
|
||||
Use the prepared x86_64 build host described in [Your first build](getting-started.md).
|
||||
|
||||
@@ -5,6 +5,9 @@ Read the complete command error and its log before retrying. Build logs are in
|
||||
On FDS, `fds bay N`, `fds profiles` and `fds power status` report the relevant
|
||||
operation state. Append `--help` to a command for accepted options.
|
||||
|
||||
For physical Pi startup, use [first-boot troubleshooting](hardware-setup.md#when-the-first-boot-fails).
|
||||
For the Paperlike on HDMI plus USB, use [Dasung diagnostics](dasung.md#diagnose-a-connection-problem).
|
||||
|
||||
| Symptom | Resolution |
|
||||
| --- | --- |
|
||||
| Build disk is full | Stop builds and VMs; run `make clean-preview`, then `make clean`. See [retention rules](cleanup.md). |
|
||||
@@ -12,7 +15,7 @@ operation state. Append `--help` to a command for accepted options.
|
||||
| Bubblewrap/user namespace failure | Check that the host permits unprivileged namespaces. Run the check in [setup](getting-started.md); do not switch software builds to root. |
|
||||
| Void checkout is unprepared | Bootstrap the checkout using upstream xbps-src instructions, then select it with `--void-packages`. |
|
||||
| Stale generated overlay/source package | Compare the source and generated copy. Preserve independent edits, remove only that generated copy, and retry. Never overwrite tracked upstream templates. |
|
||||
| Output already exists | Use a new output directory, cartridge image, preview or emulator session. Creation does not overwrite existing outputs. |
|
||||
| Output already exists | Use a new output directory, cartridge image or preview. A stopped emulator session can be restarted; see below. |
|
||||
| Executable architecture or tree integrity error | Rebuild the source package and cartridge. FDS cannot run an invalid payload. |
|
||||
| A command is unavailable | Wait for `MOUNTED READ ONLY`, inspect `fds --json bay N`, and use its qualified command alias. Run `hash -r` after removal if Bash retained an old path. |
|
||||
| Empty or unconfigured physical bays | Run `fds topology` and calibrate the machine's bay map. Do not infer slots from disk names. |
|
||||
|
||||
Reference in New Issue
Block a user