Improved the MQTT Controls Information

2025-10-12 17:06:44 -07:00
parent f707f3232a
commit 5c14c6c782
1 changed files with 77 additions and 0 deletions
@@ -162,6 +162,83 @@ systemctl --user status linux-voice-assistant --no-pager -l
 <details>
 <summary><strong>Optional (MQTT Controls)</strong></summary>

+
+## 🔌 MQTT Controls Overview
+
+The Linux Voice Assistant (LVA) creates several MQTT entities under the Home Assistant MQTT Discovery protocol. Each entity is prefixed by your LVA's unique device ID defined with the --name field in the LVA User-Mode Serviced Unit (e.g., `linux_voice_assistant`).
+
+---
+
+### 🎤 Microphone Mute (`switch` entity)
+
+Controls the microphone mute state.
+
+* **MQTT Discovery Topic:** `homeassistant/switch/<device_id>_mute/config`
+* **Name:** `[LVA Name] Mute Microphone`
+* **Icon:** `mdi:microphone-off`
+* **Functionality:** Toggles the microphone mute. When muted, the LEDs will display a dim red `solid` effect.
+
+---
+
+## 💡 LED Control for Linux Voice Assistant
+These are MQTT entities created by the Linux Voice Assistant for controlling its integrated LEDs (e.g., DotStar, NeoPixel). These entities integrate seamlessly with Home Assistant via MQTT Discovery, allowing you to manage LED effects, colors, brightness, and the number of connected LEDs directly from your Home Assistant interface.
+
+---
+
+### 🔢 Number of LEDs (`number` entity)
+
+This entity allows you to specify the physical number of addressable LEDs connected to your device.
+
+
+* **MQTT Discovery Topic:** `homeassistant/number/<device_id>_num_leds/config`
+* **Name:** `[LVA Name] Number of LEDs`
+* **Functionality:** Sets the total number of LEDs.
+* **Important:** This setting requires a **restart of the LVA service file** to take effect, as the LED hardware driver needs to be re-initialized. The value is persisted in `preferences.json`.
+
+---
+
+### ✨ State-Based LED Controls (`select` and `light` entities)
+
+For each distinct LVA state (Idle, Listening, Thinking, Responding, Error), a `select` entity for choosing an effect and a `light` entity for controlling color and brightness are created.
+
+* **States:**
+    * `idle` (e.g., `[LVA Name] Idle Effect`, `[LVA Name] Idle Color`)
+    * `listening` (e.g., `[LVA Name] Listening Effect`, `[LVA Name] Listening Color`)
+    * `thinking` (e.g., `[LVA Name] Thinking Effect`, `[LVA Name] Thinking Color`)
+    * `responding` (e.g., `[LVA Name] Responding Effect`, `[LVA Name] Responding Color`)
+    * `error` (e.g., `[LVA Name] Error Effect`, `[LVA Name] Error Color`)
+
+#### `select` Entities (Effect Selector)
+
+* **MQTT Discovery Topic:** `homeassistant/select/<device_id>_<state_name>_effect/config`
+* **Name:** `[LVA Name] [State Name] Effect`
+* **Icon:** `mdi:palette-swatch-variant`
+* **Functionality:** Allows selection of an animation/effect for the specific LVA state.
+
+#### `light` Entities (Color & Brightness Control)
+
+* **MQTT Discovery Topic:** `homeassistant/light/<device_id>_<state_name>_color/config`
+* **Name:** `[LVA Name] [State Name] Color`
+* **Functionality:** Controls the color and brightness for the specific LVA state when the selected effect uses color. Supports RGB color mode and brightness.
+
+---
+
+## 🎨 Available LED Effects
+
+The following effects can be selected via the `[State Name] Effect` (select) entities:
+
+| Effect Name | Description |
+| :--- | :--- |
+| **Off** | All LEDs are turned off. |
+| **Solid** | All LEDs display a single, constant color. |
+| **Slow Pulse** | LEDs slowly fade in and out. |
+| **Medium Pulse** | LEDs fade in and out at a moderate speed. |
+| **Fast Pulse** | LEDs rapidly fade in and out. |
+| **Slow Blink** | LEDs turn on and off slowly. |
+| **Medium Blink** | LEDs turn on and off at a moderate speed. |
+| **Fast Blink** | LEDs rapidly turn on and off. |
+| **Spin** | A single LED "spins" around the strip. |
+
 **Edit LVA user-mode service:**

 ```bash