Nocturne (usenocturne/nocturne)

Nocturne

https://github.com/usenocturne/nocturne
Admin
Nocturne is an advanced custom firmware for the Spotify Car Thing that enables enhanced...

Tokens:5,131
Snippets:47
Trust Score:8.4
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# Nocturne

Nocturne is an advanced custom firmware for the Spotify Car Thing, transforming the discontinued streaming device into a fully functional standalone unit. The project provides a complete Linux-based operating system built on Void Linux with a custom web UI, allowing users to continue using their Car Thing hardware with enhanced features including Bluetooth tethering, USB networking, and Wi-Fi connectivity through companion devices.

The build system generates flashable firmware images using a staged approach, pulling together components from multiple subprojects (nocturne-ui, nocturned daemon, and wingman management tool). It creates both full installation images and incremental update packages, supporting automated OTA updates. The firmware runs a Chromium kiosk displaying the Nocturne web interface, with network connectivity via USB gadget mode or Bluetooth tethering.

## Build System

### Main Build Script

The primary build orchestrator that executes all build stages sequentially, creating a complete flashable firmware image for the Spotify Car Thing.

```bash
# Build configuration variables (can be overridden via environment)
export NOCTURNE_IMAGE_VERSION="v3.0.0"
export NOCTURNE_UI_TAG="main"
export NOCTURNED_TAG="v1.0.16"
export WINGMAN_TAG="v1.0.1"
export DEFAULT_HOSTNAME="nocturne"
export DEFAULT_ROOT_PASSWORD="nocturne"
export SIZE_ROOT_FS="516M"

# Prerequisites - download stock files first
cd resources/stock-files && ./download.sh
cd ../..

# Run the build (requires root/sudo)
sudo ./build.sh

# Output files are created in ./output/
# - nocturne_image_v3.0.0.zip (full flashable image)
# - nocturne_update_v3.0.0.tar.zst (incremental update package)
```

### Docker Build

Containerized build environment that handles all dependencies automatically, ideal for reproducible builds without modifying the host system.

```bash
# Set up QEMU for ARM cross-compilation (required on non-ARM hosts)
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# Build the Docker image
docker build -t nocturne-builder .

# Run the build in container (outputs to ./output/)
docker run --rm --privileged -v ./output:/work/output nocturne-builder:latest

# Or use the Justfile shortcuts
just docker-qemu    # Setup QEMU
just docker-build   # Build Docker image
just docker-run     # Run full build in container
```

### Justfile Commands

Task runner configuration providing convenient shortcuts for common build and development operations.

```bash
# List all available commands
just -l
# Available recipes:
#   build
#   copy
#   lint
#   run
#   shell

# Run native build with sudo
just run

# Lint all scripts with pre-commit hooks
just lint

# Docker workflow (full pipeline)
just docker-qemu && just docker-run
```

## Build Stages

### Stage 00 - Prepare Root Filesystem

Initializes the base Void Linux ARM rootfs and installs core packages using XBPS package manager.

```bash
# Stage 00 scripts execute in order:
# 00-echo.sh      - Print stage header
# 10-create-directories.sh - Create working directories
# 20-cache.sh     - Setup build cache
# 30-xbps.sh      - Install Void Linux base system
# 40-resolv.conf.sh - Configure DNS resolution
# 50-stock-files.sh - Copy proprietary binaries from stock firmware

# The XBPS stage downloads and configures base system:
curl -L https://repo-default.voidlinux.org/live/current/void-armv7l-ROOTFS-${VOID_BUILD}.tar.xz | tar -xJ -C "$ROOTFS_PATH"
xbps-install -r "$ROOTFS_PATH" -Suy xbps
xbps-install -r "$ROOTFS_PATH" --repository "$RES_PATH"/xbps -y base-nocturne
```

### Stage 10 - System Configuration

Configures essential system services including SSH, networking, display output, and Bluetooth.

```bash
# Network configuration creates USB gadget for tethering
# Static IP: 172.16.42.2 on the Car Thing
# Host expects: 172.16.42.1 (gateway)

# NetworkManager connection for USB ethernet
cat > "$ROOTFS_PATH"/etc/NetworkManager/system-connections/usb0.nmconnection << EOF
[connection]
id=usb0
type=ethernet
interface-name=usb0
autoconnect=true

[ipv4]
method=manual
address1=172.16.42.2/24,172.16.42.1
dns=1.1.1.1;8.8.8.8;
EOF

# Bluetooth tethering interface
cat > "$ROOTFS_PATH"/etc/network/interfaces << EOF
auto lo
iface lo inet loopback

auto bnep0
iface bnep0 inet dhcp
EOF
```

### Stage 20 - Nocturne Application Setup

Installs the Nocturne-specific components: daemon, web UI, and management tools from GitHub releases.

```bash
# Install nocturned daemon from GitHub releases
"$HELPERS_PATH"/github_releases.sh -r usenocturne/nocturned -a nocturned -v "$NOCTURNED_TAG" -d "$WORK_PATH"
install "$WORK_PATH"/nocturned "$ROOTFS_PATH"/usr/sbin/nocturned

# Download and install Nocturne UI (Vite + React web app)
curl -Lo "$WORK_PATH"/nocturne-ui.zip https://nightly.link/usenocturne/nocturne-ui/workflows/build/"$NOCTURNE_UI_TAG"/nocturne-ui.zip
mkdir -p "$ROOTFS_PATH"/etc/nocturne/ui
unzip "$WORK_PATH"/nocturne-ui.zip -d "$ROOTFS_PATH"/etc/nocturne/ui

# Write version file for OTA update system
echo "$NOCTURNE_IMAGE_VERSION" > "$ROOTFS_PATH"/etc/nocturne/version.txt
```

### Stage 40 - Image Generation

Creates the final flashable firmware image and update packages using genimage.

```bash
# Generate ext4 system image
m4 -D xFS=ext4 -D xIMAGE=system.xFS -D xLABEL="system" -D xSIZE="$SIZE_ROOT_FS" -D xUSEMKE2FS \
  "$RES_PATH"/m4/genimage.m4 > "$WORK_PATH"/genimage_root.cfg

genimage --rootpath "$ROOTFS_PATH" \
  --tmppath /tmp/genimage \
  --inputpath "${IMAGE_PATH}" \
  --outputpath "${IMAGE_PATH}" \
  --config "$WORK_PATH"/genimage_root.cfg

# Create zstd-compressed update package for OTA
tar -cf - -C "$UPDATE_PATH"/ . | zstd -9 -o "$IMAGE_PATH"/nocturne_update_"$NOCTURNE_IMAGE_VERSION".tar.zst
```

## Helper Scripts

### GitHub Releases Downloader

Utility script for fetching release assets from GitHub with optional SHA256 verification.

```bash
# Download specific version with checksum verification
./scripts/build-helpers/github_releases.sh \
  -r usenocturne/nocturned \
  -a nocturned \
  -v v1.0.16 \
  -d /tmp/downloads

# Download latest version (no -v flag)
./scripts/build-helpers/github_releases.sh \
  -r usenocturne/wingman \
  -a wingman \
  -d /tmp/downloads

# Skip SHA256 verification with -s flag
./scripts/build-helpers/github_releases.sh \
  -r usenocturne/nocturne-ui \
  -a nocturne-ui.zip \
  -s \
  -d /tmp/downloads
```

### Chroot Executor

Runs commands inside the target rootfs using chroot, with optional script copying.

```bash
# Run a command directly in chroot
./scripts/build-helpers/chroot_exec.sh /bin/sh -c "xbps-reconfigure -fa"

# Copy and execute a script inside chroot (-c flag)
./scripts/build-helpers/chroot_exec.sh -c /path/to/setup-script.sh

# Change default shell for root user
./scripts/build-helpers/chroot_exec.sh chsh -s /bin/bash root
```

### Stock Files Downloader

Downloads and extracts proprietary components from official Spotify Car Thing firmware required for hardware support.

```bash
# Run from the stock-files directory
cd resources/stock-files
sudo ./download.sh

# Environment variables to customize firmware source
export FIRMWARE_ID="P3QZbZIDWnp5m_azQFQqP"
export VERSION_ID="Sn_vBLpPfJjic6DZtCj6k"
export FILE_ID="IVXX0JDs_B5nDGs5Om0it"
./download.sh

# Extracted files include:
# - Chromium browser binaries
# - Weston compositor and libraries
# - Mali GPU drivers (libMali.so)
# - Kernel modules for Car Thing hardware
# - Hardware control utilities (phb, uenv, sp-als-backlight)
```

## Services

### USB Gadget Service

Configures the Car Thing as a USB RNDIS network device, enabling internet sharing from connected computers.

```bash
# Service location: /etc/sv/usb-gadget/run
# Creates USB gadget at /sys/kernel/config/usb_gadget/g1

# USB device identification:
# Vendor ID:  0x0000 (Linux)
# Product ID: 0x1014 (Multifunction Device)
# Manufacturer: "Vanta Labs"
# Product: "Nocturne"

# Network configuration:
# Device MAC: a0:b1:c2:d3:e4:00
# Host MAC:   a0:b1:c2:d3:e4:01
# Device IP:  172.16.42.2
# Host IP:    172.16.42.1 (gateway)
```

### Chromium Kiosk Service

Runs Chromium in kiosk mode displaying the Nocturne web interface with hardware acceleration.

```bash
# Service location: /etc/sv/chromium/run
# Waits for: weston, nocturne-ui, nocturned

# Chromium launch configuration
/usr/bin/chromium-browser/chrome \
  --no-sandbox \
  --in-process-gpu \
  --remote-debugging-port=2222 \
  --user-data-dir=/var/cache/chrome_storage \
  --kiosk \
  --disable-pinch \
  --allow-file-access-from-files \
  --ignore-certificate-errors \
  --enable-experimental-web-platform-features \
  --app=http://localhost:80

# Remote debugging available at port 2222
# Access via: chrome://inspect on connected computer
```

## Update System

### Update Template Configuration

Defines OTA update metadata structure for the Nocturne update system.

```json
{
  "version": "3.0.1",
  "tag": "v3.0.1",
  "minimumVersion": "3.0.0",
  "imageUrl": "https://usenocturne.com/images/versions/3.webp",
  "shortDescription": "This update brings new features and bug fixes.",
  "fullDescription": "This update brings new features and bug fixes.\n\n- feature 1\n- feature 2",
  "files": {
    "full": "nocturne_image_v3.0.1.zip",
    "update": "nocturne_update_v3.0.1.tar.zst"
  },
  "commands": {
    "pre": [],
    "post": []
  }
}
```

### First Boot Script

Handles initial device setup on first boot after flashing, resetting user data and settings.

```bash
# Kernel command line parameter triggers first boot:
# nocturne.firstboot=1

# First boot actions:
# 1. Reset user data to defaults
/sbin/reset-data

# 2. Reset system settings
/sbin/reset-settings

# 3. Clear firstboot flag for subsequent boots
/usr/bin/uenv set firstboot 0
```

## Host Setup (Windows)

### USB Network Configuration

PowerShell commands to configure internet sharing from Windows to the Car Thing via USB.

```powershell
# Requires Windows 10/11 Pro or Enterprise

# Find the Car Thing network adapter (RNDIS device)
$ctNic = (Get-NetAdapter -InterfaceDescription "*NDIS*")

# Configure static IP on host side (gateway for Car Thing)
$ctNic | Set-NetIPAddress -IPAddress 172.16.42.1 -PrefixLength 24

# Enable NAT for internet sharing
New-NetNat -Name "CarThing" -InternalIPInterfaceAddressPrefix 172.16.42.0/24

# Troubleshooting: Check for conflicts
Get-VMSwitch  # If Hyper-V is installed

# Install Hyper-V feature if Get-VMSwitch unavailable
Get-WindowsOptionalFeature -Online | Where-Object FeatureName -like '*Hyper-V*'
```

## Summary

Nocturne provides a comprehensive solution for repurposing Spotify Car Thing hardware after its discontinuation. The primary use case is creating a standalone music controller with modern features like Bluetooth tethering and Wi-Fi connectivity (via Nocturne Connector on Raspberry Pi). Developers can customize the firmware by modifying build stages, adjusting service configurations, or contributing to the subprojects (nocturne-ui for the interface, nocturned for the daemon, or wingman for device management).

Integration patterns center around the staged build system and runit service management. Custom functionality can be added by creating new build stage scripts in `scripts/stages/`, adding runit services in `scripts/services/`, or modifying system configuration through the resources directory. The Docker-based build ensures reproducibility across development environments, while the update template system enables seamless OTA firmware distribution to end users through the official Nocturne infrastructure.