# Yocto FCB1010 Looper System - Implementation Guide

## Project Overview

Build a minimal, real-time Linux system for an audio looper pedal using Yocto Project. The system boots from initramfs only for maximum speed, includes RT kernel patches, and supports over-the-air updates via SWUpdate with A/B partitioning.

**Key Requirements:**
- x64 hardware (NUC-class)
- Static IP: 192.168.0.25
- SSH access with public key authentication
- USB live installer that can dd copy to disk
- A/B partition scheme for reliable updates
- RT kernel with PREEMPT_RT
- JACK audio stack
- SWUpdate for OTA updates

## Architecture Decisions

**Boot Strategy:** EFI boot → initramfs-only (no rootfs mounting)
**Network:** WiFi with static IP, credentials baked into image
**Updates:** SWUpdate web interface + SSH API access
**Installation:** USB boot → SSH → dd copy entire USB to target disk
**Partition Layout:** EFI boot partition with initramfs-A.cpio.gz and initramfs-B.cpio.gz

## Yocto Implementation Approach

**Custom Layer Structure:**
Create meta-looper with recipes for kernel config (RT patches), network setup (static IP + WiFi), SSH keys, audio stack (JACK), and two image types: main system (initramfs) and USB installer.

**Build Configuration:**
- MACHINE = "genericx86-64"
- Kernel: linux-yocto with RT features
- Minimal install, not Pokey distribution

## Key Implementation Points

**Kernel:** Enable PREEMPT_RT, high-res timers, and audio subsystem. Use kernel fragment files (.cfg) to configure RT options.

**Networking:** Create recipes for wpa_supplicant.conf and network interfaces with static IP. Include WiFi credentials at build time.

**SSH:** Recipe to install public key to root's authorized_keys during image build.

**SWUpdate:** Configure for A/B updates, web interface on port 8080, and integration with systemd-boot for partition switching.

**USB Installer:** Second image that boots live system with installation script. Script partitions target disk, creates EFI boot partition, and dd copies the installer image to create installed system.

## Running
The build and testing platform is built in Docker. A Compose file is used to script the separate targets:
- docker compose run disk-image
- docker compose run qemu-server
- docker compose run push-update
- docker compose run ssh-client

The compose file mounts the proper directories for cache, output, ... It also forwards the proper ports for qemu.

The run script wraps docker compose run and adds some environment variables.

## Testing Strategy for AI Agent

**QEMU Testing:** Use runqemu with network forwarding to test SSH, networking, and SWUpdate functionality. QEMU supports graphics for GUI testing and USB forwarding for hardware validation.

**Build Validation:** Verify initramfs size (<200MB), boot time (<10 seconds), and RT kernel configuration. Test static IP assignment and SSH key authentication.

**Update Testing:** Create test SWUpdate packages and verify A/B switching works correctly. Test both web interface and SSH-based update deployment.

**Audio Validation:** Confirm JACK installation, RT scheduling capabilities with cyclictest, and audio device detection.

**Installation Testing:** Boot USB installer in QEMU, SSH in, run installation script on virtual disk, then boot installed system to verify complete workflow.

The implementation should focus on creating minimal, working recipes that can be tested incrementally in QEMU before hardware deployment. Each component (kernel, network, SSH, audio, updates) should be testable independently.