BadgeOS
This manual is for BadgeOS 2.1.0 on NixOS 26.05.20261031.fa13731. Want to skip the build? Grab an SD card image for your badge or LicheeRV Nano.
BadgeOS is NixOS for the Nix Vegas DEF CON badge, and for the Sipeed LicheeRV Nano. The badge is a small single board computer built around a Milk-V Duo Module 01, whose Sophgo SG2000 has two very different CPUs in it, an ARM Cortex-A53 and a RISC-V C906. The SD card has a complete NixOS install for each of them, and you pick which one boots (see Switching CPU cores). The Nano’s SG2002 has the same two cores, and a strap resistor on the board picks one (see The LicheeRV Nano).
Everything on the badge comes from one repository and is built with Nix, including the kernel, the bootloader, the system for each core, and even the LED patterns and OLED screens, which are small Nix functions that the badge evaluates every frame.
Where to start
If you just got a badge, Getting started walks through booting it, logging in, and getting it on a network, and Profiles and buttons covers the desktop and the video player.
If you want to change what the LEDs and the OLED show, LED ring and OLED screens explains how the patterns and screens work and how to write your own on the badge itself.
If you want to keep running BadgeOS without the SD card, Installing to the eMMC moves it onto the badge’s own storage, and Updating covers keeping it current afterwards.
If you’re working on other SG200x hardware, How BadgeOS boots describes the storage layout and the boot chain, and Using the NixOS module shows how to use BadgeOS as a board support package in your own flake. The SoM covers the SG2000 itself, what doesn’t work yet, and JTAG, and Contributing covers working on BadgeOS itself.
If something isn’t working, try Troubleshooting, and Security covers the default login and what the badge exposes.
The options reference lists every option we declare, and there’s a search page for it too.
Note
Working on BadgeOS with an LLM? Go for it. See Using LLMs on BadgeOS before you send a pull request.
The hardware
This is the short version; The hardware has the connectors, the pinouts and what the silkscreen labels mean.
| Part | What BadgeOS does with it |
|---|---|
| SG2000: ARM Cortex-A53 and RISC-V C906 | Boots either one (switching cores) |
| 24 WS2812 LEDs on SPI3 | Runs Nix patterns on them from early boot |
| SAO connector, I2C OLED (SSD1306 or SH1106) | Status screens and effects, also written in Nix |
| Sharp Memory Display header | The text console (tty1) |
| HDMI out, through an LT8912B MIPI-DSI bridge | Desktop and video profiles, with HDMI audio |
| AIC8800 WiFi and Bluetooth | NetworkManager and BlueZ |
| 10/100 Ethernet | The badge’s own network, routed out over WiFi, with netboot |
| USB-C | A USB network link to your computer on the same network, or a USB host port in the desktop profile |
| eMMC | An optional install target with A/B updates |
| BOOT, RESET and BUTTON | BOOT and BUTTON pick a profile at power-up, and BUTTON also drives the LEDs and screens |
| AA battery pack, voltage-sense ADCs | nix-badge power shows the rails and the battery |
The AA batteries are there because we accidentally ordered a lot of them for last year’s badge, and this one needed to use them somehow.
Source
BadgeOS lives at github.com/NixVegas/BadgeOS under the LGPL-3.0. The bootloader builds and our SG2000 mask ROM research are in NixVegas/sophgone, and the PCB is on git.nixos.lv since it doesn’t fit on GitHub anymore. Last year’s ESP32-C6 badge has its own README.