Raspberry Pi Alexa Voice Assistant: Hardware Decisions and AVS SDK Debugging

Building a custom Raspberry Pi Alexa device using the Amazon Alexa Voice Service (AVS) Device SDK is a benchmark embedded project. It forces you to navigate I2S audio routing, digital signal processing (DSP) for wake-word detection, and Linux audio server management. However, the transition to Raspberry Pi OS Bookworm—and its default shift from PulseAudio to PipeWire—has broken legacy AVS SDK tutorials. If you are following a guide from 2022, your audio routing will fail.

This guide cuts through the outdated forum posts. We will make concrete hardware decisions, map the exact I2S pins, provide robust GPIO control code, and debug the specific ALSA/PipeWire errors that stall modern Pi Alexa builds.

The Hardware Decision Matrix

Before writing code, you must select the compute module and the audio interface. The Raspberry Pi 5 introduced changes to the 40-pin header's I2S routing and physical clearance that complicate standard audio HATs. For a frictionless AVS SDK build in 2026, the Raspberry Pi 4 Model B (4GB) remains the definitive target board.

Concrete Pick: The Seeed Studio ReSpeaker 2-Mics Pi HAT. It uses the WM8960 I2S codec, includes an onboard JST connector for a 3W speaker, and breaks out GPIO 17 for a physical tap-to-talk button.

Complete Parts List

• Compute: Raspberry Pi 4 Model B (4GB RAM) - ~$55
• Audio HAT: Seeed Studio ReSpeaker 2-Mics Pi HAT (WM8960) - ~$12
• Transducer: 3W 4-Ohm Speaker with JST-PH 2.0 connector - ~$5
• Power: Official Raspberry Pi 27W USB-C PD Power Supply (crucial to prevent brownouts when the WM8960 amplifier peaks) - ~$12
• Storage: 32GB Samsung EVO Plus microSD (Class 10, A2) - ~$8

Pin Mapping and Physical Assembly

The ReSpeaker 2-Mic HAT communicates via the I2S (PCM) bus for audio and I2C for codec configuration. It also uses SPI for the onboard APA102 RGB LEDs. Below is the exact BCM-to-Physical pin mapping required for your device tree overlays and GPIO scripts.

1. Flash Raspberry Pi OS (64-bit, Bookworm) to the microSD card using Raspberry Pi Imager. Enable SSH and configure your WiFi in the OS customization menu.
2. Boot the Pi and run sudo apt update && sudo apt upgrade -y.
3. Install the Seeed audio driver: git clone https://github.com/respeaker/seeed-voicecard.git && cd seeed-voicecard && sudo ./install.sh.
4. Reboot. Verify the I2S overlay loaded by checking dmesg | grep wm8960. You should see the codec initializing.

AVS SDK Audio Routing in the PipeWire Era

The most common failure point for Raspberry Pi Alexa builds today is the audio server. Raspberry Pi OS Bookworm uses PipeWire by default, which intercepts ALSA calls. The AVS SDK sample app expects direct ALSA access to apply its Acoustic Echo Cancellation (AEC) algorithms. If PipeWire intercepts the stream, the AEC fails, and Alexa hears her own voice as an echo, causing infinite loops.

You must configure ALSA to bypass PipeWire for the AVS SDK process. Create or edit the ALSA configuration file at ~/.asoundrc:

pcm.!default {
  type asym
  playback.pcm "plug:dmix"
  capture.pcm "plug:dsnoop"
}

pcm.dmix {
  type dmix
  ipc_key 1024
  slave.pcm "hw:seeed2micvoicec,0"
}

pcm.dsnoop {
  type dsnoop
  ipc_key 1025
  slave.pcm "hw:seeed2micvoicec,0"
}

This configuration forces the AVS SDK to use the hardware device (hw:seeed2micvoicec,0) via the dmix and dsnoop plugins, entirely sidestepping the PipeWire session manager. Consult the official Amazon AVS documentation for the CMake build flags required to compile the SDK with ALSA support rather than PortAudio.

GPIO Control: Physical Tap-to-Talk Code

While 'Alexa' is the default wake word, a physical tap-to-talk button is essential for noisy environments or when the wake-word engine is disabled to save CPU cycles. The AVS SDK sample app runs in a terminal and listens for the 't' keystroke to trigger dialogue. We will use a Python daemon to monitor GPIO 17 and inject that keystroke via tmux.

Target Board: Raspberry Pi 4 Model B (4GB)
OS: Raspberry Pi OS Bookworm (64-bit)
Dependencies: sudo apt install python3-gpiozero tmux

import time
import sys
import subprocess
from gpiozero import Button
from signal import pause

# Pin Definitions for ReSpeaker 2-Mic HAT
TALK_BUTTON_PIN = 17
TMUX_SESSION_NAME = 'avs'

def handle_button_press():
    '''
    Injects a 't' keystroke into the tmux session running the AVS Sample App.
    '''
    try:
        # Send the 't' key to the AVS session to trigger tap-to-talk
        subprocess.run(
            ['tmux', 'send-keys', '-t', TMUX_SESSION_NAME, 't'],
            check=True,
            capture_output=True
        )
        print('[INFO] Tap-to-talk triggered via GPIO 17.')
    except subprocess.CalledProcessError as e:
        print(f'[ERROR] tmux command failed. Is the AVS session running?\n{e.stderr.decode()}')
    except FileNotFoundError:
        print('[FATAL] tmux binary not found. Install via: sudo apt install tmux')
        sys.exit(1)

if __name__ == '__main__':
    try:
        # Initialize button with internal pull-up, 50ms debounce
        talk_button = Button(TALK_BUTTON_PIN, pull_up=True, bounce_time=0.05)
        talk_button.when_pressed = handle_button_press
        
        print(f'[INFO] Alexa GPIO Daemon active. Monitoring Pin {TALK_BUTTON_PIN}.')
        print('[INFO] Ensure AVS SampleApp is running in a tmux session named "avs".')
        
        # Block main thread efficiently
        pause()
        
    except ImportError as e:
        print(f'[FATAL] Missing library: {e}. Run: sudo apt install python3-gpiozero')
        sys.exit(1)
    except Exception as e:
        print(f'[FATAL] Unexpected GPIO initialization error: {e}')
        sys.exit(1)

Run the AVS sample app inside tmux first: tmux new -s avs, then execute your ./SampleApp binary. Start the Python script in a second terminal or as a background systemd service.

Debugging: When the Wake Word Fails

When your Raspberry Pi Alexa build refuses to respond to the wake word, the failure is almost always in the audio capture pipeline or the Sensory/Kitt.AI wake-word engine licensing. Do not rewrite your code; check the logs.

First Three Things to Check

1. Verify Hardware Enumeration: Run arecord -l. You must see card 1: seeed2micvoicec [seeed-2mic-voicecard]. If it shows as card 0, your ~/.asoundrc indices are wrong.
2. Check PipeWire Interference: Run systemctl --user status pipewire. If it is active and you haven't applied the ~/.asoundrc bypass, PipeWire is holding the PCM device open.
3. Verify I2C/I2S Overlays: Run cat /boot/firmware/config.txt | grep i2s. You must see dtoverlay=seeed-2mic-voicecard. If missing, the driver install script failed.

Exact Error Strings and Ranked Causes

Extending or Simplifying the Build

Once the base Raspberry Pi Alexa assistant is operational, you must decide whether to scale the project for home automation or strip it down for a kiosk deployment.

How to Simplify (Kiosk / Appliance Mode)

If you are building a dedicated voice-controlled appliance (like a smart mirror or kitchen timer) and do not need the full AVS SDK overhead, abandon the C++ SDK entirely. Use the Alexa Gadgets API or a lightweight Python wrapper like alexa-remote2 via Node.js to send predefined commands. Alternatively, for pure TTS/STT without the Amazon ecosystem, pivot to the Rhasspy offline voice assistant, which runs natively on the Pi 4 without cloud authentication.

How to Extend (Smart Home Hub)

To turn your Pi Alexa into a local smart home bridge, integrate Home Assistant. Run Home Assistant OS in a Docker container alongside the AVS SDK. Use the ha-mqtt-remote Python library to intercept Alexa's smart home skill intents and publish them to a local Mosquitto MQTT broker. This allows Alexa to control Zigbee/Matter devices connected to the Pi's USB radios with sub-50ms local latency, bypassing the cloud round-trip.

Final Recommendation: Do not overcomplicate your first build. Order the Raspberry Pi 4 (4GB) and the ReSpeaker 2-Mic HAT. Flash Bookworm, apply the ALSA bypass, and get the wake word responding reliably before attempting MQTT integrations or 3D-printed acoustic enclosures. Master the I2S routing first; the smart home features are just software on top of a stable audio pipeline.