fds-os/docs/eeprom.md

Pi 5 EEPROM configuration

Boot images · Recovery · User manual

The profile tool creates reviewable firmware/configuration files on the workstation. Applying them to a Pi is a separate maintenance operation. Preserve the machine's original firmware and configuration before changing them.

Preview a profile on the build workstation

From the repository root:

./tools/configure-pi-eeprom --profile production
./tools/configure-pi-eeprom --profile development

The first invocation downloads three checksum-pinned inputs into .host/eeprom/: the official configuration script, the Pi 5 preview firmware and its upstream license. Later calls verify and reuse them. FDS_OFFLINE=1 requires all inputs to exist and refuses a network download.

The command prints its new out/eeprom-PROFILE.* directory. It contains:

File	Purpose
base.bin	Exact input firmware retained unchanged
original.conf	Configuration to restore
configured.conf	Reviewed profile merged with the supplied settings
configured.bin	Real EEPROM image with the new configuration
rollback.bin	Same base firmware with original.conf restored
review.diff	Human-readable configuration changes
manifest.json	Input identity, selected settings and output SHA-256 hashes
LICENSE	Complete upstream tool and firmware notices

Default inputs are preview defaults, not a backup of your Pi. A rollback image restores the configuration supplied to this command on the supplied base firmware. It cannot reconstruct a different firmware version or settings that were never provided. Retain the actual machine's configuration and matching firmware input before applying anything to that machine.

Profile behavior

Setting	Production	Development
BOOT_ORDER	0xf6: NVMe, repeat	0xf16: NVMe, SD, repeat
BOOT_UART	0	1
NET_INSTALL_ENABLED	0	0
NET_INSTALL_AT_POWER_ON	0	0
POWER_OFF_ON_HALT	1	1
WAIT_FOR_POWER_BUTTON	0	0

Boot order is read from the right. Both profiles avoid scanning the twelve USB cartridges for firmware boot. Development retains an SD rescue path. Both disable network-install keyboard detection; Raspberry Pi documents that this detection adds USB initialization and enumeration work. Official bootloader configuration.

On Pi 5, the power-off setting requests PMIC standby on halt; the dedicated power button remains the wake mechanism. The wait setting leaves cold power-on boot enabled. After shutdown, check that attached power hardware follows the selected policy. Official power settings.

The source profiles are production.conf and development.conf. Review these files before choosing a profile.

Preserve the machine's settings

In a Raspberry Pi maintenance environment with the official EEPROM utilities, collect its configuration and version information before changing firmware:

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

Retain the matching original firmware image separately. The status report helps identify it; it is not a binary backup. Copy the saved inputs to the workstation, then prepare a new directory:

./tools/configure-pi-eeprom \
  --profile production \
  --base-image /absolute/path/to/original-pi5-firmware.bin \
  --current-config /absolute/path/to/pi-current.conf \
  --output-directory /absolute/path/to/new-eeprom-review

The base must be a regular 2 MiB Pi 5 image, not a device node. The output directory must not already exist. The helper preserves unrelated configuration lines and conditional sections. It replaces all occurrences of the six managed settings, including conditional overrides, with the selected profile's final [all] settings. Review that change in review.diff; the exact original conditional configuration remains in original.conf and rollback.bin.

The upstream parser reads the generated images back before success is reported. This checks file construction and configuration roundtrip, not hardware compatibility. No secure-boot key, fuse, customer signature or OTP setting is modified by this helper.

Apply and roll back

Apply the reviewed configuration from a Raspberry Pi maintenance environment with the official EEPROM utilities, then follow the updater's restart instructions.

sudo rpi-eeprom-config --apply ./configured.conf ./base.bin

The updater may program EEPROM immediately or schedule an update depending on its platform and update method. Follow its output and verify the resulting configuration/version after the required restart. To restore the supplied configuration on the same supplied firmware:

sudo rpi-eeprom-config --apply ./original.conf ./base.bin

If the firmware version itself changed, use the saved matching original firmware for the rollback operation. Keep the maintenance SD and an external EEPROM rescue route available; internal recovery cannot repair an EEPROM that prevents internal boot. The official EEPROM update and recovery guide describes that physical workflow.