Official NixOS Wiki

NixOS on ARM/Raspberry Pi 4: Difference between revisions

← Older edit
JamieMagee (talk | contribs)
5 edits
VisualWikitext
Nixoszz (talk | contribs)
11 edits
Tags: Reverted Visual edit
Update Pi 4 installation and profile guidance: cover optional modules, device-tree overlay limits, EEPROM updates, and HDMI connector names
 
(14 intermediate revisions by 7 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>
Raspberry Pi系列设备是由Raspberry Pi基金会制造的一系列单板计算机。它们都基于Broadcom片上系统（SoC）。


== 状态 ==
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.


Raspberry Pi 4家族仅支持AArch64。社区支持使用armv7。
== Installation ==


== Board-specific 安装说明 ==
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.


首先按照 [[NixOS_on_ARM#Installation|generic installation steps]] 获取安装程序映像，并使用 [[NixOS_on_ARM#NixOS_installation_.26_configuration|installation and configuration steps]].
== Profile defaults ==


Raspberry Pi 4B可与 [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>


nix.dev上提供了在Raspberry Pi上安装NixOS的示例说明。[https://nix.dev/tutorials/installing-nixos-on-a-raspberry-pi installing NixOS on a Raspberry Pi]  
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|请注意，Raspberry Pi 4有两个HDMI输出，显然有时控制台/TTY的用户提示显示在HDMI 1上，而启动过程显示在HDMI 0上（官方（非NixOs）非图形精简版图像也可能出现这种情况）。因此，如果在第2阶段结束时收到“欢迎使用NixOs”的消息后，您的屏幕变黑/断开连接，请尝试使用另一个HDMI端口。请在此处查看相关错误。
== Optional hardware modules ==
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].}}


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


使用nixos-generate-config将生成所需的最小配置。
{| class="wikitable"
 
! Hardware
Raspberry Pi 4在现代内核上得到了很好的支持。但是，如果您遇到GPU支持或其他deviceTree怪癖的问题，您可能希望添加nixos硬件通道：Raspberry Pi 4 is well-supported on modern kernels. However, if you encounter issues with GPU support or other deviceTree quirks, you may wish to add the nixos-hardware channel:
! Option suffixes
 
! Purpose
<code>
|-
nix-channel --add https://github.com/NixOS/nixos-hardware/archive/master.tar.gz nixos-hardware
| Audio and Bluetooth
 
| <code>audio.enable</code>, <code>bluetooth.enable</code>
nix-channel --update
| Adds a build-time audio node or Bluetooth UART pin routing. Enable the corresponding NixOS audio or Bluetooth services separately.
</code>
|-
 
| USB controllers
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
| <code>dwc2.enable</code>, <code>dwc2.dr_mode</code>, <code>xhci.enable</code>
{ config, pkgs, lib, ... }:
| Configures the DWC2 dual-role controller or the BCM2711 XHCI node.
{
|-
  imports =
| GPIO, I2C, and PWM
    [
| <code>gpio.enable</code>, <code>i2c0.enable</code>, <code>i2c1.enable</code>, <code>pwm0.enable</code>
      </nowiki><<nowiki>nixos-hardware/raspberry-pi/4</nowiki>><nowiki>
| Adds GPIO permissions, enables an I2C controller, or enables PWM0 on GPIO 18. Both I2C options also accept <code>frequency</code>.
      ./hardware-configuration.nix
|-
    ];
| Official display
  hardware = {
| <code>backlight.enable</code>, <code>touch-ft5406.enable</code>
    raspberry-pi."4".apply-overlays-dtmerge.enable = true;
| Adds support nodes for the original official touch display and its FT5406 controller.
    deviceTree = {
|-
      enable = true;
| HATs and capture devices
      filter = "*rpi-4-*.dtb";
| <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>
    };
| Configures the listed audio, PoE fan, TV tuner, or HDMI-to-CSI hardware. The PoE options expose fan temperature and hysteresis settings.
  };
|-
  console.enable = false;
| LEDs
  environment.systemPackages = with pkgs; [
| <code>leds.eth.disable</code>, <code>leds.act.disable</code>, <code>leds.pwr.disable</code>
    libraspberrypi
| Disables the selected Ethernet, activity, or power LED behaviour on supported Pi 4 boards.
    raspberrypi-eeprom
|}
  ];
  system.stateVersion = "24.11";
}
</nowiki>}}
 
=== 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 the 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] an option has been added to use the <code>fkms-3d</code> ([https://wiki.archlinux.org/title/Kernel_mode_setting modesetting]) overlay which uses the [https://www.raspberrypi.com/news/vc4-and-v3d-opengl-drivers-for-raspberry-pi-an-update/ V3D renderer]. This will only work with the vendor kernel, which is the default in NixOS.
 
{{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>
{
  # Enable audio devices
  boot.kernelParams = [ "snd_bcm2835.enable_hdmi=1" "snd_bcm2835.enable_headphones=1" ];
  boot.loader.raspberryPi.firmwareConfig = ''
    dtparam=audio=on
  '';
}
</nowiki>}}
 
If you're running headless, you can also disable HDMI audio and force use of the headphones jack by adding <code>hdmi_ignore_edid_audio=1</code> on a line below <code>dtparam=audio=on</code>.
 
=== Networking ===
 
Ethernet and wifi interfaces should work out of the box. In addition to normal network configuration, consider disabling wifi powersaving if you experience slowness or issues with the host becoming unreachable on the network shortly after boot. For NetworkManager, the following configuration is sufficient:
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
  # Basic networking
  networking.networkmanager.enable = true;
  # Prevent host becoming unreachable on wifi after some time.
  networking.networkmanager.wifi.powersave = false;
}
</nowiki>}}
 
=== Using GPIO pins as non-root ===
 
By default, the GPIO pins are enabled, but can only be accessed by the root user.
This can be addressed by adding a [https://wiki.archlinux.org/title/Udev udev] rule to your configuration that changes the ownership 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> changes 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 possible 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";
      dtboFile = ./spi0-0cs.dtbo;
    }
  ];
};
 
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 downloaded [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>
{ pkgs, ... }:
 
{
  # 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)
  # 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 = ''
    # allow access to raspi cec device for video group (and optionally register it as a systemd device, used below)
    KERNEL=="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
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.
  # scan for devices: `echo 'scan' </nowiki>><nowiki> /run/cec.fifo ; journalctl -u cec-client.service`
  # set pi as active source: `echo 'as' </nowiki>><nowiki> /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 </nowiki>><nowiki> /run/cec.fifo"'';
      StandardInput = "socket";
      StandardOutput = "journal";
      Restart="no";
  };
}
</nowiki>}}
=== Enabling Bluetooth ===


One might get bluetooth to work with this in the configuration file:
=== Device-tree overlay limitation ===


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
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.
  systemd.services.btattach = {
    before = [ "bluetooth.service" ];
    after = [ "dev-ttyAMA0.device" ];
    wantedBy = [ "multi-user.target" ];
    serviceConfig = {
      ExecStart = "${pkgs.bluez}/bin/btattach -B /dev/ttyAMA0 -P bcm -S 3000000";
    };
  };
</nowiki>}}


== Customizing & Generating SD image without installation step ==
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.
There's a nix-community project to support fine-grained kernel & config.txt, and generate the image directly:


[https://github.com/nix-community/raspberry-pi-nix/ nix-community/raspberry-pi-nix]
== EEPROM and USB boot ==


== 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 />


=== Touch screen not working ===
[[Category:NixOS on ARM]]
You have to declare this in your <code>configuration.nix</code><ref>https://discourse.nixos.org/t/cant-get-nixos-x-to-work-on-a-raspberry-pi-with-dsi-display/44532/3</ref>:<syntaxhighlight lang="nix">
hardware.raspberry-pi."4" = {
  touch-ft5406.enable = true;
};
</syntaxhighlight>
Retrieved from "https://wiki.nixos.org/wiki/NixOS_on_ARM/Raspberry_Pi_4"