From 5fcb8b2623c305712d441aae91a98d805449772b Mon Sep 17 00:00:00 2001
From: imonlinux <39863321+imonlinux@users.noreply.github.com>
Date: Sat, 11 Oct 2025 18:07:59 -0700
Subject: [PATCH] Updated for the Release v1.0.0 codebase
---
docs/linux-voice-assistant-2mic-install.md | 221 ++++++++-------------
1 file changed, 83 insertions(+), 138 deletions(-)
diff --git a/docs/linux-voice-assistant-2mic-install.md b/docs/linux-voice-assistant-2mic-install.md
index da3ee4a..d243b16 100644
--- a/docs/linux-voice-assistant-2mic-install.md
+++ b/docs/linux-voice-assistant-2mic-install.md
@@ -9,7 +9,7 @@
```
> Modeled after the Wyoming Satellite two‑mic tutorial, adapted from actual shell history.
-This guide reproduces a working setup of the **linux-voice-assistant** project with **Wyoming OpenWakeWord** or **MicroWakeWord** on a Raspberry PI Zero 2W and a Respeaker 2‑mic HAT (e.g., seeed-2mic-voicecard). It assumes a fresh system with sudo access and the default "pi" user. Included is the option to use PipeWire or PulseAudio instead of ALSA.
+This guide reproduces a working setup of the **linux-voice-assistant** project with **Wyoming OpenWakeWord** and **MicroWakeWord** on a Raspberry PI Zero 2W and a Respeaker 2‑mic HAT (e.g., seeed-2mic-voicecard). It assumes a fresh system with sudo access and the default "pi" user. Included is the option to use PipeWire or PulseAudio instead of ALSA.
## Prerequisites
- Raspberry Pi OS Lite (64-bit)
@@ -26,7 +26,7 @@ This guide reproduces a working setup of the **linux-voice-assistant** project w
sudo apt update
sudo apt upgrade
sudo apt install libportaudio2 build-essential git \
- libmpv-dev mpv python3.11-dev avahi-daemon avahi-utils
+ libmpv-dev mpv python3.11-dev
sudo reboot
```
@@ -47,21 +47,7 @@ sudo reboot
```
-## 4. Wyoming OpenWakeWord (OWW), skip to step 5. if using MicroWakeWord (MWW)
-
-
-```bash
-git clone https://github.com/rhasspy/wyoming-openwakeword.git
-```
-
-```bash
-cp ~/linux-voice-assistant/wyoming-openwakeword/requirements.txt ~/wyoming-openwakeword/requirements.txt
-cd wyoming-openwakeword/
-script/setup
-```
-
-
-## 5. Linux Voice Assistant (LVA)
+## 4. Linux Voice Assistant (LVA)
```bash
cd ~/linux-voice-assistant/
@@ -69,14 +55,14 @@ script/setup
```
-## 6. Choose your install option "Choose your Adventure!"
+## 5. Choose your install option "Choose your Adventure!"
Pick **one** of the following install paths. Expand a section to see the exact steps.
-> Tip: PipeWire options run services in *user* mode (requires `loginctl enable-linger`); PulseAudio/ALSA options run services in *system* mode.
+> Tip: All services run in *user* mode (requires `loginctl enable-linger`);
-PipeWire + OpenWakeWord (user-mode services)
+PipeWire (user-mode services)
**Prep (PipeWire):** Follow the PipeWire tutorial first: [the tutorial](install_pipewire.md).
@@ -85,44 +71,13 @@ Pick **one** of the following install paths. Expand a section to see the exact s
sudo loginctl enable-linger pi
```
-**Install user-mode services:**
+**Install LVA user-mode services:**
```bash
mkdir -p ~/.config/systemd/user
-
-# LVA
-cp ~/linux-voice-assistant/service/user-pw-oww-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
-
-# OWW
-cp ~/linux-voice-assistant/service/user-wyoming-openwakeword.service.service ~/.config/systemd/user/wyoming-openwakeword.service
```
-**Enable & start:**
```bash
-systemctl --user daemon-reload
-systemctl --user enable --now wyoming-openwakeword.service
-systemctl --user enable --now linux-voice-assistant.service
-```
-
-**Verify:**
-```bash
-systemctl --user status linux-voice-assistant wyoming-openwakeword --no-pager -l
-```
-
-
-
-PipeWire + MicroWakeWord (user-mode services)
-
-**Prep (PipeWire):** Follow the PipeWire tutorial first: [the tutorial](install_pipewire.md).
-
-**Enable linger:**
-```bash
-sudo loginctl enable-linger pi
-```
-
-**Install user-mode service:**
-```bash
-mkdir -p ~/.config/systemd/user
-cp ~/linux-voice-assistant/service/user-pw-mww-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
+cp ~/linux-voice-assistant/service/user-pw-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
```
**Enable & start:**
@@ -138,54 +93,38 @@ systemctl --user status linux-voice-assistant --no-pager -l
-PulseAudio + OpenWakeWord (system services)
+PulseAudio (user-mode services)
**Prep (PulseAudio):** Follow the PulseAudio tutorial first: [the tutorial](install_pulseaudio.md).
-**Install LVA (system) + tuning drop-in:**
+**Enable linger (required for user services to start after reboot):**
```bash
-sudo cp ~/linux-voice-assistant/service/pa-oww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
-
-sudo mkdir -p /etc/systemd/system/linux-voice-assistant.service.d
-sudo cp ~/linux-voice-assistant/service/10-tuning.conf /etc/systemd/system/linux-voice-assistant.service.d/10-tuning.conf
+sudo loginctl enable-linger pi
```
-**Install OWW (system):**
+**Install LVA user-mode services:**
```bash
-sudo cp ~/linux-voice-assistant/service/wyoming-openwakeword.service /etc/systemd/system/wyoming-openwakeword.service
+mkdir -p ~/.config/systemd/user
+```
+
+```bash
+cp ~/linux-voice-assistant/service/user-pa-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
```
**Enable & start:**
```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now wyoming-openwakeword linux-voice-assistant
-sudo systemctl status linux-voice-assistant wyoming-openwakeword --no-pager -l
+systemctl --user daemon-reload
+systemctl --user enable --now linux-voice-assistant.service
+```
+
+**Verify:**
+```bash
+systemctl --user status linux-voice-assistant --no-pager -l
```
-PulseAudio + MicroWakeWord (system services)
-
-**Prep (PulseAudio):** Follow the PulseAudio tutorial first: [the tutorial](install_pulseaudio.md).
-
-**Install LVA (system) + tuning drop-in:**
-```bash
-sudo cp ~/linux-voice-assistant/service/pa-mww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
-
-sudo mkdir -p /etc/systemd/system/linux-voice-assistant.service.d
-sudo cp ~/linux-voice-assistant/service/10-tuning.conf /etc/systemd/system/linux-voice-assistant.service.d/10-tuning.conf
-```
-
-**Enable & start:**
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now linux-voice-assistant
-sudo systemctl status linux-voice-assistant --no-pager -l
-```
-
-
-
-ALSA + OpenWakeWord (system services)
+ALSA (user-mode services)
**No extra audio stack needed.** If you’re using a different sound card/driver, confirm device names:
```bash
@@ -193,59 +132,34 @@ arecord -l
aplay -l
```
-**Install LVA (system):**
+**Enable linger (required for user services to start after reboot):**
```bash
-sudo cp ~/linux-voice-assistant/service/alsa-oww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
+sudo loginctl enable-linger pi
```
-**Install OWW (system):**
+**Install LVA user-mode services:**
+
```bash
-sudo cp ~/linux-voice-assistant/service/wyoming-openwakeword.service /etc/systemd/system/wyoming-openwakeword.service
+mkdir -p ~/.config/systemd/user
+```
+
+```bash
+sudo cp ~/linux-voice-assistant/service/user-linux-voice-assistant.service ~/.config/systemd/user/linux-voice-assistant.service
```
**Enable & start:**
```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now wyoming-openwakeword linux-voice-assistant
-sudo systemctl status linux-voice-assistant wyoming-openwakeword --no-pager -l
+systemctl --user daemon-reload
+systemctl --user enable --now linux-voice-assistant.service
+```
+
+**Verify:**
+```bash
+systemctl --user status linux-voice-assistant --no-pager -l
```
-
-ALSA + MicroWakeWord (system services)
-
-**No extra audio stack needed.** If you’re using a different sound card/driver, confirm device names:
-```bash
-arecord -l
-aplay -l
-```
-
-**Install LVA (system):**
-```bash
-sudo cp ~/linux-voice-assistant/service/alsa-mww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
-```
-
-**Enable & start:**
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now linux-voice-assistant
-sudo systemctl status linux-voice-assistant --no-pager -l
-```
-
-
-
-Optional: Advertise LVA to Home Assistant via Avahi
-
-**Generate & install ESPHome-style mDNS service:**
-```bash
-chmod +x ~/linux-voice-assistant/script/gen-esphome-avahi.sh
-sudo ~/linux-voice-assistant/script/gen-esphome-avahi.sh
-sudo systemctl restart avahi-daemon.service
-```
-
-
-
-## 7. Connect to Home Assistant
+## 6. Connect to Home Assistant
### If HA does not discover the new LVA:
@@ -254,12 +168,12 @@ sudo systemctl restart avahi-daemon.service
3. Choose "ESPHome" and then "Set up another instance of ESPHome"
4. Enter the IP address of your voice satellite with port 6053
5. Click "Submit"
-6. During the registration process, use the wake word that you configured in your linux-voice-assistant.service file. Default is "alexa".
+6. During the registration process, use the wake word that is displayed on the registration page. Default is "OK Nabu".
-## 8. Verification
-- Use "journalctl -u linux-voice-assistant.service -f" to check for errors for ALSA and PluseAudio. Debugging is enabled.
-- Use "journalctl --user -u linux-voice-assistant.service -f" to check for errors when using PipeWire. Debugging is enabled.
+## 7. Verification
+
+- Use "journalctl --user -u linux-voice-assistant.service -f" to check for errors. Debugging is enabled.
- Expect logs like `Connected to Home Assistant`
- Look for `[OWW] Detection: name=...` followed by re-arming/cycling
- Ask: *“What time is it?”* and confirm TTS reply
@@ -268,7 +182,7 @@ sudo systemctl restart avahi-daemon.service
### Settings -> Voice assistants -> Assist (the assistant you configured) -> Text-to-speech -> Voice
-## 9. Change OWW detection model
+## 8. Change OWW detection model
After the LVA is registered with HA, you can change the Wake Word model used in the ESPHome Voice Assistant entity.
@@ -285,18 +199,49 @@ ok_nabu_v0.1.tflite -> OK Nabo **(I had to say OK Nobu)**
Additional community provided OWW models available from this repository:
https://github.com/fwartner/home-assistant-wakewords-collection
-You just copy the ones you want into the ~/wyoming-openwakeword/wyoming-openwakeword/models directory. If a model is currupted, the wyoming-openwakeword.service will fail to start.
+You just copy the ones you want into the ~/linux-voice-assistant/wakewords/openWakeWord directory. If a model is currupted, the LVA will fail to start.
+Each model added will need a corresponding json file. (note the json file names matches the tflite name)
+
+***Example***
+
+Add Model:
+```
+/linux-voice-assistant/wakewords/openWakeWord/hal_v2.tflite
+```
+Create Json:
+```
+/linux-voice-assistant/wakewords/openWakeWord/hal_v2.json
+```
+
+Contents:
+```
+{
+ "type": "openWakeWord",
+ "wake_word": "HAL",
+ "model": "hal_v2.tflite"
+}
+```
**Word of warning. I have had problems with some of the community provided wake words. YMMV**
-## 10. Switching between OWW and MWW. Or ALSA, PW, PA see section 6.
+## 9. Switching between ALSA, PW, or PA see section 5.
-If you intend to switch from PA to ALSA, you must first stop the pusleaudio.service.
+If you intend to switch from PA or PW to ALSA, you must first stop and disable the corresponding user-mode services.
+
+###PulseAudio
```bash
-sudo systemctl stop pulseaudio.service
+sudo systemctl --user stop pulseaudio.service
```
```bash
-sudo systemctl disable pulseaudio.service
+sudo systemctl --user disable pulseaudio.service
+```
+###PipeWire
+
+```bash
+sudo systemctl --user stop pipewire.service
+```
+```bash
+sudo systemctl --user disable pipewire.service
```