Table of Contents
include_toc
| include_toc |
|---|
| true |
Pi 5 EEPROM configuration
Development reference and historical context. For current operating instructions, use the user manual. Acceptance applies only to the source and artifacts identified in each record.
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
./tools/configure-pi-eeprom --profile maintenance
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 | 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. Whether the assembled computer and attached hardware behave as intended still needs a physical test. Official power settings.
The source profiles are production.conf, development.conf and maintenance.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 USB and, for EEPROM recovery, a spare 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.
FDS/OS
Start here
Use the computer
- Use cartridges and run programs
- DATA and persistent files
- WindowMaker and FDS Control
- Dasung Paperlike display
Install and maintain
- Flash disk images
- Internal storage and machine settings
- Pi 5 EEPROM configuration
- Recovery and rollback
- Verify a release
- Reclaim build space
- Troubleshooting
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.