Skip to main content

Raspberry Pi Zero 2 w Setup w/ Respeaker Lite PiHat

WyomingPi SatelliteZero 2 + OpenWakeWordRespeaker PiHat 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:

      Wrong audio format (not 16kHz mono) Missing prebuilt OpenWakeWord wheels Incorrect ALSA device selection 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