# Raspberry Pi Zero 2 w Setup w/ Respeaker PiHat v2

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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](https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2023-10-10/2023-10-10-raspios-bookworm-arm64-lite.img.xz)) Flash using Raspberry Pi Imager v1.96 (download [here](https://github.com/raspberrypi/rpi-imager/releases/download/v1.9.6/imager-1.9.6.exe)). 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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#system-preparation)

SSH into the Pi: ``` ssh pi@ ```

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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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)

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#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

[](https://github.com/Jdiller-86/LocalAlexaReplacement#alsa-device-errors)

Use: ``` arecord -l ```

Then adjust: ``` plughw:X,Y ```

--- # Training Custom Wake Words

[](https://github.com/Jdiller-86/LocalAlexaReplacement#training-custom-wake-words)

To train a custom wake word go to [Google Colab](https://colab.research.google.com/drive/1q1oe2zOyZp7UsB3jJiQ1IFn8z5YfjwEb?usp=sharing#scrollTo=1cbqBebHXjFD) and follow the instructions to train a wake word using googles gpu time for free. --- ## References - [Getting Started with Raspberry Pi | Seeed Studio Wiki](https://wiki.seeedstudio.com/respeaker_2_mics_pi_hat_raspberry_v2/)