### Application Component Installation

Source: https://context7.com/usenocturne/nocturne/llms.txt

Downloads and installs the Nocturne daemon and web UI components from GitHub releases into the target filesystem.

```bash
"$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
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
```

--------------------------------

### First Boot Script for Initial Setup

Source: https://context7.com/usenocturne/nocturne/llms.txt

Handles the initial device setup on the first boot after flashing. This script resets user data and system settings to defaults and clears the firstboot flag to prevent re-execution on subsequent boots. It is triggered by a kernel command line parameter.

```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
```

--------------------------------

### Install Hyper-V on Windows (if needed)

Source: https://github.com/usenocturne/nocturne/blob/main/README.md

Installs the Hyper-V optional Windows feature if the 'Get-VMSwitch' command is not found, which may be required for resolving network conflicts when configuring the Car Thing.

```powershell
Get-WindowsOptionalFeature -Online | Where-Object FeatureName -like '*Hyper-V*' | Enable-WindowsOptionalFeature -Online -NoRestart
```

--------------------------------

### Install Terbium Driver on Windows

Source: https://github.com/usenocturne/nocturne/blob/main/README.md

Installs the necessary Terbium driver on Windows using PowerShell. This is a prerequisite for flashing custom firmware onto the Car Thing.

```powershell
irm https://driver.terbium.app/get | iex
```

--------------------------------

### Root Filesystem Initialization

Source: https://context7.com/usenocturne/nocturne/llms.txt

Initializes the Void Linux ARM root filesystem using XBPS. It downloads the base system and installs the custom base-nocturne package.

```bash
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
```

--------------------------------

### Configure Network for Car Thing (PowerShell)

Source: https://context7.com/usenocturne/nocturne/llms.txt

This script configures the network adapter for the Car Thing, sets a static IP address on the host, and enables Network Address Translation (NAT) for internet sharing. It also includes troubleshooting steps to check for Hyper-V conflicts and install the Hyper-V feature if necessary.

```powershell
$ctNic = (Get-NetAdapter -InterfaceDescription "*NDIS*")
$ctNic | Set-NetIPAddress -IPAddress 172.16.42.1 -PrefixLength 24
New-NetNat -Name "CarThing" -InternalIPInterfaceAddressPrefix 172.16.42.0/24
Get-VMSwitch
Get-WindowsOptionalFeature -Online | Where-Object FeatureName -like '*Hyper-V*'
```

--------------------------------

### List Justfile build recipes

Source: https://github.com/usenocturne/nocturne/blob/main/README.md

Display the available commands defined in the project's Justfile. This helps developers identify the correct targets for building, linting, and running the project.

```bash
just -l
```

--------------------------------

### System Network Configuration

Source: https://context7.com/usenocturne/nocturne/llms.txt

Configures network interfaces for the Car Thing, including USB gadget mode for tethering and Bluetooth BNEP interface settings.

```bash
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

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

auto bnep0
iface bnep0 inet dhcp
EOF
```

--------------------------------

### Dockerized Build Environment

Source: https://context7.com/usenocturne/nocturne/llms.txt

Commands to build and run the Nocturne firmware within a containerized environment to ensure reproducibility. It handles cross-compilation using QEMU.

```bash
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
docker build -t nocturne-builder .
docker run --rm --privileged -v ./output:/work/output nocturne-builder:latest
```

--------------------------------

### U-Boot Bootloader Environment Configuration

Source: https://github.com/usenocturne/nocturne/blob/main/resources/flash/env.txt

A collection of environment variables and shell-like scripts used by U-Boot to manage the boot process, display initialization, and system recovery modes.

```U-Boot Script
check_charger=mw 0xFF6346DC 0x33000000;mw.b 0x1337DEAD 0x00 1;i2c dev 2;i2c read 0x35 0x3 1 0x1337DEAD;if cmp.b 0x1337DEAD 0x1330DEAD 1; then run storeboot;else osd open;osd clear;imgread pic logo bad_charger $loadaddr;bmp display $bad_charger_offset;bmp scale;vout output ${outputmode};while true; do sleep 1; if gpio input GPIOAO_3; then run splash_boot; fi; done;fi;

get_boot_slot=if test $active_slot = _a; then setenv sys_part mmcblk0p14 ;elif test $active_slot = _b; then setenv sys_part mmcblk0p15; fi

storeboot=boot_cooling;run check_button;run get_boot_slot;run storeargs;get_valid_slot;setenv bootargs ${bootargs} androidboot.slot_suffix=${active_slot};consume_boot_try;if imgread kernel ${boot_part} ${loadaddr}; then bootm ${loadaddr}; fi;run update;
```

--------------------------------

### Build Orchestration and Configuration

Source: https://context7.com/usenocturne/nocturne/llms.txt

The primary build script configuration and execution flow. It defines environment variables for component versions and triggers the build process to generate flashable images.

```bash
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"
cd resources/stock-files && ./download.sh
cd ../..
sudo ./build.sh
```

--------------------------------

### Stock Files Downloader Script

Source: https://context7.com/usenocturne/nocturne/llms.txt

Downloads and extracts proprietary components from official Spotify Car Thing firmware required for hardware support. It can be run from the stock-files directory and allows customization of the firmware source using environment variables.

```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
```

--------------------------------

### Justfile Task Automation

Source: https://context7.com/usenocturne/nocturne/llms.txt

Common task runner recipes for managing the Nocturne build lifecycle, including linting, native builds, and Docker workflows.

```makefile
just -l
just run
just lint
just docker-qemu && just docker-run
```

--------------------------------

### Configure Windows Network Adapter for Car Thing

Source: https://github.com/usenocturne/nocturne/blob/main/README.md

Configures the network adapter for the Car Thing on Windows 10/11 Pro or Enterprise using PowerShell. This enables internet sharing via USB tethering.

```powershell
$ctNic = (Get-NetAdapter -InterfaceDescription "*NDIS*")

$ctNic | Set-NetIPAddress -IPAddress 172.16.42.1 -PrefixLength 24

New-NetNat -Name "CarThing" -InternalIPInterfaceAddressPrefix 172.16.42.0/24
```

--------------------------------

### USB Gadget Service Configuration

Source: https://context7.com/usenocturne/nocturne/llms.txt

Configures the Car Thing as a USB RNDIS network device for internet sharing. This involves setting up the USB gadget in the sysfs and configuring network parameters like MAC addresses and IP addresses for both the device and the host.

```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)
```

--------------------------------

### Generate Firmware Image using genimage

Source: https://context7.com/usenocturne/nocturne/llms.txt

Generates the final flashable firmware image and update packages using genimage. This involves creating configuration files for ext4 system images and then executing genimage. Finally, it creates a zstd-compressed update package for OTA.

```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
```

--------------------------------

### USB Network Configuration for Windows Host

Source: https://context7.com/usenocturne/nocturne/llms.txt

Provides PowerShell commands for configuring internet sharing from a Windows host to the Car Thing via USB. This functionality requires Windows 10/11 Pro or Enterprise editions.

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

--------------------------------

### Write Version File for OTA Update System

Source: https://context7.com/usenocturne/nocturne/llms.txt

Writes the Nocturne image version to a file in the root filesystem, used by the OTA update system.

```bash
echo "$NOCTURNE_IMAGE_VERSION" > "$ROOTFS_PATH"/etc/nocturne/version.txt
```

--------------------------------

### Extract xbps-static binaries

Source: https://github.com/usenocturne/nocturne/blob/main/README.md

Safely extract the xbps-static tarball to the root filesystem. This command uses specific flags to prevent overwriting existing files or changing ownership/permissions.

```bash
sudo tar --no-overwrite-dir --no-same-owner --no-same-permissions -xvf xbps-static-latest.x86_64-musl.tar.xz -C /
```

--------------------------------

### GitHub Releases Downloader Script

Source: https://context7.com/usenocturne/nocturne/llms.txt

A utility script for fetching release assets from GitHub. It supports downloading specific versions, the latest version, and optionally verifies checksums using SHA256. The script can skip verification with the -s flag.

```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
```

--------------------------------

### Chromium Kiosk Service Configuration

Source: https://context7.com/usenocturne/nocturne/llms.txt

Runs Chromium in kiosk mode to display the Nocturne web interface with hardware acceleration. This service depends on weston, nocturne-ui, and nocturned. It configures Chromium with specific flags for kiosk operation, remote debugging, and user data management.

```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
```

--------------------------------

### Chroot Executor Script

Source: https://context7.com/usenocturne/nocturne/llms.txt

A script to execute commands inside a target root filesystem using chroot. It supports running commands directly, copying and executing scripts within the chroot environment using the -c flag, and changing user shells.

```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
```

--------------------------------

### Update Template Configuration for OTA

Source: https://context7.com/usenocturne/nocturne/llms.txt

Defines the metadata structure for Over-The-Air (OTA) updates in the Nocturne system. This JSON object specifies version details, image URLs, descriptions, filenames for full and update packages, and pre/post-update commands.

```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": []
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.