Raspberry Pi Zero 2 w Setup w/ Respeaker PiHat v2

This document provides a complete, working setup guide for configuring a Raspberry Pi–based Wyoming Satellite with OpenWakeWord and Home Assistant.
Hardware Used
Raspberry Pi Zero 2w (with headers)
ReSpeaker 2-Mic Pi HAT (or compatible I2S mic + RGB LED board)
MicroSD Card (8GB+)
Stable 5V 3A power supply
Operating System
Raspberry Pi OS Lite (64-bit)
Debian Bookworm based
Kernel 6.x
Image used:
2023-10-10-raspios-bookworm-arm64-lite.img (download here)
Flash using Raspberry Pi Imager v1.96 (download here).
Enable SSH before first boot.
In the Raspberry Pi Imager after selecting the device and image you want to use it will prompt you to customize the system settings. Make sure you configure network settings so it will automatically connect to your network. You can also configure hostname and credentials here. Then, make sure to enable ssh in the services tab at the top of the menu. When you first ssh into the pi you may need to use the IP address and not the hostname, simply look for the hostname in your router settings and then find the associated IP.
System Preparation
SSH into the Pi:
ssh pi@<pi-ip>
Update system:
sudo apt update && sudo apt upgrade -y
Install required dependencies:
sudo apt install -y \
  python3 \
  python3-venv \
  python3-pip \
  git \
  libopenblas-dev \
  libatlas-base-dev \
  libportaudio2 \
  portaudio19-dev \
  python3-dev
Install Wyoming Satellite
Clone repository:
git clone https://github.com/rhasspy/wyoming-satellite.git
cd wyoming-satellite
Create virtual environment:
python3 -m venv .venv
Activate it:
source .venv/bin/activate
Upgrade pip tools:
pip install --upgrade pip wheel setuptools
Install dependencies (CRITICAL STEP):
pip install -f 'https://synesthesiam.github.io/prebuilt-apps/' \
  -r requirements.txt \
  -r requirements_audio_enhancement.txt \
  -r requirements_vad.txt
This ensures prebuilt OpenWakeWord and audio wheels are used.
Enable and Verify Audio
List devices:
arecord -l
Test mic:
arecord -f cd test.wav
aplay test.wav
If no audio:
Check HAT seating
Enable I2S in raspi-config
Reboot
Running Wyoming Satellite
Basic working command:
./script/run \
  --name "kitchen" \
  --uri tcp://0.0.0.0:10700 \
  --wake openwakeword \
  --wake-model "ok_nabu" \
  --mic-command "arecord -D plughw:1,0 -r 16000 -c 1 -f S16_LE" \
  --snd-command "aplay -D plughw:1,0"
Key Working Details:
16kHz mono input is REQUIRED
plughw avoids ALSA format mismatch errors
openwakeword must be explicitly selected
Home Assistant Integration
In Home Assistant:
Settings → Devices & Services → Add Integration → Wyoming Protocol
Enter:
Host: Port: 10700
If Pi IP changes, update router DHCP reservation or update HA integration.
LED Customization
LED logic is controlled in:
wyoming_satellite/led.py
To keep LEDs OFF until wake word detected:
Modify idle/streaming state color to black:
self.color = (0, 0, 0)
Restart service after edits.
Mapping Hardware Button (Mute Toggle)
In main loop, map GPIO button press to:
Toggle mic active state
Set LED color to black when muted
Pseudo-logic:
if button_pressed:
    mic_enabled = not mic_enabled
    if not mic_enabled:
        self.color = (0, 0, 0)
Common Problems & Fixes
LEDs stuck on yellow
Cause: Default idle state color in led.py
Fix: Set idle color to (0, 0, 0) Restart satellite
ALSA device errors
Use:
arecord -l
Then adjust:
plughw:X,Y
Training Custom Wake Words
To train a custom wake word go to Google Colab and follow the instructions to train a wake word using googles gpu time for free.
References
Getting Started with Raspberry Pi | Seeed Studio Wiki