Skip to main content

Raspberry Pi Zero 2 w Setup w/ Respeaker Lite PiHat

Wyoming Satellite + OpenWakeWord Setup Guide

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)

Networking Stability Fix

Problem: Router reassigned Pi IP.

Solution:

Set DHCP reservation in router:

  • Bind Pi MAC address to fixed IP

OR

Set static IP in:

/etc/dhcpcd.conf

What Fixed Wake Word Recognition

The key issues were:

  1. Wrong audio format (not 16kHz mono)
  2. Missing prebuilt OpenWakeWord wheels
  3. Incorrect ALSA device selection
  4. Audio enhancement packages not installed

Once corrected:

  • Wake word detection became immediate and reliable
  • Changing wake word in HA began working

Common Problems & Fixes

Wake word not detecting

✔ Confirm 16kHz mono input
✔ Verify openwakeword selected
✔ Reinstall with prebuilt wheels
✔ Check mic device index

LEDs stuck on yellow

Cause: Default idle state color in led.py

Fix: Set idle color to (0, 0, 0) Restart satellite

Mic always streaming

Cause: VAD or state machine misconfiguration

Fix: Reinstall requirements_vad.txt

HA cannot reconnect

Cause: IP address changed

Fix: Reserve DHCP IP Restart integration

ALSA device errors

Use:

arecord -l

Then adjust:

plughw:X,Y

Recommended Improvements

  • Create systemd service for auto-start
  • Reserve static IP
  • Add physical mute LED indicator
  • Tune OpenWakeWord sensitivity if needed

Final Working Stack Summary

OS: Raspberry Pi OS Lite 64-bit (Bookworm)
Python: 3.11
Wyoming Satellite: latest main branch
Wake Engine: OpenWakeWord (prebuilt wheels)
Audio: ALSA plughw at 16kHz mono
Home Assistant: Wyoming Protocol integration

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

Back to top