View source for NixOS on ARM/Raspberry Pi 4

{{ARM/breadcrumb}}
<div class="infobox">
{|class="table"
!colspan="2" class="title"|Raspberry Pi 4 Family
|-
|colspan="2"|(Image not available)
|-
!Manufacturer
|Raspberry Pi Foundation
|-
!Architecture
|AArch64
|-
!Bootloader
|Custom or U-Boot
|-
!Boot order
|Configurable; SD, USB, Netboot
|-
!Maintainer
|
|-
!colspan="2" class="title"|Raspberry Pi 4B
|-
!SoC
|BCM2711
|}
</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 is only supported as '''AArch64'''. Use as armv7 is community supported.

== Board-specific installation notes ==

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]].

The Raspberry Pi 4B should work with either the [https://hydra.nixos.org/job/nixos/trunk-combined/nixos.sd_image.aarch64-linux generic SD image] or [https://hydra.nixos.org/job/nixos/trunk-combined/nixos.sd_image_new_kernel.aarch64-linux the new kernel variant], starting with 21.05 (or unstable). As long as a kernel 5.10 or newer is in use.

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.

Sample instructions for [https://nix.dev/tutorials/installing-nixos-on-a-raspberry-pi installing NixOS on a Raspberry Pi] are available at nix.dev.

=== Configuration ===

{{outdated|These instructions were written when the generic image did not work. Using the vendor kernel may be desirable under some conditions<sup>[which?]</sup>}}

Using <code>nixos-generate-config</code> will not generate the required minimal configuration.

Remember to add the nixos-unstable channel.

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ config, pkgs, lib, ... }:

{
 # This configuration worked on 09-03-2021 nixos-unstable @ commit 102eb68ceec
 # The image used https://hydra.nixos.org/build/134720986

  boot = {
    kernelPackages = pkgs.linuxPackages_rpi4;
    tmpOnTmpfs = true;
    initrd.availableKernelModules = [ "usbhid" "usb_storage" ];
    # ttyAMA0 is the serial console broken out to the GPIO
    kernelParams = [
        "8250.nr_uarts=1"
        "console=ttyAMA0,115200"
        "console=tty1"
        # Some gui programs need this
        "cma=128M"
    ];
  };

  boot.loader.raspberryPi = {
    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, 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.

When running from USB device without SD card present, kernel spams log about missing SD card, workaround for this is to set:

{{outdated|This will only work when not using U-Boot. Configuring through an overlay will be required.}}

{{file|/etc/nixos/configuration.nix|nix|<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 ====

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.gnome3.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 ====

{{outdated|An equivalent change that works with U-Boot through <code>hardware.deviceTree</code> is needed.}}

In addition to the usual config, you will need to enable audio support explicitly in the firmwareConfig.

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
  sound.enable = true;
  hardware.pulseaudio.enable = true;

  boot.loader.raspberryPi.firmwareConfig = ''
    dtparam=audio=on
  '';
</nowiki>}}

=== Gpio ===
Add gpio group and change permission for all users in new gpio group.
Now all users in gpio group have access to /dev/gpiomem and to gpio pins via sysfs.


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
  # add gpio group
  users.groups.gpio = {};

  # udev rule for gpio
  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 with gpio group
  users = {
    mutableUsers = false;
    users.mygpiouser = {
      isNormalUser = true;
      password = "mygpiouserpasswd";
      extraGroups = [ "wheel" "gpio" ];
    };
  };

</nowiki>}}
== Notes about the boot process ==

Unless using an extremely early WIP image, the Raspberry Pi 4B boots using the U-Boot platform firmware.

=== Updating U-Boot ===

[https://github.com/NixOS/nixpkgs/issues/82455#issuecomment-959797355 These steps can be followed to update the platform firmware.]

== Troubleshooting ==

=== Power issues ===

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:

* Lightning bolt icon on HDMI output "breaking" the display.
* 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.}}

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.

<hr />