imonlinux
49e75d0b2f
## Summary: Feature - Add Full MQTT Control for LEDs and Mute This pull request introduces a comprehensive MQTT integration to bypass limitations in the pinned aioesphomeapi library and provide full remote control over the voice satellite's features and appearance. It uses MQTT Discovery to automatically create and configure a device and its associated entities within Home Assistant. This allows for real-time control from the HA interface and enables powerful automations. Key Features: A switch entity to mute and unmute the microphone. A full suite of select and light entities to customize the effect, color, and brightness for each voice assistant state (Idle, Listening, Thinking, Responding, Error). A number entity to configure the number of LEDs in the strip, allowing for use with custom hardware. All settings are persistent, retained by the MQTT broker and re-applied whenever the application restarts. ## File Changes ### pyproject.toml (Modified) Adds paho-mqtt as a core dependency to enable MQTT communication. Pins aioesphomeapi==41.13.0 to ensure stability with the existing codebase and avoid unresolved library issues on some platforms. ### linux_voice_assistant/mqtt_controller.py (New File) Introduces the MqttController, a new class that manages all communication with the MQTT broker. On startup, it connects to the broker and publishes discovery configurations for all entities, automatically creating them in Home Assistant. Subscribes to command topics to receive instructions from the HA interface. Subscribes to state topics to read retained messages on startup, ensuring all user settings are persistent. Acts as a bridge, translating incoming MQTT messages into internal EventBus events for other components to act upon. ### linux_voice_assistant/led_controller.py (Modified) Refactored for Full Configurability: The controller has been re-architected to remove all hard-coded effects and colors. Central Configuration: It now uses a central configs dictionary to store the effect, color, and brightness settings for each voice assistant state (idle, listening, etc.). Dynamic State Management: Subscribes to new set_<state>_effect and set_<state>_color events from the event bus to update its configuration in real-time. Applies Custom Effects: The main voice event handlers (voice_stt_start, voice_stt_end, etc.) have been simplified to look up the user's chosen configuration and apply it. New Animations: Implements a full suite of animations (Slow/Medium/Fast Pulse, Slow/Medium/Fast Blink, Spin) to be used by the effect selectors. ### linux_voice_assistant/__main__.py (Modified) Adds command-line arguments (--mqtt-host, --mqtt-port, etc., and --num-leds) to configure the MQTT connection and initial LED setup. Instantiates and starts the MqttController on application startup if an MQTT host is provided. Includes the MicMuteHandler class, which listens for mute commands, updates the global mic_muted state, and clears the audio queue on unmute to prevent processing stale audio. Updates the process_audio loop to respect the mic_muted flag. ### linux_voice_assistant/satellite.py (Modified) Adds a handler for the VOICE_ASSISTANT_ERROR event, publishing a voice_error event to the EventBus so the LedController can provide visual feedback. Fixes a race condition where the "Responding" LED effect was being cancelled prematurely, ensuring it now plays for the full duration of the TTS audio. ### models.py, entity.py, api_server.py (Modified) Includes various compatibility fixes, reversions, and clean-up from the previous development cycle to create a stable base for the MQTT implementation. This ensures the application starts reliably with the pinned aioesphomeapi version.
Linux Voice Assistant
Experimental Linux voice assistant (LVA) for Home Assistant that uses the ESPHome protocol/API (via aioesphomeapi).
Runs on Linux aarch64 and x86_64 platforms. Tested with Python 3.13 and Python 3.11.
Supports announcments, start/continue conversation, and timers.
See the tutorial to build a satellite using a Raspberry Pi Zero 2 W and a ReSpeaker 2Mic HAT.
What's working:
- This fork is from https://github.com/OHF-Voice/linux-voice-assistant Release v1.0.0 which introduces the ablity to use both MicroWakeWord and OpenWakeWord detections models.
- Updated to support LED Events including GPIO based LED controls. Defaults to the ReSpeaker 2Mic Hat SPI leds, but you can use the Grove port GPIO12/13 by adding run config statements.
- Now supports ALSA, PulseAudio and PipeWire playback backends using the updated
linux_voice_assistant/mpv_player.py. - You can choose between ALSA, PulseAudio, or PipeWire by enabling the matching systemd User Mode service file.
- You can choose between all MWW and OWW wake word within HA after the VLA is registered. Choosen wake words are saved to preferences.json in the linux-voice-assistant folder.
- The volume control is now persistant between connections and reboots. The volume setting gets stored in prefernces.json and loaded when LVA starts.
Microphone mute button entity added. Changes the LED event to dim red while muted.(The mute switch does not survive a reboot or reconnect because unique_id not supported by aioesphomeapi version 41.13.0)
Add Full MQTT Control for LEDs and Mute
-
This branch introduces a comprehensive MQTT integration to bypass limitations in the pinned aioesphomeapi library and provide full remote control over the voice satellite's features and appearance.
-
It uses MQTT Discovery to automatically create and configure a device and its associated entities within Home Assistant. This allows for real-time control from the HA interface and enables powerful automations.
Key Features:
-
A switch entity to mute and unmute the microphone.
-
A full suite of select and light entities to customize the effect, color, and brightness for each voice assistant state (Idle, Listening, Thinking, Responding, Error).
-
A number entity to configure the number of LEDs in the strip, allowing for use with custom hardware.
-
All settings are persistent, retained by the MQTT broker and re-applied whenever the application restarts.
See the tutorial to enable MQTT Controls.
Installation
Install system dependencies (apt-get):
libportaudio2(forsounddevice)build-essential(forpymicro-features)libmpv-dev(forpython-mpv)mpv(for testing)libmpv-dev(for building spidev)
Clone and install project:
git clone https://github.com/OHF-Voice/linux-voice-assistant.git
cd linux-voice-assistant
script/setup
Running
Use script/run or python3 -m linux_voice_assistant
See --help for more options.
Connecting to Home Assistant
- In Home Assistant, go to "Settings" -> "Device & services"
- Click the "Add integration" button
- Choose "ESPHome" and then "Set up another instance of ESPHome"
- Enter the IP address of your voice satellite with port 6053
- Click "Submit"
ToDo:
- Implement echo-cancellation filter in PipeWire. (Improves wake word detection when audio is being played)
Merge jianyu-li's PR from source project to add mute switch function in this branchImplement MQTT entities to support advanced controls of the LVA.Configure LVA to advertise on Zeroconf/mDNS via Avahi for HA to auto detect (in progress)(Not needed as Release v1.0.0 implemented in code)- Implement a single LVA systemd unit file that can be addapted using profiles and drop-ins (in progress)
- Implement OWW model validation checks and error handling so that a bad model doesn't crash OWW
- Make the selection of the right ALSA ar PA device more scripted
Make a Docker of the projectAlready done in parent repo.Add sensor entity that displays which wake word engine is being used for HA(Not needed as you can use both at the same time)- Could this be an DEB package?
Implement Stop for OWW(Not needed, Stop with MWW works even when using OWW detection models)- Stretch goal: create a smart installer full of validation and sanity checks