fds-os/docs/eeprom.md

Pi 5 EEPROM configuration

Boot images · Recovery · Implementation ledger

M12 now provides an offline configuration workflow using the pinned official Raspberry Pi tool and a real Pi 5 firmware image. The host checks passed; application to a physical Pi, boot order, PMIC behavior and timing remain deferred. tools/configure-pi-eeprom only creates files. It never reads or writes a hardware EEPROM, invokes a firmware updater, or reboots a machine.

Preview a profile on the build workstation

From the repository root:

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

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. These settings do not establish a measured FDS boot improvement. 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. Whether the assembled computer and attached hardware behave as intended still needs a physical test. Official power settings.

The source profiles are production.conf and development.conf. No GPIO wake option or unmeasured HDMI tuning is added.

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 during physical testing

This step is deliberately outside the host/VM acceptance run. Use the Pi's maintenance environment and the official installed EEPROM utilities. Once the reviewed files and saved original inputs are available there, the upstream configuration interface is:

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. FDS has not yet tested it on your Pi.

Inputs, dependencies and software evidence

The input lock is inputs.json, pinned to raspberrypi/rpi-eeprom commit 2fee426f27b6c54d3f5b6f36efd9a2fe1286a45d and Pi 5 preview firmware pieeprom-2026-09-12.bin. Every download is SHA-256 checked; a changed cached input is rejected. The official source tool is stored unchanged in the cache. Void's tracked source remains unchanged.

The host workflow uses existing Python and curl. It does not add a target daemon, package or Rust dependency. The upstream parser's optional signing dependencies are not needed for configuration-only operations.

make eeprom-test passed production/development roundtrips, unchanged firmware payloads, repeatable binary output, refusal to overwrite an existing directory, preservation of custom settings, exact rollback of conditional settings, and rejection of malformed images, device nodes and oversized configuration files. Initial evidence is out/m12-eeprom.zi144zib/, with log out/logs/m12-eeprom-check.log. The complete local release acceptance is recorded in M12 validation.