⚠️ Work in progress, use at your own risk...
A minimal flake to run NixOS on RK3588/RK3588s based SBCs, support both UEFI & U-Boot.
Since this flake was started, some boards (Pi 5, Pi 5 Plus) got upstream Nixpkgs support. The upstream support does not cover all boards yet, and has some differences with vendor-provided kernel (for example, different NPU interfaces). The flake still exists to provide system configs and SD card images based on vendor kernel and U-Boot, since some may prefer them over upstream at the moment.
If you want to make an SD card image for your board using upstream packages (without using this flake), see this example config for Pi 5 Plus. If the example config works for you, you don't need this flake.
UEFI support:
| Singal Board Computer | Boot from SD card | Boot from SSD |
|---|---|---|
| Orange Pi 5 | ✔️ | ✔️ |
| Orange Pi 5 Plus | ✔️ | ✔️ |
| Rock 5A | 🚫 | 🚫 |
U-Boot support:
| Singal Board Computer | Boot from SD card | Boot from SSD |
|---|---|---|
| Orange Pi 5 | ✔️ | ✔️ |
| Orange Pi 5 Plus | ✔️ | ✔️ |
| Rock 5A | ✔️ | 🚫 |
- UEFI support for Rock 5A, Rock 5B, Orange Pi 5B, NanoPI R6C, NanoPi R6S.
- verify all the hardware features available by RK3588/RK3588s
- ethernet (rj45)
- m.2 interface(pcie & sata)
- wifi/bluetooth
- audio
- gpio
- uart/ttl
- gpu(mali-g610-firmware + panthor)
- npu (works with rkllama, tested on OPi 5 Plus)
- ...
Default user: rk, default password: rk3588
The SD card images built using this flake do not embed a bootloader,
and won't boot directly on a new board
(unlike Armbian images that do embed U-Boot and just run out of the box).
You have to manually install a bootloader (UEFI or U-Boot) into the SPI flash of your board.
To do that, you boot into an Armbian image and write a precompiled bootloader image into your SPI block device under /dev
— detailed instructions are given under links below.
Once a bootloader is in SPI, you can boot NixOS images from this repo
(although make sure your NixOS config is set to use the right bootloader).
This flake supports UEFI and U-Boot, here are the install steps:
I personally recommend running U-Boot, as our support for UEFI has known bugs (#1).
Feel free to drop a testing report in the associated discussions page.
See Debug.md
You can use this flake as an input to build your own configuration. Here is an example configuration that you can use as a starting point: Demo - Deployment.
The demo above uses Colmena with remote deployments.
If you want something more basic, just create a regular system config with flakes
and import nixos-rk3588.nixosModules.${board} as well as nixos-rk3588.nixosModules.${board}.sd-image
modules provided by this flake.
A complete Linux system typically consists of five components:
- Bootloader (typically U-Boot or EDKII)
- Linux kernel
- Device trees
- Firmwares
- Root file system (rootfs)
Among these, the bootloader, the kernel, device trees, and firmwares are hardware-related and require customization for different SBCs. On the other hand, the majority of content in the rootfs is hardware-independent and can be shared across different SBCs.
Hence, the fundamental approach here is to use the hardware-specific components(bootloader, kernel, and device trees, firmwares) provided by the vendor(orangepi/rockpi/...), and combine them with the NixOS rootfs to build a comprehensive system.
Regarding RK3588/RK3588s, a significant amount of work has been done by Armbian on their kernel, and device tree. Therefore, by integrating these components from Armbian with the NixOS rootfs, we can create a complete NixOS system.
The primary steps involved are:
- Bootloader: Since no customization is required for U-Boot or edk2-rk3588, it's also possible to directly use the precompiled image from armbian, edk2-rk3588, or the hardware vendor.
- Build the NixOS rootfs using this flake, leveraging the kernel and device tree provided by armbian.
- To make all the hardware features available, we need to add its firmwares to the rootfs. Since there is no customization required for the firmwares too, we can directly use the precompiled firmwares from Armbian & Vendor too.
And I also got a lot of help in the NixOS on ARM Matrix group!