From 31b6d70910373572b3c1c29e14dc7dfa61d061aa Mon Sep 17 00:00:00 2001 From: imonlinux <39863321+imonlinux@users.noreply.github.com> Date: Thu, 11 Dec 2025 09:54:13 -0800 Subject: [PATCH] Update xvf3800_usb_led_testing.md Added the requirement for a udev rule. --- docs/xvf3800_usb_led_testing.md | 126 +++++++++++++++++++------------- 1 file changed, 75 insertions(+), 51 deletions(-) diff --git a/docs/xvf3800_usb_led_testing.md b/docs/xvf3800_usb_led_testing.md index d68ccda..86ba69a 100644 --- a/docs/xvf3800_usb_led_testing.md +++ b/docs/xvf3800_usb_led_testing.md @@ -1,6 +1,6 @@ -# Call for Testing: XVF3800 USB LED Support in `linux-voice-assistant` +# XVF3800 USB LED and Mute Button Support in `linux-voice-assistant` -The XVF3800 branch now includes **USB-based LED ring support** using the XVF3800’s legacy LED control commands (`LED_EFFECT`, `LED_BRIGHTNESS`, `LED_SPEED`, `LED_COLOR`). This post outlines how to pull the branch, refresh your virtualenv, and enable XVF3800 support in `config.json`. +The XVF3800 branch now includes **USB-based LED ring support** using the XVF3800’s legacy LED control commands (`LED_EFFECT`, `LED_BRIGHTNESS`, `LED_SPEED`, `LED_COLOR`). This post outlines how to pull the branch, refresh your virtualenv, and enable XVF3800 support in `config.json`. I fully expect bugs and you should too. Let me know if it works first try and I will by some lottery tickets as well. --- @@ -11,7 +11,7 @@ If you **already have** the repo: ```bash cd ~/linux-voice-assistant git fetch origin -git switch xvf3800 # or: git checkout xvf3800 +git switch XVF3800 # or: git checkout xvf3800 git pull ``` @@ -19,14 +19,12 @@ If you’re **cloning fresh**: ```bash cd ~ -git clone https://github.com/imonlinux/linux-voice-assistant.git -cd linux-voice-assistant -git switch xvf3800 # or: git checkout xvf3800 +git clone --branch XVF3800 --single-branch https://github.com/imonlinux/linux-voice-assistant.git ``` --- -## 2. Refresh the Virtualenv (New Dependencies) +## 2. Install/Refresh the Virtualenv (New Dependencies) The XVF3800 backend uses **pyusb** and system libusb. @@ -35,19 +33,15 @@ From the project root: ```bash cd ~/linux-voice-assistant +# remove the linux_voice_assistant.egg-info folder if it exists +rm -rf linux_voice_assistant.egg-info + # Create venv if you don't already have one -python3 -m venv .venv - -# Activate it -source .venv/bin/activate - -# Upgrade pip and reinstall project deps (including pyusb) -pip install --upgrade pip -pip install -e . +script/setup ``` - On Debian/RPi OS, make sure libusb is installed: + ```bash sudo apt update sudo apt install libusb-1.0-0 @@ -55,11 +49,56 @@ sudo apt install libusb-1.0-0 No extra `hidapi` is required for the LED integration (this path is pure pyusb). ---- +## 3. Copy the udev rule for the XVF3800 -## 3. Enable XVF3800 Support in `config.json` +On the Pi: -Edit `linux_voice_assistant/config.json` and set the `led` block to use the XVF3800 USB backend. +```bash +sudo cp ~linux-voice-assistant/XVF3800/99-respeaker-xvf3800.rules /etc/udev/rules.d/99-respeaker-xvf3800.rules +``` + +This does: + +- Matches the XVF3800 by VID/PID (2886:001a) + +- Sets permissions to 0660 + +- Assigns it to the plugdev group + +- Tags it for desktop access (uaccess) + +### Add user (pi) to the plugdev group +**use the user name that you have created if not pi** + +```bash +sudo usermod -aG plugdev pi +``` + +Then log out and back in (or reboot) so the new group membership takes effect. + +### Reload udev rules and replug the device + +If you didn't reboot, reload the udev rules: + +```bash +sudo udevadm control --reload-rules +sudo udevadm trigger +``` + +Then unplug/replug the XVF3800 USB cable. + +You can sanity-check permissions with: + +```bash +ls -l /dev/bus/usb/*/* +``` + +Look for the device entry that corresponds to 2886:001a (you can pair it with lsusb), and confirm it’s root plugdev with crw-rw----. + + +## 4. Enable XVF3800 Support in `config.json` + +Edit `linux_voice_assistant/config.json` and set the `led` block to use the XVF3800 USB backend. If you want to test the mute button, add the following button section as well. See the `linux_voice_assistant/config.json.example` file for additional options. Minimal example: @@ -68,33 +107,15 @@ Minimal example: "app": { "name": "Linux Voice Assistant XVF3800" }, - - "audio": { - // Set this to your XVF3800 input device name or index if needed - // "input_device": "reSpeaker XVF3800 4-Mic Array", - "input_block_size": 1024 - }, - "led": { - // New: XVF3800 USB LED backend - // led_type can be "dotstar", "neopixel" or "xvf3800" + "enabled": true, "led_type": "xvf3800", - - // For XVF3800 we currently support only "usb" - "interface": "usb", - - // Used for internal logic / MQTT, not hardware-driven on XVF3800 - "num_leds": 12, - - // Optional (defaults to true if omitted) - "enabled": true + "interface": "usb" }, - - // If you previously used the 2-Mic HAT button, disable it here "button": { - "enabled": false + "enabled": true, + "mode": "xvf3800" }, - "mqtt": { "host": "192.168.1.2", "port": 1883, @@ -104,17 +125,21 @@ Minimal example: } ``` -> ✅ For non-XVF3800 setups, keep using `led_type: "dotstar"` / `"neopixel"` and your existing `interface` (`spi` or `gpio`). - --- -## 4. Run the Assistant with XVF3800 LEDs +## 5. Run the Assistant with XVF3800 LEDs + +Stop any running systemd units: + +```bash +systemctl --user stop linux-voice-assistant.service +``` + From the project root: ```bash cd ~/linux-voice-assistant -source .venv/bin/activate script/run --debug ``` @@ -124,11 +149,10 @@ With the XVF3800 branch + config above, the **USB LED ring** should now: - Turn **solid dim red** when the mic is muted - Track changes coming from the MQTT LED state entities -Please report back: +The mute button should now: -- Which distro / Pi model you’re using -- Firmware version on the XVF3800 (if known) -- What you see on the LED ring for each LVA state - (idle, listening, thinking, responding, error, muted) +- Keep hardware mute & software/LVA mute fully in sync. +- No short/long press differentiation: + One physical control, one responsibility: mute/unmute. -This will help tighten the mappings and prepare for a follow-up pass that uses the newer `LED_RING_COLOR` capabilities. +`Wake/stop is still done via wake word or a separate GPIO button (you can still wire a standalone Pi button and run mode="gpio" in parallel if desired).`