Table of Contents

Pi 5 EEPROM configuration

include_toc

include_toc
true

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
./tools/configure-pi-eeprom --profile maintenance

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	Maintenance
`BOOT_ORDER`	`0xf1`: SD, repeat	`0xf41`: SD, USB, repeat	`0xf14`: USB, SD, repeat
`BOOT_UART`	`0`	`1`	`1`
`NET_INSTALL_ENABLED`	`0`	`0`	`0`
`NET_INSTALL_AT_POWER_ON`	`0`	`0`	`0`
`POWER_OFF_ON_HALT`	`1`	`1`	`1`
`WAIT_FOR_POWER_BUTTON`	`0`	`0`	`0`

Boot order is read from the right. Production avoids firmware USB scanning. Development tries SD first; remove a bootable SD to force USB rescue. Maintenance lets a Raspberry Pi OS USB drive override FDS while the SD remains inserted for inspection or repair. Leave that USB unplugged for normal FDS operation. The FDS SYSTEM cartridge supplies userspace after stage0, not firmware boot files.

Firmware fallback cannot recover a hang after Linux has started. USB-first scans also add startup work; none of these profiles establishes a measured boot time. All disable network-install keyboard detection and omit NVMe from boot order. The Pi may need acknowledgement of its USB power warning with a 3 A supply. Use the hardware setup procedure and 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, development.conf and maintenance.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 maintenance USB and a spare SD for the external EEPROM rescue procedure available; internal recovery cannot repair an EEPROM that prevents internal boot. The official EEPROM update and recovery guide describes that physical workflow.

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.