feat(lva-peripheral): add 03-stage-lva-2mic-peripheral image

New pi-gen stage that bakes the unmerged
genericJE/linux-voice-assistant feat/peripheral-led-light-entity
branch onto a 2-Mic HAT v2 + PiCompose image, alongside the
ReSpeaker 2-Mic peripheral container from the same branch's
examples/ReSpeaker 2mic HAT/ directory. The branch sits on top of
upstream PR #266 (omaramin-2000:leds-and-buttons-events) and adds
the Light entity, Rainbow effect, and peripheral-startup-wait — none
of which are in the published ghcr.io/ohf-voice/linux-voice-assistant
image yet, so both containers build from cloned source at first boot.

What's wired:

  - /compose/lva-peripheral/ deploys two services in one compose
    project so HA enumeration waits until the Light entity is
    registered: LVA started with --peripheral-startup-wait 8,
    peripheral with restart loop on a 3 s reconnect.
  - Dockerfile.local for LVA fixes upstream's `COPY ../wakewords/`
    path (which escapes the build context); the upstream Dockerfile
    is left in lva-src/ untouched as a reference.
  - SPI overlay enabled and `pi` added to spi/gpio groups so the
    peripheral container's `group_add: [spi, gpio]` resolves to host
    GIDs that grant device access.
  - lva-peripheral-gpiochip-fix.service rewrites the compose's
    /dev/gpiochip0 to /dev/gpiochip4 on Pi 5 (one-shot, before
    picompose.service) so the same compose file works on Pi 3 / 4 /
    Zero 2 W and Pi 5.
  - LVA commit SHA pinned at /compose/lva-peripheral/LVA_COMMIT.

CI:

  - build-2michat-v2-lva-peripheral target wired into build-all.yml
    with enable-rpi-imager-snippet: true, so the release ships with
    a Pi Imager JSON pointing directly at the .img.xz.

README in the stage covers post-flash verification (containers,
audio, peripheral API, HA discovery), log paths, and the manual
smoke-test exercises that drove the branch.

Author: genericJE

.github/workflows/build-all.yml

@@ -60,6 +60,20 @@ jobs:
       compression-level: 6
       custom-hostname: picompose
 
+  # 2MICHAT-v2 + LVA peripheral (smoke-test image for the unmerged
+  # genericJE/linux-voice-assistant feat/peripheral-led-light-entity branch:
+  # Light entity, Rainbow effect, ReSpeaker 2-Mic peripheral controller).
+  # Emits a single-image rpi-imager.json alongside the .img.xz.
+  build-2michat-v2-lva-peripheral:
+    uses: ./.github/workflows/build-image-template.yml
+    with:
+      image-name: PiCompose_2MicHat-v2_LVA-Peripheral
+      stage-list: stage0 stage1 stage2 ./01-stage-picompose ./02-stage-audiodriver-2michat-v2 ./03-stage-lva-2mic-peripheral ./04-stage-finish
+      compression: xz
+      compression-level: 6
+      custom-hostname: picompose
+      enable-rpi-imager-snippet: true
+
   # RESPEAKER-LITE
   build-respeaker_lite:
     uses: ./.github/workflows/build-image-template.yml

03-stage-lva-2mic-peripheral/01-lva-peripheral/01-run.sh

@@ -0,0 +1,79 @@
+#!/bin/bash -e
+
+# Stage that drops the LVA + ReSpeaker 2-Mic peripheral compose project into
+# the rootfs at /compose/lva-peripheral/. Both images are built from cloned
+# source on first boot, so the LVA peripheral API and the ReSpeaker
+# controller line up against the same unmerged branch:
+#
+#   genericJE/linux-voice-assistant : feat/peripheral-led-light-entity
+#
+# That branch is based on the in-flight upstream PR
+# omaramin-2000:leds-and-buttons-events (OHF-Voice/linux-voice-assistant#266)
+# plus the Light entity / Rainbow effect / peripheral-startup-wait commits.
+
+LVA_REPO_URL="${LVA_REPO_URL:-https://github.com/genericJE/linux-voice-assistant.git}"
+LVA_BRANCH="${LVA_BRANCH:-feat/peripheral-led-light-entity}"
+
+SRC="/tmp/lva-src-clone-$$"
+DEST="${ROOTFS_DIR}/compose/lva-peripheral"
+
+rm -rf "$SRC"
+echo "Cloning $LVA_REPO_URL ($LVA_BRANCH)..."
+git clone --depth 1 --branch "$LVA_BRANCH" "$LVA_REPO_URL" "$SRC"
+
+mkdir -p "$DEST/lva-src"
+
+# Copy LVA source minus history/tests/docs/examples to keep the image small.
+# The peripheral example lives under examples/ — we pull it out separately
+# below, so excluding examples/ from the LVA build context is safe.
+(cd "$SRC" && tar \
+    --exclude='.git' \
+    --exclude='tests' \
+    --exclude='docs' \
+    --exclude='examples' \
+    --exclude='*.egg-info' \
+    --exclude='.venv' \
+    --exclude='uv.lock' \
+    -cf - .) | (cd "$DEST/lva-src" && tar -xf -)
+
+# Peripheral controller (Dockerfile + compose.yml + respeaker_2mic_hat.py)
+# straight from the branch.
+mkdir -p "$DEST/peripheral"
+cp -r "$SRC/examples/ReSpeaker 2mic HAT/." "$DEST/peripheral/"
+
+# Pin the LVA commit baked into this image so the user can confirm which
+# build they have on the running Pi.
+LVA_HASH="$(cd "$SRC" && git rev-parse HEAD)"
+echo "$LVA_HASH" > "$DEST/lva-src/version_githash.txt"
+echo "$LVA_HASH" > "$DEST/LVA_COMMIT"
+
+# Compose project files we ship from this stage.
+install -v -m 644 files/lva-peripheral/docker-compose.yml "$DEST/docker-compose.yml"
+install -v -m 644 files/lva-peripheral/picompose.conf    "$DEST/picompose.conf"
+install -v -m 644 files/lva-peripheral/.env              "$DEST/.env"
+install -v -m 644 files/lva-peripheral/Dockerfile.lva    "$DEST/lva-src/Dockerfile.local"
+
+# Helper that rewrites /dev/gpiochip0 → /dev/gpiochip4 on Pi 5 (where the
+# 40-pin header sits on gpiochip4). Runs once before picompose deploys.
+install -v -D -m 755 files/lva-peripheral-gpiochip-fix.sh \
+    "${ROOTFS_DIR}/usr/local/sbin/lva-peripheral-gpiochip-fix.sh"
+install -v -D -m 644 files/lva-peripheral-gpiochip-fix.service \
+    "${ROOTFS_DIR}/etc/systemd/system/lva-peripheral-gpiochip-fix.service"
+
+# Group membership + SPI overlay + enable the gpiochip-fix unit inside the chroot.
+on_chroot << 'EOF'
+getent group spi  >/dev/null && usermod -aG spi  pi || true
+getent group gpio >/dev/null && usermod -aG gpio pi || true
+
+CONFIG=/boot/config.txt
+[ -f /boot/firmware/config.txt ] && CONFIG=/boot/firmware/config.txt
+[ -f /boot/firmware/usercfg.txt ] && CONFIG=/boot/firmware/usercfg.txt
+
+sed -i -e 's:#dtparam=spi=on:dtparam=spi=on:g' "$CONFIG" || true
+grep -q "^dtparam=spi=on$" "$CONFIG" || echo "dtparam=spi=on" >> "$CONFIG"
+
+systemctl daemon-reload
+systemctl enable lva-peripheral-gpiochip-fix.service
+EOF
+
+rm -rf "$SRC"

03-stage-lva-2mic-peripheral/01-lva-peripheral/files/lva-peripheral-gpiochip-fix.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=Pick the correct /dev/gpiochip for the LVA peripheral compose project
+ConditionPathExists=/compose/lva-peripheral/docker-compose.yml
+After=local-fs.target
+Before=picompose.service
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/lva-peripheral-gpiochip-fix.sh
+RemainAfterExit=yes
+
+[Install]
+WantedBy=multi-user.target

03-stage-lva-2mic-peripheral/01-lva-peripheral/files/lva-peripheral-gpiochip-fix.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+set -e
+
+# The compose file ships with /dev/gpiochip0 (Pi 3 / 4 / Zero 2 W). On Pi 5
+# the 40-pin GPIO header lives on /dev/gpiochip4 — mapping a non-existent
+# device through Docker fails the container start. Rewrite the compose
+# device line on the first boot we see a Pi 5, then drop a marker so we
+# never rewrite again (even if the user later edits the compose by hand).
+
+COMPOSE=/compose/lva-peripheral/docker-compose.yml
+MARKER=/compose/lva-peripheral/.gpiochip-tuned
+
+[ -f "$COMPOSE" ] || exit 0
+[ -f "$MARKER" ] && exit 0
+
+MODEL="$(tr -d '\0' </proc/device-tree/model 2>/dev/null || true)"
+
+case "$MODEL" in
+  *"Raspberry Pi 5"*)
+    echo "[lva-peripheral-gpiochip-fix] $MODEL — switching peripheral to /dev/gpiochip4"
+    sed -i 's:/dev/gpiochip0:/dev/gpiochip4:g' "$COMPOSE"
+    ;;
+  *)
+    echo "[lva-peripheral-gpiochip-fix] $MODEL — keeping /dev/gpiochip0"
+    ;;
+esac
+
+touch "$MARKER"

03-stage-lva-2mic-peripheral/01-lva-peripheral/files/lva-peripheral/.env

@@ -0,0 +1,20 @@
+# LVA env vars. Override values by editing this file on the boot partition;
+# the compose project re-reads it on every `docker compose up`.
+
+LVA_USER_ID="1000"
+LVA_USER_GROUP="1000"
+
+LVA_XDG_RUNTIME_DIR="/run/user/1000"
+LVA_PULSE_SERVER="/run/user/1000/pulse/native"
+LVA_PULSE_COOKIE="/run/user/1000/pulse/cookie"
+
+# Uncomment to pin specific ALSA/PulseAudio devices instead of letting LVA
+# fall back to the system default. Useful if multiple HATs are present.
+# AUDIO_INPUT_DEVICE="default"
+# AUDIO_OUTPUT_DEVICE="default"
+
+# Friendly name for HA. Defaults to the hostname when empty.
+# CLIENT_NAME="respeaker-2mic-test"
+
+# Set to 1 to enable verbose LVA debug logging.
+# ENABLE_DEBUG="1"

03-stage-lva-2mic-peripheral/01-lva-peripheral/files/lva-peripheral/Dockerfile.lva

@@ -0,0 +1,53 @@
+FROM python:3.12-slim-trixie
+
+ENV LANG=C.UTF-8
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONUNBUFFERED=1
+
+LABEL \
+    org.opencontainers.image.title="Linux-Voice-Assistant (peripheral-led-light-entity)" \
+    org.opencontainers.image.description="LVA built from genericJE/linux-voice-assistant feat/peripheral-led-light-entity for the ReSpeaker 2-Mic HAT smoke test" \
+    org.opencontainers.image.source="https://github.com/genericJE/linux-voice-assistant/tree/feat/peripheral-led-light-entity" \
+    org.opencontainers.image.licenses="Apache-2.0"
+
+# Mirrors upstream's runtime deps. avahi for zeroconf (HA discovery),
+# pulseaudio/pipewire/alsa for audio I/O, libmpv for python-mpv playback,
+# build-essential because pymicro-features ships sdist only.
+RUN apt-get update && \
+    apt-get install --yes --no-install-recommends \
+        avahi-utils \
+        pulseaudio-utils \
+        alsa-utils \
+        pipewire-bin \
+        pipewire-alsa \
+        pipewire-pulse \
+        build-essential \
+        libmpv-dev \
+        libasound2-plugins \
+        ca-certificates \
+        iproute2 \
+        procps && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Same layout as upstream's Dockerfile but with the wakewords/ COPY path
+# corrected (upstream's `COPY ../wakewords/` escapes the build context and
+# only works when CI sets up a non-default context).
+COPY script/ ./script/
+COPY pyproject.toml ./
+COPY setup.cfg ./
+COPY sounds/ ./sounds/
+COPY wakewords/ ./wakewords/
+COPY linux_voice_assistant/ ./linux_voice_assistant/
+COPY docker-entrypoint.sh ./
+COPY version.txt ./
+COPY version_githash.txt ./
+
+RUN chmod +x docker-entrypoint.sh && \
+    ./script/setup
+
+EXPOSE 6053 6055
+
+ENTRYPOINT ["./docker-entrypoint.sh"]

03-stage-lva-2mic-peripheral/01-lva-peripheral/files/lva-peripheral/docker-compose.yml

@@ -0,0 +1,120 @@
+---
+# Linux Voice Assistant + ReSpeaker 2-Mic HAT peripheral controller.
+#
+# Two services in one compose project so service ordering is local and HA
+# only enumerates the satellite's entities once both LVA and the peripheral
+# Light entity are registered. LVA is started with --peripheral-startup-wait 8
+# (see the `command:` override below) which gives the peripheral container
+# room to connect to ws://localhost:6055 before LVA accepts HA connections
+# on 6053.
+#
+# Both images are built locally from cloned source on first boot:
+#   ./lva-src    — genericJE/linux-voice-assistant feat/peripheral-led-light-entity
+#                  (Dockerfile.local, not the upstream Dockerfile)
+#   ./peripheral — the same branch's examples/ReSpeaker 2mic HAT/ directory
+#
+# GPIO device note: /dev/gpiochip0 is mapped for Pi 3 / 4 / Zero 2 W.
+# On Pi 5 the 40-pin header sits on /dev/gpiochip4 instead — the
+# `lva-peripheral-gpiochip-fix.service` (ordered Before=picompose.service)
+# rewrites this file once on first boot if it detects a Pi 5.
+
+services:
+  fix-permissions:
+    build:
+      context: ./lva-src
+      dockerfile: Dockerfile.local
+    image: lva-peripheral-lva:local
+    entrypoint: []
+    command: "chown -R ${LVA_USER_ID:-1000}:${LVA_USER_GROUP:-1000} /app/local /app/configuration /app/wakewords/custom /app/sounds/custom"
+    environment:
+      - XDG_RUNTIME_DIR=${LVA_XDG_RUNTIME_DIR:-/run/user/1000}
+      - PULSE_SERVER=${LVA_PULSE_SERVER:-/run/user/1000/pulse/native}
+      - PULSE_COOKIE=${LVA_PULSE_COOKIE:-/run/user/1000/pulse/cookie}
+    env_file: .env
+    group_add:
+      - audio
+    volumes:
+      - wakeword_data:/app/local
+      - wakeword_custom:/app/wakewords/custom
+      - configuration:/app/configuration
+      - sounds_custom:/app/sounds/custom
+    restart: "no"
+
+  linux-voice-assistant:
+    container_name: linux-voice-assistant
+    build:
+      context: ./lva-src
+      dockerfile: Dockerfile.local
+    image: lva-peripheral-lva:local
+    restart: unless-stopped
+    network_mode: host
+    user: "${LVA_USER_ID:-1000}:${LVA_USER_GROUP:-1000}"
+    environment:
+      - XDG_RUNTIME_DIR=${LVA_XDG_RUNTIME_DIR:-/run/user/1000}
+      - PULSE_SERVER=${LVA_PULSE_SERVER:-/run/user/1000/pulse/native}
+      - PULSE_COOKIE=${LVA_PULSE_COOKIE:-/run/user/1000/pulse/cookie}
+    env_file: .env
+    group_add:
+      - audio
+    cap_add:
+      - SYS_NICE
+    volumes:
+      - wakeword_data:/app/local
+      - wakeword_custom:/app/wakewords/custom
+      - configuration:/app/configuration
+      - sounds_custom:/app/sounds/custom
+      - /etc/localtime:/etc/localtime:ro
+      - /etc/timezone:/etc/timezone:ro
+      - ${LVA_XDG_RUNTIME_DIR:-/run/user/1000}:${LVA_XDG_RUNTIME_DIR:-/run/user/1000}
+    command:
+      - "--peripheral-startup-wait"
+      - "8"
+    depends_on:
+      - fix-permissions
+    healthcheck:
+      test: ["CMD", "pgrep", "-f", "linux_voice_assistant"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 90s
+
+  respeaker-peripheral:
+    container_name: respeaker-peripheral
+    build:
+      context: ./peripheral
+    image: lva-peripheral-respeaker:local
+    restart: unless-stopped
+    network_mode: host
+    user: "${LVA_USER_ID:-1000}:${LVA_USER_GROUP:-1000}"
+    devices:
+      - /dev/spidev0.0:/dev/spidev0.0
+      - /dev/gpiochip0:/dev/gpiochip0
+    group_add:
+      - gpio
+      - spi
+    environment:
+      - PYTHONUNBUFFERED=1
+    command:
+      - "--host"
+      - "localhost"
+      - "--port"
+      - "6055"
+    depends_on:
+      - linux-voice-assistant
+    healthcheck:
+      test: ["CMD", "pgrep", "-f", "respeaker_2mic_hat.py"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 15s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+volumes:
+  wakeword_data:
+  wakeword_custom:
+  configuration:
+  sounds_custom:

03-stage-lva-2mic-peripheral/01-lva-peripheral/files/lva-peripheral/picompose.conf

@@ -0,0 +1,19 @@
+# PiCompose deploy config for the LVA + ReSpeaker 2-Mic peripheral project.
+#
+# This stage is an unmerged-branch smoke test, not a production deploy.
+# We build locally on first boot from baked-in source (no pull) and stay
+# off the cron schedule to avoid trying to re-pull images we don't have
+# in any registry.
+
+DISABLED=false
+
+# Compose every boot. The build cache makes subsequent boots fast; this
+# just guarantees the containers are running after a power cycle.
+BOOT_ENABLED=true
+BOOT_IMAGE_PULL=false
+
+# No CRON for this smoke-test project — there's no upstream image to pull
+# and the LVA branch source is baked into the image.
+CRON_ENABLED=false
+CRON_SCHEDULE="0 4 * * *"
+CRON_IMAGE_PULL=false