nix-community/raspberry-pi-nix
1
0
Fork 0
mirror of https://github.com/nix-community/raspberry-pi-nix.git synced 2025-11-08 19:46:03 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

update readme

Browse source
This commit is contained in:
Travis Staton 2024-07-27 10:35:45 -04:00
parent 0dfdbce026
commit 4ecdee4572
1 changed files with 51 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

107
README.md
View file

@ -19,36 +19,35 @@ and `rpi/config.nix`. The other modules are mostly wrappers that set
## Example ## Example
See [the example See the `rpi-example` config in this flake for a CI-checked example.
repo](https://github.com/tstat/raspberry-pi-nix-example) for a
complete example.
```nix ```nix
{ {
description = "raspberry-pi-nix example"; description = "raspberry-pi-nix example";
nixConfig = {
extra-substituters = [ "https://raspberry-pi-nix.cachix.org" ];
extra-trusted-public-keys = [
"raspberry-pi-nix.cachix.org-1:WmV2rdSangxW0rZjY/tBvBDSaNFQ3DyEQsVw8EvHn9o="
];
};
inputs = { inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-22.11"; nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
raspberry-pi-nix.url = "github:tstat/raspberry-pi-nix"; raspberry-pi-nix.url = "github:nix-community/raspberry-pi-nix";
}; };
outputs = { self, nixpkgs, raspberry-pi-nix }: outputs = { self, nixpkgs, raspberry-pi-nix }:
let let
inherit (nixpkgs.lib) nixosSystem; inherit (nixpkgs.lib) nixosSystem;
basic-config = { pkgs, lib, ... }: { basic-config = { pkgs, lib, ... }: {
# bcm2711 for rpi 3, 3+, 4, zero 2 w
# bcm2712 for rpi 5
# See the docs at:
# https://www.raspberrypi.com/documentation/computers/linux_kernel.html#native-build-configuration
raspberry-pi-nix.board = "bcm2711";
time.timeZone = "America/New_York"; time.timeZone = "America/New_York";
users.users.root.initialPassword = "root"; users.users.root.initialPassword = "root";
networking = { networking = {
hostName = "basic-example"; hostName = "basic-example";
useDHCP = false; useDHCP = false;
interfaces = { wlan0.useDHCP = true; }; interfaces = {
wlan0.useDHCP = true;
eth0.useDHCP = true;
};
}; };
environment.systemPackages = with pkgs; [ bluez bluez-tools ];
hardware = { hardware = {
bluetooth.enable = true; bluetooth.enable = true;
raspberry-pi = { raspberry-pi = {
@ -80,11 +79,11 @@ complete example.
``` ```
## Using the provided cache to avoid compiling linux ## Using the provided cache to avoid compiling linux
This repo uses the raspberry pi linux kernel fork, and compiling linux This repo uses the raspberry pi linux kernel fork, and compiling linux takes a
takes a while. I do push my kernel builds to a cachix cache that you while. CI pushes kernel builds to the nix-community cachix cache that you may
may use to avoid compiling linux yourself. The cache can be found use to avoid compiling linux yourself. The cache can be found at
at https://raspberry-pi-nix.cachix.org, and you can follow the https://nix-community.cachix.org, and you can follow the instructions there
instructions there to use this cache. to use this cache.
You don't need the cachix binary to use the cachix cache though, you You don't need the cachix binary to use the cachix cache though, you
just need to add the relevant just need to add the relevant
@ -114,16 +113,15 @@ nix build '.#nixosConfigurations.rpi-example.config.system.build.sdImage'
## The firmware partition ## The firmware partition
The image produced by this package is partitioned in the same way as The image produced by this package is partitioned in the same way as the aarch64
the aarch64 installation media from nixpkgs: There is a firmware installation media from nixpkgs: There is a firmware partition that contains
partition that contains necessary firmware, u-boot, and necessary firmware, the kernel or u-boot, and config.txt. Then there is another
config.txt. Then there is another partition (labeled `NIXOS_SD`) that partition (labeled `NIXOS_SD`) that contains everything else. The firmware and
contains everything else. The firmware and `config.txt` file are `config.txt` file are managed by NixOS modules defined in this
managed by NixOS modules defined in this package. Additionally, a package. Additionally, a systemd service will update the firmware and
systemd service will update the firmware and `config.txt` in the `config.txt` in the firmware partition __in place__. If uboot is enabled then
firmware partition __in place__. Linux kernels are stored in the linux kernels are stored in the `NIXOS_SD` partition and will be booted by
`NIXOS_SD` partition and will be booted by u-boot in the firmware u-boot in the firmware partition.
partition.
## `config.txt` generation ## `config.txt` generation
@ -258,39 +256,36 @@ nix build '.#nixosConfigurations.rpi-example.config.hardware.raspberry-pi.config
## Firmware partition implementation notes ## Firmware partition implementation notes
In Raspberry Pi devices the proprietary firmware manipulates the In Raspberry Pi devices the proprietary firmware manipulates the device tree in
device tree in a number of ways before handing it off to the kernel a number of ways before handing it off to the kernel (or in our case, to
(or in our case, to u-boot). The transformations that are performed u-boot). The transformations that are performed aren't documented so well
aren't documented so well (although I have found [this (although I have found [this
list](https://forums.raspberrypi.com/viewtopic.php?t=329799#p1974233) list](https://forums.raspberrypi.com/viewtopic.php?t=329799#p1974233) ).
).
This manipulation makes it difficult to use the device tree configured This manipulation makes it difficult to use the device tree configured directly
directly by NixOS as the proprietary firmware's manipulation must be by NixOS as the proprietary firmware's manipulation must be known and
known and reproduced. reproduced.
Even if the manipulation were successfully reproduced, some benefits Even if the manipulation were successfully reproduced, some benefits would be
would be lost. For example, the firmware can detect connected hardware lost. For example, the firmware can detect connected hardware during boot and
during boot and automatically configure the device tree accordingly automatically configure the device tree accordingly before passing it onto the
before passing it onto the kernel. If this firmware device tree is kernel. If this firmware device tree is ignored then a NixOS system rebuild with
ignored then a NixOS system rebuild with a different device tree would a different device tree would be required when swapping connected
be required when swapping connected hardware. Examples of what I mean hardware. Examples of what I mean by hardware include: the specific Raspberry Pi
by hardware include: the specific Raspberry Pi device booting the device booting the image, connected cameras, and connected displays.
image, connected cameras, and connected displays.
So, in order to avoid the headaches associated with failing to So, in order to avoid the headaches associated with failing to reproduce some
reproduce some firmware device tree manipulation, and to reap the firmware device tree manipulation, and to reap the benefits afforded by the
benefits afforded by the firmware device tree configuration, u-boot is firmware device tree configuration, the bootloader is configured to use the
configured to use the device tree that it is given (i.e. the one that device tree that it is given (i.e. the one that the raspberry pi firmware loads
the raspberry pi firmware loads and manipulates). As a consequence, and manipulates). As a consequence, device tree configuration is controlled via
device tree configuration is controlled via the [config.txt the [config.txt
file](https://www.raspberrypi.com/documentation/computers/config_txt.html). file](https://www.raspberrypi.com/documentation/computers/config_txt.html).
Additionally, the firmware, device trees, and overlays from the Additionally, the firmware, device trees, and overlays from the `raspberrypifw`
`raspberrypifw` package populate the firmware partition. This package package populate the firmware partition. This package is kept up to date by the
is kept up to date by the overlay applied by this package, so you overlay applied by this package, so you don't need configure this. However, if
don't need configure this. However, if you want to use different you want to use different firmware you can override that package to do so.
firmware you can override that package to do so.
## What's not working? ## What's not working?
- [ ] Pi 5 u-boot devices other than sd-cards (i.e. usb, nvme). - [ ] Pi 5 u-boot devices other than sd-cards (i.e. usb, nvme).