From 76746e4262d192d8d007708cf8f52c78a5c9832b Mon Sep 17 00:00:00 2001
From: imonlinux <39863321+imonlinux@users.noreply.github.com>
Date: Sat, 27 Sep 2025 08:52:58 -0700
Subject: [PATCH] Update linux-voice-assistant-2mic-install.md
Cleanup and collapsible sections to reduce confusion.
---
docs/linux-voice-assistant-2mic-install.md | 219 +++++++++++----------
1 file changed, 116 insertions(+), 103 deletions(-)
diff --git a/docs/linux-voice-assistant-2mic-install.md b/docs/linux-voice-assistant-2mic-install.md
index 2ea583e..0a669aa 100644
--- a/docs/linux-voice-assistant-2mic-install.md
+++ b/docs/linux-voice-assistant-2mic-install.md
@@ -1,4 +1,4 @@
-# Linux Voice Assistant on 2‑Mic Linux — Installation & Configuration Guide
+# Linux Voice Assistant on RaspberryPi with ReSpeaker 2‑Mic — Installation & Configuration Guide
> Created using ChatGPT 5 with the following prompt:
```html
@@ -35,7 +35,6 @@ sudo reboot
```bash
git clone https://github.com/imonlinux/linux-voice-assistant.git
-git clone https://github.com/rhasspy/wyoming-openwakeword.git
```
@@ -50,6 +49,11 @@ 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/
@@ -65,171 +69,180 @@ script/setup
```
-## 6. Configure audio devices, choose PipeWire, PulseAudio, or ALSA (default)
+## 6–7. Choose your install option "Choose your Adventure!"
-### (Optional) PipeWire
+Pick **one** of the following install paths. Expand a section to see the exact steps.
-See [the tutorial](install_pipewire.md) to install and configure PipeWire.
+> Tip: PipeWire options run services in *user* mode (requires `loginctl enable-linger`); PulseAudio/ALSA options run services in *system* mode.
-### (Optional) PulseAudio
+
+PipeWire + OpenWakeWord (user-mode services)
-See [the tutorial](install_pulseaudio.md) to install and configure PulseAudio.
-
-### For Standard ALSA
-
-You shouldn't have to change anything if you are using the driver provided in this repo. If you are using something else, find your sound device names and update the linux-voice-assistant/service/alsa-oww-linux-voice-assistant.service used with OpenWakeWord or linux-voice-assistant/service/alsa-mww-linux-voice-assistant.service file used with MicroWakeWord to match sound card details:
-
-```bash
-arecord -l
-aplay -l
-```
-
-
-## 7. Systemd services
-
-### (Optional) enable Avahi service file to advertise LVA to HA:
-
-```bash
-chmod +x ~/linux-voice-assistant/script/gen-esphome-avahi.sh
-sudo ~/linux-voice-assistant/script/gen-esphome-avahi.sh
-```
-
-```bash
-sudo systemctl restart avahi-daemon.service
-```
-
-### (Optional) for PipeWire with OWW copy these service files to /home/pi/.config/systemd/user
-### Note: This installs OWW and LVA as User Mode Systemd services. This requires linger to be enabled on the user (pi).
-### Note: Without linger the User Mode Systemd service(s) will not start automatically after a reboot.
-
-Enable linger for the user:
+**Prep (PipeWire):** Follow the PipeWire tutorial first: [the tutorial](install_pipewire.md).
+**Enable linger (required for user services to start after reboot):**
```bash
sudo loginctl enable-linger pi
```
-Install User Mode Service files:
-
+**Install user-mode services:**
```bash
mkdir -p ~/.config/systemd/user
-cp ~/linux-voice-assistant/service/user-pw-oww-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
+# LVA
+cp ~/linux-voice-assistant/service/user-pw-oww-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
-cp ~/linux-voice-assistant/service/user-wyoming-openwakeword.service.service ~/.config/systemd/user/wyoming-openwakeword.service.service
+# OWW
+cp ~/linux-voice-assistant/service/user-wyoming-openwakeword.service.service ~/.config/systemd/user/wyoming-openwakeword.service
```
-Enable and start the user mode services:
-
+**Enable & start:**
```bash
systemctl --user daemon-reload
systemctl --user enable --now wyoming-openwakeword.service
systemctl --user enable --now linux-voice-assistant.service
```
-Check that the user mode services are running:
-
+**Verify:**
```bash
-sytemctl --user status linux-voice-assistat.service
+systemctl --user status linux-voice-assistant wyoming-openwakeword --no-pager -l
```
+
-#### Proceed to step 8 (Connecting to HA)
+
+PipeWire + MicroWakeWord (user-mode services)
+**Prep (PipeWire):** Follow the PipeWire tutorial first: [the tutorial](install_pipewire.md).
-### (Optional) for PipeWire with MWW copy this service file to /home/pi/.config/systemd/user
-### Note: This installs LVA as User Mode Systemd service. This requires linger to be enabled on the user (pi).
-### Note: Without linger the User Mode Systemd service(s) will not start automatically after a reboot.
-
-Enable linger for the user:
-
+**Enable linger:**
```bash
sudo loginctl enable-linger pi
```
-Install User Mode Service file:
-
+**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-mww-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
```
-Enable and start the user mode service:
-
+**Enable & start:**
```bash
systemctl --user daemon-reload
systemctl --user enable --now linux-voice-assistant.service
```
-Check that the user mode service is running:
-
+**Verify:**
```bash
-sytemctl --user status linux-voice-assistat.service
+systemctl --user status linux-voice-assistant --no-pager -l
```
+
-#### Proceed to step 8 (Connecting to HA)
+
+PulseAudio + OpenWakeWord (system services)
+**Prep (PulseAudio):** Follow the PulseAudio tutorial first: [the tutorial](install_pulseaudio.md).
-### (Optional) for PulseAudio with OWW copy this service file into /etc/systemd/system/:
-
+**Install LVA (system) + tuning drop-in:**
```bash
-sudo cp ~/linux-voice-assistant/service/pa-oww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
-```
-Create the systemd drop-in directory for linux-voice-assistant.service:
+sudo cp ~/linux-voice-assistant/service/pa-oww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
-```bash
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
```
+**Install OWW (system):**
```bash
-sudo cp ~/linux-voice-assistant/service/10-tuning.conf \
- /etc/systemd/system/linux-voice-assistant.service.d/10-tuning.conf
+sudo cp ~/linux-voice-assistant/service/wyoming-openwakeword.service /etc/systemd/system/wyoming-openwakeword.service
```
-### OR for Pulse Audio with MWW copy this service file into /etc/systemd/system/:
-
+**Enable & start:**
```bash
-sudo cp ~/linux-voice-assistant/service/pa-mww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now wyoming-openwakeword linux-voice-assistant
+sudo systemctl status linux-voice-assistant wyoming-openwakeword --no-pager -l
```
-Create the systemd drop-in directory for linux-voice-assistant.service:
+
+
+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
```
-```bash
-sudo cp ~/linux-voice-assistant/service/10-tuning.conf \
- /etc/systemd/system/linux-voice-assistant.service.d/10-tuning.conf
-```
-
-
-### For ALSA with OWW copy this service file into /etc/systemd/system/:
-
-```bash
-sudo cp ~/linux-voice-assistant/service/alsa-oww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
-```
-
-
-### OR for ALSA with MWW copy this service file into /etc/systemd/system/:
-
-```bash
-sudo cp ~/linux-voice-assistant/service/alsa-mww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
-```
-
-### For either ALSA or PulseAudio systems with the OWW copy this service file into /etc/systemd/system/:
-### Not needed if using PipeWire
-
-```bash
-sudo cp ~/linux-voice-assistant/service/wyoming-openwakeword.service /etc/systemd/system/wyoming-openwakeword.service
-```
-
-### For either ALSA or PulseAudio start new services and confirm services are running:
-### Not needed if using PipeWire
-
+**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)
+
+**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-oww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
+```
+
+**Install OWW (system):**
+```bash
+sudo cp ~/linux-voice-assistant/service/wyoming-openwakeword.service /etc/systemd/system/wyoming-openwakeword.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
```
+
+
+
+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
+```
+
## 8. Connect to Home Assistant