Home Assistant Guide

What Is a Wyoming Satellite?

A Wyoming Satellite is a DIY voice‑enabled module - usually a Raspberry Pi - that connects to Home Assistant and handles your voice locally. It listens for your wake word, streams your voice for processing, and plays responses back through a speaker, all using the open "Wyoming" protocol. Unlike cloud-based systems, every step happens in your home.

Wyoming Satellite vs Home Assistant Voice Preview Edition

Here's a comparison between a DIY Wyoming Satellite and the official Home Assistant Voice Preview Edition (Voice PE) - a plug‑and‑play device:

Getting Started: Preparing Your Raspberry Pi

This guide walks you through setting up a Wyoming Satellite on a Raspberry Pi, using either a ReSpeaker 2-Mic HAT or a Waveshare WM8960 HAT for audio. Other HATs are also supported - just use the right setup guide for your hardware.

You'll install Raspberry Pi OS Lite (64-bit) and connect over SSH from your PC using PuTTY. No screen or keyboard is needed for the Pi - you'll do everything from your computer.

What You'll Need

• A Raspberry Pi (any model that supports 64-bit)
• A microSD card (8GB or larger) and a card reader
• A PC running Windows
• An internet-connected Wi-Fi or Ethernet network
• PuTTY (free SSH tool for Windows)
• A microphone HAT: ReSpeaker 2-Mic HAT, Waveshare WM8960, or other

Step 1: Download and Install Raspberry Pi Imager

1. Get Raspberry Pi Imager from the official website and install it.
2. Open Imager. Click "Choose OS" → Raspberry Pi OS (Other) → Raspberry Pi OS Lite (64-bit).
3. Click "Choose Storage" and pick your microSD card.
4. Once you click next, you'll see a popup that says "Would you like to apply OS customisation settings?"
   Click EDIT SETTINGS to open the customization options, where you can set:
   • Hostname: e.g. raspberrypi (or leave default)
   • Enable SSH: Choose "Use password authentication"
   • Username and password: E.g. pi / raspberry
   • Configure Wi-Fi: (if using Wi-Fi)
5. Click "Save", then "Yes" to use these settings and image your card. If you see another dialog telling you the data on the card will be erased, click Yes to proceed.
6. Insert the card into the Pi and power it up.

Step 2: Find the Raspberry Pi's IP Address

• Option 1: Check your router's device list for raspberrypi or similar.
• Option 2: Use Angry IP Scanner.
• Option 3: Try raspberrypi.local if using Ethernet and DHCP.

Step 3: Install and Use PuTTY to Connect

1. Download PuTTY from putty.org and install it.
2. In PuTTY's "Host Name", enter your Pi's IP (e.g. 192.168.1.42).
3. Set Port to 22 and Connection Type to SSH.
4. Click Open. Accept any security warning.
5. Log in with your username (e.g. pi) and password (e.g. raspberry).

If successful, you'll now see the Raspberry Pi terminal prompt - you're in!

Personalize this Guide for Your Setup

Step 4: Install Wyoming Satellite and OpenWakeWord

Before installing anything else, update your Raspberry Pi to make sure you have the latest security fixes and software:

sudo apt update && sudo apt upgrade

This ensures every package on your Pi is up to date, which helps prevent installation errors and unexpected problems later.

Why Use Separate Virtual Environments?

You may see some guides suggesting to install both Wyoming Satellite and OpenWakeWord into the same folder and venv. Don't do this! Both projects often require different versions of their dependencies, and installing them together can easily lead to frustrating errors and version conflicts (for example, you might see "No module named ..." or "Version X required, found Y" messages).

Best practice is to give each one its own directory and virtual environment. This keeps their software completely separate, so you won't run into mysterious breakage if one project updates. If you ever need to remove or upgrade one, you can do it safely - without affecting the other.

Step 4.1: Install System Packages

These commands install the extra tools and libraries your Pi needs for this project (just run them once at the start).

sudo apt install git
sudo apt-get install --no-install-recommends git python3-venv libopenblas-dev

• git: Lets you download project code from GitHub.
• python3-venv: Enables "virtual environments" (safe spaces for project-specific Python software).
• libopenblas-dev: Needed for fast wake word detection (used by OpenWakeWord).

Step 4.2: Install Wyoming Satellite (in its own folder)

Now we'll set up Wyoming Satellite. This creates a dedicated directory and virtual environment just for it.

git clone https://github.com/rhasspy/wyoming-satellite.git
cd wyoming-satellite
python3 -m venv .venv
source .venv/bin/activate

• git clone ...: Downloads the project code into a new folder (wyoming-satellite).
• cd wyoming-satellite: Moves you into that folder.
• python3 -m venv .venv: Creates a new virtual environment named .venv inside the folder.
• source .venv/bin/activate: Activates the virtual environment - you'll see your prompt change to (.venv).

Step 4.3: Install Wyoming Satellite Python Packages

With your venv active, install all the extra Python software Wyoming Satellite needs:

.venv/bin/pip3 install --upgrade pip wheel setuptools
.venv/bin/pip3 install -f 'https://synesthesiam.github.io/prebuilt-apps/' -e '.[all]'

• .venv/bin/pip3 install --upgrade pip wheel setuptools: Makes sure your packaging tools are up to date (helps avoid errors).
• .venv/bin/pip3 install -f 'https://synesthesiam.github.io/prebuilt-apps/' -e '.[all]': Installs all the dependencies that Wyoming Satellite needs - wake word support, audio tools, and more - in one go.
  No need for a requirements file, and these will only affect this venv (not your whole Pi).

Tip: This venv is only for Wyoming Satellite - don't install OpenWakeWord here!

Step 4.4: Install OpenWakeWord (in its own folder and venv)

OpenWakeWord is required for wake word detection (so your satellite can listen for "Hey Jarvis" or any custom word). This is a completely separate project, and it's important to keep it in its own directory and virtual environment.

1. Clone the OpenWakeWord repository and set up a new venv:

   cd ~
   git clone https://github.com/rhasspy/wyoming-openwakeword.git
   cd wyoming-openwakeword
   python3 -m venv .venv
   source .venv/bin/activate
   

2. Install OpenWakeWord:

   ./script/setup

   This will install all dependencies for OpenWakeWord (in this venv only).

Why not share the venv? Many online guides have you install everything together, but this leads to version conflicts and breakages - especially as both projects are updated frequently. By giving each project its own venv, you ensure a smoother, easier experience.

When done, you'll have:

• ~/wyoming-satellite/.venv/ for Wyoming Satellite (only)
• ~/wyoming-openwakeword/.venv/ for OpenWakeWord (only)

Now you're ready to continue with sound card and microphone setup below.

Step 5: Install Drivers for Your Microphone HAT

Choose your hardware below for step-by-step instructions:

arecord -L

arecord -D plughw:CARD=YOURDEVICE,DEV=0 -r 16000 -c 1 -f S16_LE -t wav -d 5 test.wav
aplay -D plughw:CARD=YOURDEVICE,DEV=0 test.wav

Step 6: Test Wyoming Satellite Manually

Once your mic and speaker work, you can run Wyoming Satellite manually. Be sure to substitute the correct device name for your hardware if you didn't change it via the above form!

script/run \
  --debug \
  --name 'my satellite' \
  --uri 'tcp://0.0.0.0:10700' \
  --mic-command 'arecord -D plughw:CARD=wm8960soundcard,DEV=0 -r 48000 -c 2 -f S16_LE -t raw' \
  --snd-command 'aplay -D plughw:CARD=wm8960soundcard,DEV=0 -r 48000 -c 2 -f S16_LE -t raw'

What to expect: If everything is set up correctly, you'll see output similar to this:

INFO:root:Ready
INFO:root:Connected to services
DEBUG:root:Connected to mic service
...

This means your Wyoming Satellite is running and has successfully connected to your mic and speaker.
You're now ready to integrate with Home Assistant!

If you see an error or the output does not reach "Ready":
Check that your device names and audio settings are correct, and review the troubleshooting tips in the previous steps.

Running Wyoming Satellite and OpenWakeWord Automatically (systemd)

Step 7.1: Create the OpenWakeWord Service

sudo systemctl edit --force --full wyoming-openwakeword.service

[Unit]
Description=Wyoming openWakeWord
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
ExecStart=/home/pi/wyoming-satellite/.venv/bin/python3 -m openwakeword --uri 'tcp://127.0.0.1:10400'
WorkingDirectory=/home/pi/wyoming-satellite
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target

Step 7.2: Create the Wyoming Satellite Service

sudo systemctl edit --force --full wyoming-satellite.service

[Unit]
Description=Wyoming Satellite
Wants=network-online.target wyoming-openwakeword.service
After=network-online.target wyoming-openwakeword.service
Requires=wyoming-openwakeword.service

[Service]
Type=simple
ExecStart=/home/pi/wyoming-satellite/script/run --name 'my satellite' --uri 'tcp://0.0.0.0:10700' --wake-uri 'tcp://127.0.0.1:10400' --wake-word-name 'hey_jarvis_v0.1' --mic-command 'arecord -D plughw:CARD=seeed2micvoicec,DEV=0 -r 16000 -c 1 -f S16_LE -t raw' --snd-command 'aplay -D plughw:CARD=seeed2micvoicec,DEV=0 -r 22050 -c 1 -f S16_LE -t raw'
WorkingDirectory=/home/pi/wyoming-satellite
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target

Step 7.3: Enable and Start Both Services

sudo systemctl daemon-reload
sudo systemctl enable --now wyoming-openwakeword.service
sudo systemctl enable --now wyoming-satellite.service

Connect to Home Assistant

As soon as both services show Ready in their logs, add the satellite in Home Assistant (via Settings → Devices & Services). Once Home Assistant is connected, you can start testing your wake word and see detections appear in your logs.
Home Assistant should auto-detect your Wyoming Satellite (look for a "Discovered" notification in Settings → Devices & Services). If not:

• Check the service is running:

  sudo systemctl status wyoming-satellite.service

  journalctl -u wyoming-satellite.service -f

• Verify it's listening on port 10700:

  ss -tuln | grep 10700

• Make sure Pi and Home Assistant are on the same network/subnet.
• Add it manually if needed:
  1. In Home Assistant, go to Settings → Devices & Services → Add Integration
  2. Search for "Wyoming"
  3. Enter your Pi's IP and port (default: 10700)
  4. Click "Submit" and assign a name/area
• Try restarting Home Assistant if you still don't see it.

Step 9: Check That Everything Works

sudo systemctl status wyoming-openwakeword.service
sudo systemctl status wyoming-satellite.service
journalctl -u wyoming-openwakeword.service -f
journalctl -u wyoming-satellite.service -f

What Should You See?

• When you run sudo systemctl status wyoming-openwakeword.service or sudo systemctl status wyoming-satellite.service, you should see active (running) highlighted in green. This means your service started successfully and is running in the background.
• When you use journalctl -u wyoming-satellite.service -f (or for openwakeword), you should see log messages appearing live.

If It's Not Working

• If the status says failed or inactive (dead), or you see lots of red error messages in the logs, something went wrong.
• Check the error message: The last few lines in the journalctl output will usually tell you what's wrong (e.g., "file not found", "invalid argument", "can't open audio device").
• Common problems:
  • Typo in the ExecStart command line or wrong file path (double-check every path and option).
  • Wrong username in service files (paths must match your actual Pi username and folder).
  • Mic or speaker device not detected (use arecord -L and aplay -l to see your device strings).
  • Virtual environment not activated in the service (make sure all Python paths point to your .venv).
  • Missing dependencies (try running sudo apt-get install -y python3-venv python3-pip again, or check the install steps).
• If you fix something in a service file, always run:
  sudo systemctl daemon-reload
  Then restart the service:
  sudo systemctl restart wyoming-satellite.service
• If you're stuck, copy the error message and search for it, or ask for help in the Home Assistant community forum.

Audio Enhancements

Fine-tune your microphone with:

--mic-auto-gain 5 --mic-noise-suppression 2

• --mic-auto-gain: 0 (off) to 31 (loudest), e.g. 5–10 is typical
• --mic-noise-suppression: 0 (off) to 4 (max), e.g. 2 is a good starting point
• --mic-volume-multiplier X: Multiply mic volume by X (e.g. 2 = double volume)

Add these to your ExecStart line in your wyoming-satellite.service or script/run command.

LED Control and Visual Feedback

ReSpeaker HATs (Built-in LEDs)

1. Set up the LED service:

   cd ~/wyoming-satellite/examples
   python3 -m venv --system-site-packages .venv
   .venv/bin/pip3 install --upgrade pip wheel setuptools
   .venv/bin/pip3 install 'wyoming==1.5.2'
   # For USB 4-Mic Array:
   .venv/bin/pip3 install 'pixel-ring'
   sudo apt-get install python3-spidev python3-gpiozero
   

2. Test and create systemd service:

   .venv/bin/python3 2mic_service.py --help
   sudo systemctl edit --force --full 2mic_leds.service
   

   [Unit]
   Description=2Mic LEDs
   [Service]
   Type=simple
   ExecStart=/home/pi/wyoming-satellite/examples/.venv/bin/python3 2mic_service.py --uri 'tcp://127.0.0.1:10500'
   WorkingDirectory=/home/pi/wyoming-satellite/examples
   Restart=always
   RestartSec=1
   [Install]
   WantedBy=default.target
   

3. Update Wyoming Satellite service:
   • In [Unit], add: Requires=2mic_leds.service
   • In [Service], add to your command: --event-uri 'tcp://127.0.0.1:10500'
4. Reload and restart:

   sudo systemctl daemon-reload
   sudo systemctl enable --now 2mic_leds.service
   sudo systemctl restart wyoming-satellite.service
   

5. Brightness and debugging: Use --led-brightness 8 (range 1–31). Use --debug for troubleshooting.

Custom GPIO LED

1. What you need: 1 LED, 220–470Ω resistor, 2 jumper wires
2. Wiring: LED anode to GPIO17 (pin 11), cathode via resistor to GND
3. Install Python GPIO library:

   sudo apt-get install python3-gpiozero

4. Python script (led_event_listener.py):

   from gpiozero import LED
   import sys
   import time
   led = LED(17)  # GPIO17
   for line in sys.stdin:
       if line.strip():
           led.on()
           time.sleep(1)
           led.off()
   

5. Update your Wyoming Satellite service:

   --detection-command "python3 /home/pi/led_event_listener.py"

   You can do the same for --transcript-command or --timer-finished-command for other effects.

Adding Sounds to Your Voice Assistant

You can play sound effects when the wake word is detected, after speech-to-text, or when a timer finishes. These should be WAV files stored on your Pi.

How to Transfer WAV Files

1. WinSCP (easy, Windows): Download WinSCP, connect to your Pi's IP, and drag-and-drop your WAV file to the /home/pi/wyoming-satellite/sounds/ folder. If the sounds folder doesn't exist, create it.
2. scp (Windows PowerShell, Mac, or Linux):

   scp C:\Users\YourName\Downloads\awake.wav pi@192.168.1.42:/home/pi/wyoming-satellite/sounds/awake.wav

Example usage:

--awake-wav /home/pi/wyoming-satellite/sounds/awake.wav

How to Use Sounds

• Wake word detected:

  --awake-wav /home/pi/voice/sounds/awake.wav

• Voice command done (STT):

  --done-wav /home/pi/voice/sounds/done.wav

• Timer finished:

  --timer-finished-wav /home/pi/voice/sounds/timer_done.wav

• Repeat timer finished sound:

  --timer-finished-wav-repeat 3 2

  (Repeats 3 times, with 2 seconds between)

Add these to your ExecStart line or script/run command. Only WAV files are supported by default.

Custom Event Commands (Advanced)

Wyoming Satellite lets you run your own commands or scripts when certain events happen (e.g., wake word, timer finished).

• Run a script on satellite startup:

  --startup-command "/home/pi/startup_script.sh"

• Custom sound or script on wake word detection:

  --detection-command "/home/pi/play-sound.sh"

• Script after STT is complete:

  --transcript-command "/home/pi/after_stt.sh"

See the Wyoming Satellite documentation for a full list (including events for timers, TTS, errors, and more).

Tip: For advanced automation, you can write a Python script to listen for events via --event-uri. See wyoming-satellite/example_event_client.py for a basic starter script!