Jump to content

NixOS on ARM/Raspberry Pi 4: Difference between revisions

From Official NixOS Wiki
← Older edit
JamieMagee (talk | contribs)
5 edits
VisualWikitext
imported>Bobbbay
m Add instructions on uncompressing the .zst files.
Update Pi 4 installation and profile guidance: cover optional modules, device-tree overlay limits, EEPROM updates, and HDMI connector names
 
(71 intermediate revisions by 33 users not shown)
Line 1: Line 1:
{{ARM/breadcrumb}}
{{ARM/breadcrumb}}
<div class="infobox">
<div class="infobox">
{|class="table"
{| class="table"
!colspan="2" class="title"|Raspberry Pi 4 Family
! colspan="2" class="title" | Raspberry Pi 4 family
|-
|-
|colspan="2"|(Image not available)
| colspan="2" | [[File:Raspberry_Pi_4,_2_GB_RAM_version_4.jpg|frameless|256px|A Raspberry Pi 4.]]
|-
|-
!Manufacturer
! Manufacturer
|Raspberry Pi Foundation
| Raspberry Pi Ltd
|-
|-
!Architecture
! Architecture
|AArch64
| AArch64
|-
|-
!Bootloader
! Boot method
|Custom or U-Boot
| Raspberry Pi EEPROM and firmware, U-Boot, and extlinux
|-
|-
!Boot order
! SoC
|Configurable; SD, USB, Netboot
| BCM2711
|-
|-
!Maintainer
! Variants
|
| Pi 4B, Pi 400, CM4, and CM4S
|-
!colspan="2" class="title"|Raspberry Pi 4B
|-
!SoC
|BCM2711
|}
|}
</div>
</div>
The Raspberry Pi family of devices is a series of single-board computers made by the Raspberry Pi Foundation. They are all based on Broadcom System-on-a-chip (SOCs).


== Status ==
The '''Raspberry Pi 4''' family works with the generic AArch64 SD image and has a board profile in <code>nixos-hardware</code>. The profile selects a Raspberry Pi downstream kernel and includes the Pi 4 initrd modules and Wi-Fi and Bluetooth firmware. It requests full KMS and provides optional modules for Pi 4 peripherals and HATs.


{{note|The Raspberry Pi 4 is currently <em>unsupported</em> though the NixOS distribution provides upstream beta-quality images.}}
== Installation ==


The default Linux kernel in use, is the Raspberry Pi Foundation's fork. This will change for the mainline kernel once its support for the Raspberry Pi 4 Family is good enough to allow the user to boot, configure, and rebuild a system.
Use the generic AArch64 SD image described on the [[NixOS on ARM/Raspberry Pi#Installation|family page]]. It contains boot files for Pi 4B, Pi 400, CM4, and CM4S.<ref name="generic-image">[https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/installer/sd-card/sd-image-aarch64.nix Nixpkgs generic AArch64 SD image module]</ref> In a flake, import <code>nixos-hardware.nixosModules.raspberry-pi-4</code>. With channels, import <code>&lt;nixos-hardware/raspberry-pi/4&gt;</code>. The [[NixOS on ARM/Raspberry Pi#Board profiles|family page]] provides complete examples and explains that a profile is not a bootable image.


The Raspberry Pi 4 Family is only supported as '''AArch64'''. Use as armv7 is community supported.
== Profile defaults ==


== Board-specific installation notes ==
The Pi 4 profile selects a pinned kernel from Raspberry Pi's downstream Linux tree and limits generation device trees to <code>bcm2711-rpi-*.dtb</code>. Its initrd includes the BCM2711 PCIe and VL805 reset drivers. The profile also installs pinned Wi-Fi and Bluetooth firmware, disables GRUB, and enables extlinux generation.<ref name="profile">[https://github.com/NixOS/nixos-hardware/blob/master/raspberry-pi/4/default.nix nixos-hardware Raspberry Pi 4 profile]</ref>


<del>First follow the [[NixOS_on_ARM#Installation|generic installation steps]] to get the installer image</del> and install using the [[NixOS_on_ARM#NixOS_installation_.26_configuration|installation and configuration steps]].
The shared <code>config.txt</code> defaults request full VC4 KMS with <code>dtoverlay=vc4-kms-v3d</code>.<ref name="config-defaults">[https://github.com/NixOS/nixos-hardware/blob/master/raspberry-pi/common/config-txt-defaults.nix nixos-hardware Raspberry Pi config.txt defaults]</ref> The compatibility option <code>hardware.raspberry-pi."4".fkms-3d.enable</code> is disabled by default and is not the normal graphics path.


''(Until the generic image works, a [https://hydra.nixos.org/job/nixos/trunk-combined/nixos.sd_image_raspberrypi4.aarch64-linux temporary device-specific image is build on Hydra]. Note that this image is not using u-boot, but rather the Raspberry Pi specific bootloader configuration.)''
== Optional hardware modules ==


Please note: to uncompress the .zstd, one may use the <code>unzstd</code> command (equivalent to <code>zstd -d</code>) on supported machines. The zstd commands can be accessed from the <code>zstd</code> package.
The Pi 4 profile imports the following options, all disabled by default. Each path starts with <code>hardware.raspberry-pi."4".</code>.


=== Configuration ===
{| class="wikitable"
 
! Hardware
Using <code>nixos-generate-config</code> will not generate the required minimal configuration.
! Option suffixes
 
! Purpose
Remember to add the nixos-unstable channel.
|-
 
| Audio and Bluetooth
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
| <code>audio.enable</code>, <code>bluetooth.enable</code>
{ config, pkgs, lib, ... }:
| Adds a build-time audio node or Bluetooth UART pin routing. Enable the corresponding NixOS audio or Bluetooth services separately.
 
|-
{
| USB controllers
# This configuration worked on 09-03-2021 nixos-unstable @ commit 102eb68ceec
| <code>dwc2.enable</code>, <code>dwc2.dr_mode</code>, <code>xhci.enable</code>
# The image used https://hydra.nixos.org/build/134720986
| Configures the DWC2 dual-role controller or the BCM2711 XHCI node.
 
|-
  boot = {
| GPIO, I2C, and PWM
    kernelPackages = pkgs.linuxPackages_rpi4;
| <code>gpio.enable</code>, <code>i2c0.enable</code>, <code>i2c1.enable</code>, <code>pwm0.enable</code>
    tmpOnTmpfs = true;
| Adds GPIO permissions, enables an I2C controller, or enables PWM0 on GPIO 18. Both I2C options also accept <code>frequency</code>.
    initrd.availableKernelModules = [ "usbhid" "usb_storage" ];
|-
    # ttyAMA0 is the serial console broken out to the GPIO
| Official display
    kernelParams = [
| <code>backlight.enable</code>, <code>touch-ft5406.enable</code>
        "8250.nr_uarts=1"
| Adds support nodes for the original official touch display and its FT5406 controller.
        "console=ttyAMA0,115200"
|-
        "console=tty1"
| HATs and capture devices
        # Some gui programs need this
| <code>digi-amp-plus.enable</code>, <code>poe-hat.enable</code>, <code>poe-plus-hat.enable</code>, <code>tv-hat.enable</code>, <code>tc358743.enable</code>
        "cma=128M"
| Configures the listed audio, PoE fan, TV tuner, or HDMI-to-CSI hardware. The PoE options expose fan temperature and hysteresis settings.
    ];
|-
  };
| LEDs
 
| <code>leds.eth.disable</code>, <code>leds.act.disable</code>, <code>leds.pwr.disable</code>
  boot.loader.raspberryPi = {
| Disables the selected Ethernet, activity, or power LED behaviour on supported Pi 4 boards.
    enable = true;
|}
    version = 4;
  };
  boot.loader.grub.enable = false;
  boot.loader.generic-extlinux-compatible.enable = true;
 
  # Required for the Wireless firmware
  hardware.enableRedistributableFirmware = true;
 
  networking = {
    hostName = "nixos-raspi-4"; # Define your hostname.
    networkmanager = {
      enable = true;
    };
  };
 
  environment.systemPackages = with pkgs; [
    neovim
  ];
 
  users = {
    defaultUserShell = pkgs.zsh;
    mutableUsers = false;
    users.root = {
      password = "apassword";
    };
    users.anormaluser = {
      isNormalUser = true;
      password = "apassword";
      extraGroups = [ "wheel" ]; # Enable ‘sudo’ for the user.
    };
  };
 
  environment.variables = {
    EDITOR = "nvim";
  };
 
  programs.zsh = {
    enable = true;
    syntaxHighlighting.enable = true;
    interactiveShellInit = ''
      source ${pkgs.grml-zsh-config}/etc/zsh/zshrc
    '';
    promptInit = ""; # otherwise it'll override the grml prompt
  };
 
  nix = {
    autoOptimiseStore = true;
    gc = {
      automatic = true;
      dates = "weekly";
      options = "--delete-older-than 30d";
    };
    # Free up to 1GiB whenever there is less than 100MiB left.
    extraOptions = ''
      min-free = ${toString (100 * 1024 * 1024)}
      max-free = ${toString (1024 * 1024 * 1024)}
    '';
  };
 
  # Assuming this is installed on top of the disk image.
  fileSystems = {
    "/" = {
      device = "/dev/disk/by-label/NIXOS_SD";
      fsType = "ext4";
      options = [ "noatime" ];
    };
  };
 
  nixpkgs.config = {
    allowUnfree = true;
  };
  powerManagement.cpuFreqGovernor = "ondemand";
  system.stateVersion = "20.09";
  #swapDevices = [ { device = "/swapfile"; size = 3072; } ];
}
</nowiki>}}
=== USB boot ===
 
For USB booting to work properly, firmware update might be needed:
 
{{commands|<nowiki>
nix-shell -p raspberrypi-eeprom
rpi-eeprom-update -d -a
</nowiki>}}
 
Now reboot the device so it can update the firmware from boot partition.
 
When running from USB device without SD card present, kernel spams log about missing SD card, workaround for this is to set:
 
{{commands|<nowiki>
boot.loader.raspberryPi.firmwareConfig = "dtparam=sd_poll_once=on";
</nowiki>}}
 
=== GPU support ===
 
The following configuration samples are built on the assumption that they are added to an already working configuration. They are not complete configurations.
 
==== Without GPU ====
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
  services.xserver = {
    enable = true;
    displayManager.lightdm.enable = true;
    desktopManager.gnome3.enable = true;
    videoDrivers = [ "fbdev" ];
  };
}
</nowiki>}}
==== With GPU ====
Warning: The device tree overlays provided with the RaspberryPi Kernel don't seem to be compatible with dtc. We might need to add support for the `dtmerge` tool as an alternative, or ask upstream to fix their overlays (or dtc).
 
See https://github.com/NixOS/nixpkgs/pull/107637#issuecomment-752635965 for details.
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ pkgs, ... }:
 
{
  hardware.opengl = {
    enable = true;
    setLdLibraryPath = true;
    package = pkgs.mesa_drivers;
  };
  hardware.deviceTree = {
    kernelPackage = pkgs.linux_rpi4;
    overlays = [ "${pkgs.device-tree_rpi.overlays}/vc4-fkms-v3d.dtbo" ];
  };
  services.xserver = {
    enable = true;
    displayManager.lightdm.enable = true;
    desktopManager.gnome3.enable = true;
    videoDrivers = [ "modesetting" ];
  };
  boot.loader.raspberryPi.firmwareConfig = ''
    gpu_mem=192
  '';
}
</nowiki>}}
==== Tools ====
 
The raspberry tools are available in the <code>libraspberrypi</code> package and include commands like <code>vcgencmd</code> to measure temperature and CPU frequency.
 
==== Audio ====


In addition to the usual config, you will need to enable audio support explicitly in the firmwareConfig.
The exact option definitions are in the [https://github.com/NixOS/nixos-hardware/tree/master/raspberry-pi/4 Pi 4 profile directory]. Some options apply only to the Pi 4B and exclude Compute Module variants.


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
=== Device-tree overlay limitation ===
  sound.enable = true;
  hardware.pulseaudio.enable = true;


  boot.loader.raspberryPi.firmwareConfig = ''
These optional modules use <code>hardware.deviceTree.overlays</code>, while <code>hardware.raspberry-pi.configtxt.settings</code> uses a separate firmware-time mechanism. The mechanisms can conflict. See [[NixOS on ARM/Raspberry Pi#Kernels and device trees|Kernels and device trees]]. [https://github.com/NixOS/nixos-hardware/issues/1946 nixos-hardware issue #1946] tracks the migration.
    dtparam=audio=on
  '';
</nowiki>}}
== Troubleshooting ==


=== Power issues ===
The base profile leaves <code>hardware.raspberry-pi."4".apply-overlays-dtmerge.enable</code> disabled. Some peripheral modules enable it when they require the Raspberry Pi <code>dtmerge</code> implementation. Do not enable it as a general installation step.


The Raspberry Pi 4B is as power-hungry, if not more, as its predecessors. It is important to have a [https://www.raspberrypi.org/documentation/hardware/raspberrypi/power/README.md sufficient enough power supply] or ''weirdness'' may happen. Weirdness may include:
== EEPROM and USB boot ==


* Lightning bolt icon on HDMI output "breaking" the display.
The Pi 4 bootloader lives in a rewritable EEPROM. USB or network boot may require a suitable EEPROM release and <code>BOOT_ORDER</code>. The <code>hardware.raspberry-pi.firmware</code> module manages files on the FAT firmware partition but does not update this EEPROM. Use the <code>raspberrypi-eeprom</code> package and the [https://www.raspberrypi.com/documentation/computers/configuration.html#update-bootloader-version official update procedure].
* Screen switching back to u-boot text
** Fixable temporarily when power is sufficient by switching VT (alt+F2 / alt+F1)
* Random hangs


{{note|A ''properly rated'' USB power supply, AND a good cable are necessary. The cable has to be short enough to not incur power losses through the length. Do note that thin and cheap cables usually have thinner copper wires, which in turn accentuates power losses.}}
The Pi 4B has two micro-HDMI outputs. Linux names the connector marked <code>HDMI0</code> as <code>HDMI-A-1</code> and <code>HDMI1</code> as <code>HDMI-A-2</code>.<ref name="display">[https://www.raspberrypi.com/documentation/computers/configuration.html#display-settings Raspberry Pi display documentation]</ref> If a text console or display manager appears on an unexpected output, check both connectors and use a kernel <code>video=</code> parameter when a fixed mapping is required.


Note that the Type-C USB receptacle for the Raspberry Pi 4B '''does not implement Power Delivery (USB PD)'''. This means that it is limited to whatever the power supply will provide when not negotiating power, which is most likely 5V at some undetermined power level.
For intermittent Wi-Fi reachability problems, see the [[NixOS on ARM/Raspberry Pi#Wi-Fi power saving|power-saving note on the family page]].


===First Install Issues===
== See also ==


Make sure that you resize the <code>NIXOS_SD</code> partition and expand the filesystem so that the initial install will have enough space for the <code>/nix/store</code>. Assuming you only have the SD card plugged in:
* [[NixOS on ARM/Raspberry Pi]]
<nowiki>
* [[NixOS on ARM/Installation]]
$ sudo parted resizepart 2 100%
* [https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#raspberry-pi-boot-eeprom Raspberry Pi boot EEPROM documentation]
$ sudo resize2fs /dev/disk/by-label/NIXOS_SD</nowiki>


You might also have to add the nix channels manually.
== References ==
<nowiki>
$ sudo mkdir -p /nix/var/nix/profiles/per-user/root/channels/
$ nix-channel --add https://nixos.org/channels/nixos-unstable nixpkgs
$ nix-channel --update</nowiki>


Finally, the <code>nixos-install</code> program might fail to copy your <code>configuration.nix</code> and <code>hardware-configuration.nix</code> files automatically to <code>/etc/nixos/</code>. You can do this yourself by <code>sudo cp /mnt/etc/nixos/* /etc/nixos/</code>.
<references />


<hr />
[[Category:NixOS on ARM]]

Latest revision as of 17:23, 18 July 2026

Raspberry Pi 4 family
A Raspberry Pi 4.
Manufacturer Raspberry Pi Ltd
Architecture AArch64
Boot method Raspberry Pi EEPROM and firmware, U-Boot, and extlinux
SoC BCM2711
Variants Pi 4B, Pi 400, CM4, and CM4S

The Raspberry Pi 4 family works with the generic AArch64 SD image and has a board profile in nixos-hardware. The profile selects a Raspberry Pi downstream kernel and includes the Pi 4 initrd modules and Wi-Fi and Bluetooth firmware. It requests full KMS and provides optional modules for Pi 4 peripherals and HATs.

Installation

Use the generic AArch64 SD image described on the family page. It contains boot files for Pi 4B, Pi 400, CM4, and CM4S.[1] In a flake, import nixos-hardware.nixosModules.raspberry-pi-4. With channels, import <nixos-hardware/raspberry-pi/4>. The family page provides complete examples and explains that a profile is not a bootable image.

Profile defaults

The Pi 4 profile selects a pinned kernel from Raspberry Pi's downstream Linux tree and limits generation device trees to bcm2711-rpi-*.dtb. Its initrd includes the BCM2711 PCIe and VL805 reset drivers. The profile also installs pinned Wi-Fi and Bluetooth firmware, disables GRUB, and enables extlinux generation.[2]

The shared config.txt defaults request full VC4 KMS with dtoverlay=vc4-kms-v3d.[3] The compatibility option hardware.raspberry-pi."4".fkms-3d.enable is disabled by default and is not the normal graphics path.

Optional hardware modules

The Pi 4 profile imports the following options, all disabled by default. Each path starts with hardware.raspberry-pi."4"..

Hardware Option suffixes Purpose
Audio and Bluetooth audio.enable, bluetooth.enable Adds a build-time audio node or Bluetooth UART pin routing. Enable the corresponding NixOS audio or Bluetooth services separately.
USB controllers dwc2.enable, dwc2.dr_mode, xhci.enable Configures the DWC2 dual-role controller or the BCM2711 XHCI node.
GPIO, I2C, and PWM gpio.enable, i2c0.enable, i2c1.enable, pwm0.enable Adds GPIO permissions, enables an I2C controller, or enables PWM0 on GPIO 18. Both I2C options also accept frequency.
Official display backlight.enable, touch-ft5406.enable Adds support nodes for the original official touch display and its FT5406 controller.
HATs and capture devices digi-amp-plus.enable, poe-hat.enable, poe-plus-hat.enable, tv-hat.enable, tc358743.enable Configures the listed audio, PoE fan, TV tuner, or HDMI-to-CSI hardware. The PoE options expose fan temperature and hysteresis settings.
LEDs leds.eth.disable, leds.act.disable, leds.pwr.disable Disables the selected Ethernet, activity, or power LED behaviour on supported Pi 4 boards.

The exact option definitions are in the Pi 4 profile directory. Some options apply only to the Pi 4B and exclude Compute Module variants.

Device-tree overlay limitation

These optional modules use hardware.deviceTree.overlays, while hardware.raspberry-pi.configtxt.settings uses a separate firmware-time mechanism. The mechanisms can conflict. See Kernels and device trees. nixos-hardware issue #1946 tracks the migration.

The base profile leaves hardware.raspberry-pi."4".apply-overlays-dtmerge.enable disabled. Some peripheral modules enable it when they require the Raspberry Pi dtmerge implementation. Do not enable it as a general installation step.

EEPROM and USB boot

The Pi 4 bootloader lives in a rewritable EEPROM. USB or network boot may require a suitable EEPROM release and BOOT_ORDER. The hardware.raspberry-pi.firmware module manages files on the FAT firmware partition but does not update this EEPROM. Use the raspberrypi-eeprom package and the official update procedure.

The Pi 4B has two micro-HDMI outputs. Linux names the connector marked HDMI0 as HDMI-A-1 and HDMI1 as HDMI-A-2.[4] If a text console or display manager appears on an unexpected output, check both connectors and use a kernel video= parameter when a fixed mapping is required.

For intermittent Wi-Fi reachability problems, see the power-saving note on the family page.

See also

References

  1. ↑ Nixpkgs generic AArch64 SD image module
  2. ↑ nixos-hardware Raspberry Pi 4 profile
  3. ↑ nixos-hardware Raspberry Pi config.txt defaults
  4. ↑ Raspberry Pi display documentation
Retrieved from "https://wiki.nixos.org/w/index.php?title=NixOS_on_ARM/Raspberry_Pi_4&oldid=33755"