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>Kalch
m Add .enable to hardware.raspberry-pi."4".audio
Update Pi 4 installation and profile guidance: cover optional modules, device-tree overlay limits, EEPROM updates, and HDMI connector names
 
(40 intermediate revisions by 18 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"|[[File:Raspberry_Pi_4,_2_GB_RAM_version_4.jpg|frameless|256px|A Raspberry Pi 4.]]
| 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.


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


== Board-specific installation notes ==
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.


First follow the [[NixOS_on_ARM#Installation|generic installation steps]] to get the installer image and install using the [[NixOS_on_ARM#NixOS_installation_.26_configuration|installation and configuration steps]].
== Profile defaults ==


The Raspberry Pi 4B works with the [https://hydra.nixos.org/job/nixos/trunk-combined/nixos.sd_image.aarch64-linux generic SD image].
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>


Sample instructions for [https://nix.dev/tutorials/installing-nixos-on-a-raspberry-pi installing NixOS on a Raspberry Pi] are available at nix.dev.
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.


{{warning| Note that the Raspberry Pi 4 has two HDMI outputs, and apparently sometimes the user prompt for the console/TTY is displayed on HDMI 1 while the boot process is displayed on HDMI 0 (this may even [https://raspberrypi.stackexchange.com/a/112071/149250 be the case] with the official (non NixOs) non-graphical lite image). So if after the message "Welcome on NixOs" at the end of phase 2 your screen goes black/disconnects, try to use the other HDMI port. See the related bug [https://github.com/NixOS/nixpkgs/issues/179701 here].}}
== Optional hardware modules ==


=== Configuration ===
The Pi 4 profile imports the following options, all disabled by default. Each path starts with <code>hardware.raspberry-pi."4".</code>.


Using <code>nixos-generate-config</code> will generate the required minimal configuration.
{| class="wikitable"
 
! Hardware
For better GPU Support and some deviceTree quirks add the nixos-hardware channel:
! Option suffixes
<code>nix-channel --add https://github.com/NixOS/nixos-hardware/archive/master.tar.gz nixos-hardware</code>
! Purpose
 
|-
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
| Audio and Bluetooth
{ config, pkgs, lib, ... }:
| <code>audio.enable</code>, <code>bluetooth.enable</code>
{
| Adds a build-time audio node or Bluetooth UART pin routing. Enable the corresponding NixOS audio or Bluetooth services separately.
  imports =
|-
    [
| USB controllers
      <nixos-hardware/raspberry-pi/4>
| <code>dwc2.enable</code>, <code>dwc2.dr_mode</code>, <code>xhci.enable</code>
      ./hardware-configuration.nix
| Configures the DWC2 dual-role controller or the BCM2711 XHCI node.
    ];
|-
  hardware = {
| GPIO, I2C, and PWM
    raspberry-pi."4".apply-overlays-dtmerge.enable = true;
| <code>gpio.enable</code>, <code>i2c0.enable</code>, <code>i2c1.enable</code>, <code>pwm0.enable</code>
    deviceTree = {
| Adds GPIO permissions, enables an I2C controller, or enables PWM0 on GPIO 18. Both I2C options also accept <code>frequency</code>.
      enable = true;
|-
      filter = "*rpi-4-*.dtb";
| Official display
    };
| <code>backlight.enable</code>, <code>touch-ft5406.enable</code>
  };
| Adds support nodes for the original official touch display and its FT5406 controller.
  console.enable = false;
|-
  environment.systemPackages = with pkgs; [
| HATs and capture devices
    libraspberrypi
| <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>
    raspberrypi-eeprom
| Configures the listed audio, PoE fan, TV tuner, or HDMI-to-CSI hardware. The PoE options expose fan temperature and hysteresis settings.
  ];
|-
  system.stateVersion = "23.11";
| LEDs
}
| <code>leds.eth.disable</code>, <code>leds.act.disable</code>, <code>leds.pwr.disable</code>
</nowiki>}}
| Disables the selected Ethernet, activity, or power LED behaviour on supported Pi 4 boards.
=== USB boot ===
|}
 
For USB booting to work properly, a 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.
 
=== 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.gnome.enable = true;
    videoDrivers = [ "fbdev" ];
  };
}
</nowiki>}}
==== With GPU ====
 
In [https://github.com/NixOS/nixos-hardware/pull/261 nixos-hardware#261] a new option has been added to use the <code>fkms-3d</code> overlay. This will only work with the vendor kernel.
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ pkgs, ... }:
 
{
  imports = [
    .../nixos-hardware/raspberry-pi/4
  ];
 
  hardware.raspberry-pi."4".fkms-3d.enable = true;
 
  services.xserver = {
    enable = true;
    displayManager.lightdm.enable = true;
    desktopManager.gnome.enable = true;
  };
}
</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 hardware audio support:
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
  sound.enable = true;
  hardware.pulseaudio.enable = true;
  hardware.raspberry-pi."4".audio.enable = true;
</nowiki>}}
 
=== Using GPIO pins as non root ===
 
By default, the GPIO pins are enable, but can only be accessed by the root user.
This can be address by adding a [https://wiki.archlinux.org/title/Udev udev] rule to your configuration that changes the owner ship of <code>/dev/gpiomem</code> and the other required devices.
 
The following code adds a group <code>gpio</code> and adds the user <code>mygpiouser</code> to that group.
You probably want to put your own user name here.
 
The <code>extraRules</code> change the owner of <code>gpiomem</code> and all other files needed for GPIO to work to <code>root:gpio</code> and changes the permissions to <code>0660</code>.
Therefore, the root user and anyone in the gpio group can now access the GPIO pins.
 
<syntaxHighlight lang="nix">
  # Create gpio group
  users.groups.gpio = {};
 
  # Change permissions gpio devices
  services.udev.extraRules = ''
    SUBSYSTEM=="bcm2835-gpiomem", KERNEL=="gpiomem", GROUP="gpio",MODE="0660"
    SUBSYSTEM=="gpio", KERNEL=="gpiochip*", ACTION=="add", RUN+="${pkgs.bash}/bin/bash -c 'chown root:gpio  /sys/class/gpio/export /sys/class/gpio/unexport ; chmod 220 /sys/class/gpio/export /sys/class/gpio/unexport'"
    SUBSYSTEM=="gpio", KERNEL=="gpio*", ACTION=="add",RUN+="${pkgs.bash}/bin/bash -c 'chown root:gpio /sys%p/active_low /sys%p/direction /sys%p/edge /sys%p/value ; chmod 660 /sys%p/active_low /sys%p/direction /sys%p/edge /sys%p/value'"
  '';
 
  # Add user to group
  users = {
    users.mygpiouser = {
      extraGroups = [ "gpio" ... ];
      ....
    };
  };
</syntaxHighlight>
 
=== Enabling the SPI ===
 
To enable the SPI, you would normally add <code>dtparam=spi=on</code> to <code>/boot/config.txt</code>.
This is not possbible on NixOS, and instead you have to apply a device tree overlay.
For this we use the <code>hardware.deviceTree.overlays</code> option.
After applying the overlay, we add an <code>spi</code> group and change the owner of the <code>spidev</code> device to it, similarly to [[#Using GPIO pins as non root |GPIO]].
 
<syntaxHighlight lang="nix">
hardware.raspberry-pi."4".apply-overlays-dtmerge.enable = true;
hardware.deviceTree = {
  enable = true;
  filter = "*-rpi-*.dtb";
  overlays = [
    {
      name = "spi";
      dtsoFile = ./spi0-0cd.dtso;
    }
  ];
};
 
users.groups.spi = {};
 
services.udev.extraRules = ''
  SUBSYSTEM=="spidev", KERNEL=="spidev0.0", GROUP="spi", MODE="0660"
'';
</syntaxHighlight>
 
The the <code>spi0-0cd.dtso</code> file can be downlaoded [https://github.com/raspberrypi/firmware/blob/master/boot/overlays/spi0-0cs.dtbo here].
You might have to change the <code>compatible</code> field to "raspberrypi" in the dtbo file.
 
=== HDMI-CEC ===
 
A few bits and pieces for using HDMI-CEC on the Pi4:


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
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.
{ pkgs, ... }:


{
=== Device-tree overlay limitation ===
  # an overlay to enable raspberrypi support in libcec, and thus cec-client
  nixpkgs.overlays = [
    # nixos-22.05
    # (self: super: { libcec = super.libcec.override { inherit (self) libraspberrypi; }; })
    # nixos-22.11
    (self: super: { libcec = super.libcec.override { withLibraspberrypi = true; }; })
  ];


  # install libcec, which includes cec-client (requires root or "video" group, see udev rule below)
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.
  # scan for devices: `echo 'scan' | cec-client -s -d 1`
  # set pi as active source: `echo 'as' | cec-client -s -d 1`
  environment.systemPackages = with pkgs; [
    libcec
  ];


  services.udev.extraRules = ''
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.
    # allow access to raspi cec device for video group (and optionally register it as a systemd device, used below)
    SUBSYSTEM=="vchiq", GROUP="video", MODE="0660", TAG+="systemd", ENV{SYSTEMD_ALIAS}="/dev/vchiq"
  '';


  # optional: attach a persisted cec-client to `/run/cec.fifo`, to avoid the CEC ~1s startup delay per command
== EEPROM and USB boot ==
  # scan for devices: `echo 'scan' > /run/cec.fifo ; journalctl -u cec-client.service`
  # set pi as active source: `echo 'as' > /run/cec.fifo`
  systemd.sockets."cec-client" = {
    after = [ "dev-vchiq.device" ];
    bindsTo = [ "dev-vchiq.device" ];
    wantedBy = [ "sockets.target" ];
    socketConfig = {
      ListenFIFO = "/run/cec.fifo";
      SocketGroup = "video";
      SocketMode = "0660";
    };
  };
  systemd.services."cec-client" = {
    after = [ "dev-vchiq.device" ];
    bindsTo = [ "dev-vchiq.device" ];
    wantedBy = [ "multi-user.target" ];
    serviceConfig = {
      ExecStart = ''${pkgs.libcec}/bin/cec-client -d 1'';
      ExecStop = ''/bin/sh -c "echo q > /run/cec.fifo"'';
      StandardInput = "socket";
      StandardOutput = "journal";
      Restart="no";
  };
}
</nowiki>}}


== Notes about the boot process ==
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].


Unless using an extremely early WIP image, the Raspberry Pi 4B boots using the U-Boot platform firmware.
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.


=== Updating U-Boot/Firmware ===
For intermittent Wi-Fi reachability problems, see the [[NixOS on ARM/Raspberry Pi#Wi-Fi power saving|power-saving note on the family page]].


{{commands| <nowiki>
== See also ==
$ nix-shell -p raspberrypi-eeprom
$ sudo mount /dev/disk/by-label/FIRMWARE /mnt
$ sudo BOOTFS=/mnt FIRMWARE_RELEASE_STATUS=stable rpi-eeprom-update -d -a
</nowiki>}} [https://nix.dev/tutorials/installing-nixos-on-a-raspberry-pi#updating-firmware source]


== Troubleshooting ==
* [[NixOS on ARM/Raspberry Pi]]
* [[NixOS on ARM/Installation]]
* [https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#raspberry-pi-boot-eeprom Raspberry Pi boot EEPROM documentation]


=== Audio not playing and Bluetooth: no controller available ===
== References ==


On the Raspberry Pi kernel, the jack may never play audio, and no Bluetooth devices may ever be found. To get this to work, it is recommended to switch to the mainline kernel. See [https://github.com/NixOS/nixpkgs/issues/123725 nixpkgs#123725]  for more info.
<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"