When deploying a single-board computer for a headless smart home node, a digital signage display, or an industrial IoT gateway, graphical user interfaces are often an unnecessary overhead. For engineers and DIY enthusiasts working with Raspberry Pi OS, the sudo raspi-config utility remains the undisputed king of system provisioning. However, treating the Raspberry Pi config command as just a simple menu for enabling SSH or changing the hostname leaves massive automation and performance-tuning capabilities on the table.

In this comprehensive setup guide, we will dissect the architecture of raspi-config, explore hidden hardware toggles specific to the Raspberry Pi 4 and Pi 5, and demonstrate how to leverage its non-interactive mode for fleet deployments.

The Anatomy of the Raspberry Pi Config Command

At its core, the Raspberry Pi config command is not a compiled binary; it is a massive, continuously maintained Bash script located at /usr/bin/raspi-config. It relies on whiptail to generate the familiar blue-and-grey Text User Interface (TUI) dialog boxes over your SSH or serial console session.

Because it is a script, it acts as an abstraction layer over dozens of underlying Linux subsystems. When you toggle an option in the TUI, the script is actively editing configuration files, enabling systemd services, modifying device tree overlays in the firmware partition, and installing missing dependencies via apt. According to the official RPi-Distro GitHub repository, the script is updated frequently to accommodate new silicon features, such as the RP1 southbridge architecture introduced with the Raspberry Pi 5.

Navigating the TUI: Bookworm OS and Pi 5 Specifics

If you are running the latest Debian Bookworm-based Raspberry Pi OS, the underlying file structure has shifted. Historically, boot configurations lived in /boot/config.txt. Today, the raspi-config tool correctly targets /boot/firmware/config.txt to align with standard Linux filesystem hierarchies. Understanding this shift is critical when manually verifying the changes the config command makes.

Unlocking Raspberry Pi 5 PCIe Gen 3.0

One of the most powerful hardware-specific features buried in the modern raspi-config menu is the PCIe speed toggle. The Raspberry Pi 5 exposes a PCIe 2.0 x1 connector by default for backward compatibility and signal integrity. However, many modern NVMe HATs and AI accelerators support PCIe Gen 3.0 speeds.

By navigating to Advanced Options > PCIe Speed in the TUI, the Raspberry Pi config command injects the dtparam=pciex1_gen=3 overlay into your firmware configuration. While the Raspberry Pi Foundation notes that Gen 3.0 is not officially certified due to signal compliance margins, in real-world testing with quality active HATs, this single toggle doubles your NVMe storage throughput from roughly 450 MB/s to over 900 MB/s.

Automating Deployments: The Non-Interactive Mode

While the TUI is excellent for single-node setups, it is useless for flashing and deploying a fleet of 50 Home Assistant nodes. This is where the nonint (non-interactive) flags become essential. By passing specific arguments to the Raspberry Pi config command, you can script your entire setup process in a bash initialization file.

Pro-Tip for Fleet Managers: You can view every available non-interactive command by inspecting the script directly. Run grep -E '^do_[a-zA-Z0-9_]+\(\)' /usr/bin/raspi-config in your terminal to dump a complete list of callable functions.

Here is how you use the non-interactive flags to automate a headless deployment:

# Set the hostname without a reboot prompt
sudo raspi-config nonint do_hostname 'flux-sensor-node-01'

# Enable SSH and I2C silently
sudo raspi-config nonint do_ssh 0
sudo raspi-config nonint do_i2c 0

# Set the Wi-Fi regulatory domain (required before connecting)
sudo raspi-config nonint do_wifi_country 'US'

# Expand the root filesystem to fill the SD card/NVMe
sudo raspi-config nonint do_expand_rootfs

Note that in the raspi-config logic, a parameter of 0 typically means 'enable' or 'on', while 1 means 'disable' or 'off'. This inverted logic often trips up beginners writing automation scripts.

Comparison: raspi-config vs. Manual File Editing

Is it better to use the Raspberry Pi config command or edit the text files manually? The table below breaks down the decision framework based on deployment scenarios.

Configuration Task Using raspi-config Manual Editing (/boot/firmware/config.txt or /etc/) Verdict
Enabling SPI / I2C Handles kernel modules, config.txt overlays, and user group permissions simultaneously. Requires editing config.txt, then manually running usermod -aG i2c $USER. raspi-config (Safer, fewer steps)
Changing Boot Order (USB vs SD) Updates the Pi 4/5 bootloader EEPROM configuration safely via vl805 and rpi-eeprom-config. Extremely high risk of bricking the boot sequence if hex values are miscalculated. raspi-config (Mandatory)
Custom Device Tree Overlays Limited to pre-approved Raspberry Pi Foundation overlays. Allows injection of third-party or custom .dtbo files for niche sensors. Manual (Required for custom hardware)
Memory Split (GPU RAM) Provides safe, preset increments (e.g., 64MB, 128MB). Allows exact byte-level allocation (e.g., gpu_mem=85). Tie (Depends on precision needs)

Real-World Troubleshooting: When the Config Command Fails

Despite its robustness, the Raspberry Pi config command can encounter edge-case failures, particularly on minimal OS images or custom-built kernels.

Missing Whiptail Dependencies

If you are running a stripped-down Debian image or a minimal Ubuntu Server build on your Pi, invoking sudo raspi-config may return a command not found or a whiptail: not found error. The TUI relies entirely on the whiptail package. Fix this by running sudo apt update && sudo apt install whiptail. If you are strictly headless and lack network access at that moment, you must fall back on the nonint flags mentioned earlier, as they bypass the UI requirement entirely.

EEPROM Mismatches on Pi 4 and Pi 5

Sometimes, selecting 'Boot Order' or 'PCIe Speed' in the config tool will throw a silent error or fail to persist across reboots. This is almost always caused by an outdated bootloader EEPROM. The Raspberry Pi config command attempts to modify the EEPROM, but if the onboard firmware is too old to recognize the new flags, it rejects the write.

To resolve this, bypass the config menu temporarily and force an EEPROM update via the CLI:

sudo apt update
sudo apt install rpi-eeprom
sudo rpi-eeprom-update -a
sudo reboot

After the reboot, the Raspberry Pi config command will successfully interface with the updated silicon, allowing you to enable advanced boot and bus configurations without silent failures.

Summary for System Integrators

The raspi-config utility is far more than a beginner's setup wizard; it is a vital abstraction layer that protects the integrity of the Raspberry Pi's firmware and OS state. By understanding the shift to the /boot/firmware/ directory in Bookworm, utilizing the nonint flags for automated provisioning, and recognizing when to manually intervene with EEPROM updates, you can deploy resilient, high-performance SBC nodes with absolute confidence.