uConsole CM4 — NixOS SD Image

NixOS flake for building a bootable SD card image for the ClockworkPi uConsole (Raspberry Pi CM4 variant).

Hardware

• Device: ClockworkPi uConsole
• Core Module: Raspberry Pi Compute Module 4 (BCM2711, ARM64)
• Display: Built-in panel (works)
• Input: Built-in keyboard (works)
• Connectivity: WiFi (works), Bluetooth (untested)

Dependencies

Flake Inputs

Input	Source	Purpose
nixpkgs	github:NixOS/nixpkgs/nixos-unstable	NixOS packages and modules (root input)
nixos-uconsole	github:nixos-uconsole/nixos-uconsole	uConsole-specific NixOS modules, kernel patches, and image builder

Transitive Dependencies

nixos-uconsole pulls in:

Dependency	Source	Purpose
nixpkgs (via uconsole)	github:NixOS/nixpkgs/nixos-25.11	Base NixOS system (pinned to 25.11)
nixos-rasperrypi	github:nvmd/nixos-raspberrypi (v1.20260317.0)	Raspberry Pi kernel, bootloader, device tree overlays
argononed	github:nvmd/argononed (flake)	Raspberry Pi 4 argon1 fan control overlay
nixos-images	github:nvmd/nixos-images (sdimage-installer)	Pre-built SD image infrastructure
flake-compat	github:edolstra/flake-compat	Flake compatibility layer

Runtime Packages

Installed via configuration.nix:

Package	Purpose
niri	Scrollable-tiling Wayland compositor
xwayland-satellite	Xwayland support for non-Wayland apps
alacritty	Terminal emulator
fuzzel	Application launcher
waybar	Status bar
mako	Notification daemon
swaylock	Screen locker
swayidle	Idle management daemon
swaybg	Wallpaper daemon
tuigreet	TUI login greeter (via greetd)
xdg-desktop-portal-gtk	XDG portal for file chooser, screen sharing

Quick Start

Build the SD Image

just
# or: nix build --system aarch64-linux ".#default"

Output: ./result/nixos-uconsole-cm4.img

Flash to SD Card

# Replace /dev/sdX with your SD card device
sudo dd if=./result/nixos-uconsole-cm4.img of=/dev/sdX bs=4M status=progress conv=sync

Update the Lockfile

nix flake update

Build System

Cross-Compilation

The flake is configured for cross-compilation from x86_64 → aarch64:

• Build host: x86_64-linux (your development machine)
• Target: aarch64-linux (uConsole CM4)
• Mechanism: packages.aarch64-linux tells Nix to build for the ARM64 target

Prerequisites for Cross-Compilation (non-NixOS hosts)

If building on a non-NixOS distro, you need QEMU user-mode emulation so Nix can run aarch64 binaries during the build.

Debian / Ubuntu / Linux Mint:

sudo apt install qemu-user-static binfmt-support
sudo update-binfmts --enable qemu-aarch64
ls /proc/sys/fs/binfmt_misc | grep aarch64  # should show: qemu-aarch64

Arch / CachyOS:

sudo pacman -S qemu-user-static qemu-user-static-binfmt
sudo systemctl restart systemd-binfmt
ls /proc/sys/fs/binfmt_misc | grep aarch64  # should show: qemu-aarch64

Build on Target (native)

If you already have a minimal NixOS on the uConsole:

sudo nixos-rebuild switch --flake .#default

Configuration

User Account

Edit configuration.nix line 3:

username = "cole";  # ← change to your username

Set authentication (pick one):

# Option 1: temporary password (change on first login)
users.users.${username}.initialPassword = "temp-password";

# Option 2: SSH key (recommended)
users.users.${username}.openssh.authorizedKeys.keys = [
  "ssh-ed25519 AAAA... your-key-here"
];

NixOS Options Reference

Key options in configuration.nix:

Option	Purpose
programs.niri.enable	Installs and enables the Niri Wayland compositor
services.greetd.enable	TUI display manager for Wayland sessions
security.polkit.enable	PolicyKit for system privileges
services.gnome.gnome-keyring.enable	Secret keyring (required by Niri)
xdg.portal.enable	XDG Desktop Portal for app integration
services.openssh.enable	SSH server (headless access)

Known Issues & Fixes

1. mkUconsoleSystem / mkUconsoleImage not found

Cause: Wrong function names. The nixos-uconsole flake exports mkUConsoleSystem and mkUConsoleImage (camelCase, via .lib).

Fix: Use nixos-uconsole.lib.mkUConsoleSystem and nixos-uconsole.lib.mkUConsoleImage.

2. ./configuration.nix path not found in flake

Cause: Nix flakes require all referenced paths to be git-tracked.

Fix: git add configuration.nix before building.

3. ./configuration.nix as string vs path literal

Cause: In NixOS modules, paths must be path literals, not strings.

Fix: Use [ ./configuration.nix ] not [ "./configuration.nix" ].

4. Cross-compilation fails with "cannot run aarch64 binaries"

Cause: Missing QEMU binfmt registration on non-NixOS hosts.

Fix: Install qemu-user-static and register binfmt (see prerequisites above).

5. greetd.tuigreet deprecation warning

Cause: pkgs.greetd.tuigreet was renamed to pkgs.tuigreet.

Fix: Use ${pkgs.tuigreet}/bin/tuigreet.

Project Structure

.
├── flake.nix          # Flake definition: inputs, outputs, build targets
├── flake.lock         # Locked dependency versions
├── configuration.nix  # NixOS system configuration (Niri, greetd, apps, user)
├── Justfile           # Build shortcut (`just` = `nix build --system aarch64-linux .#default`)
└── README.md          # This file

Future Work

• Noctalia Shell integration (unverified on ARM)
• Niri keybinding customization
• NetworkManager configuration for WiFi
• Sleep/suspend support
• Audio configuration