Leds and buttons events (#266)
Use events and commands to control custom onboard leds and buttons. Can be used to communicate with an external Python script via a WebSocket API running in a container alongside LVA.
This commit is contained in:
Omar Amin authored and GitHub committed
1 parent
e1770d071c
commit
2d460b6728
51 files changed
+9251
-117
No files matched your search
@@ -0,0 +1,223 @@
|
||||
# Peripheral Web Console
|
||||
|
||||
The Peripheral Web Console is a web-based interface for testing and interacting with the Linux Voice Assistant WebSocket API. It allows you to monitor LVA state and send commands to control the voice assistant from a browser.
|
||||
|
||||
## Overview
|
||||
|
||||
This HTML console provides:
|
||||
- Real-time connection status to the LVA WebSocket server
|
||||
- Live event feed showing all LVA events (wake word detected, listening, TTS, timers, etc.)
|
||||
- Control buttons to send commands to LVA (mute/unmute, volume control, start listening, etc.)
|
||||
- Visual indicators for volume, mute state, and Home Assistant connection status
|
||||
- Audio level visualization
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Step 1: Download the HTML File
|
||||
|
||||
Download [peripheral_web_console.html](peripheral_web_console.html)
|
||||
|
||||
|
||||
### Step 2: Open the HTML File in Your Browser
|
||||
|
||||
Open the file using any modern web browser (Chrome, Firefox, Safari, Edge):
|
||||
|
||||
<img src="image.png" width="300">
|
||||
|
||||
**Option A: Direct File Open**
|
||||
- Double-click the `peripheral_web_console.html` file
|
||||
- Or drag it into your browser window
|
||||
- The file will open as a local file URL (e.g., `file:///path/to/peripheral_web_console.html`)
|
||||
|
||||
**Option B: Using a Local Web Server**
|
||||
```bash
|
||||
# Using Python 3
|
||||
python -m http.server 8000
|
||||
|
||||
# Using Python 2
|
||||
python -m SimpleHTTPServer 8000
|
||||
|
||||
# Then navigate to: http://localhost:8000/peripheral_web_console.html
|
||||
```
|
||||
|
||||
### Step 3: Configure the WebSocket Connection URL
|
||||
|
||||
When the page loads, you'll see the **CONNECTION & STATUS** section at the top with:
|
||||
- Current WebSocket URL (default: `ws://localhost:6055`)
|
||||
- A "connect" button
|
||||
|
||||
**To modify the connection URL:**
|
||||
1. Look at the input field showing the WebSocket address
|
||||
2. By default, it points to `ws://localhost:6055`
|
||||
3. Change this if your LVA server is running on a different host or port:
|
||||
- Local development: `ws://localhost:6055`
|
||||
- Remote server: `ws://your-server-ip:6055`
|
||||
- Docker container: `ws://lva-container:6055` (if using Docker networking)
|
||||
|
||||
### Step 4: Connect to LVA
|
||||
|
||||
<img src="image_2.png" width="300">
|
||||
|
||||
1. Once you've configured the URL, click the **"connect"** button
|
||||
2. The page will attempt to establish a WebSocket connection to the LVA server
|
||||
3. On successful connection:
|
||||
- The status indicator changes from "disconnected" (gray dot) to "connected" (green dot)
|
||||
- You'll receive a "snapshot" event showing the current state (volume, mute status, last recognized text, etc.)
|
||||
- Event feed will show: `connecting to ws://...`, `connected`, `snapshot`
|
||||
|
||||
4. If connection fails:
|
||||
- Ensure LVA is running and the WebSocket server is active
|
||||
- Verify the URL is correct (check host and port)
|
||||
- Check browser console (F12 → Console tab) for error messages
|
||||
- Verify network connectivity and firewall rules
|
||||
|
||||
## Using the Web Console
|
||||
|
||||
### Connection & Status Section
|
||||
|
||||
Displays real-time information:
|
||||
- **Status Indicator**: Gray (disconnected) or Green (connected)
|
||||
- **WebSocket URL**: The connection endpoint
|
||||
- **STATE**: Current LVA state (idle, listening, thinking, etc.)
|
||||
- **VOLUME**: Current volume level (0-100%)
|
||||
- **MUTED**: Microphone mute status (yes/no)
|
||||
- **HA CONNECTED**: Home Assistant connection status
|
||||
- **AUDIO LEVEL**: Visual bar showing real-time audio input level
|
||||
|
||||
### Event Feed
|
||||
|
||||
Shows a chronological log of all events received from LVA:
|
||||
|
||||
**Example events:**
|
||||
- `connecting to ws://localhost:6055`
|
||||
- `connected`
|
||||
- `snapshot` - Initial state when connected
|
||||
- `wake_word_detected` - Wake word detected
|
||||
- `listening` - Microphone is recording
|
||||
- `stt_text: "set a timer for 10 seconds"` - Recognized speech
|
||||
- `thinking` - Processing the command
|
||||
- `tts_text: "OK, timer set."` - Assistant's response
|
||||
- `tts_speaking` - Playing the response audio
|
||||
- `idle` - Returned to waiting state
|
||||
- `timer_ticking`, `timer_ringing` - Timer events
|
||||
- `volume_changed`, `volume_muted` - Volume events
|
||||
- `disconnected` - Connection lost
|
||||
|
||||
Click "clear" to remove all events from the feed.
|
||||
|
||||
### Commands Section
|
||||
|
||||
Send commands to LVA by clicking buttons:
|
||||
|
||||
**Listening & Pipeline:**
|
||||
- **Start listening** - Manually trigger listening (as if wake word was detected)
|
||||
- **Stop pipeline** - Abort the current voice pipeline (stops listening, thinking, speaking)
|
||||
|
||||
**Audio Control:**
|
||||
- **Volume up** / **Volume down** - Adjust volume by small increments
|
||||
- **Set volume** - Set exact volume level using slider (0.0-1.0)
|
||||
- **Mute microphone** / **Unmute microphone** - Toggle microphone mute
|
||||
|
||||
**Media & Timers:**
|
||||
- **Pause media player** / **Resume media player** / **Stop media player** - Control music playback
|
||||
- **Stop timer ringing** - Silence an active timer alarm
|
||||
|
||||
**Button Presses:**
|
||||
- **Single press**, **Double press**, **Triple press**, **Long press** - Simulate physical button inputs
|
||||
- Useful for testing button-based interactions if LVA is connected to hardware buttons
|
||||
|
||||
## Example Workflow
|
||||
|
||||
1. **Start LVA server** with WebSocket peripheral API enabled
|
||||
2. **Open** `peripheral_web_console.html` in browser
|
||||
3. **Click "connect"** to establish WebSocket connection
|
||||
4. **Observe events** as you interact with LVA via voice (e.g., "Hey Home Assistant, what time is it?")
|
||||
5. **Send commands** from the console (e.g., click "Mute microphone" to test mute functionality)
|
||||
6. **Watch feedback** in the event feed and status indicators
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Won't Establish
|
||||
- **Problem**: "disconnected" status persists
|
||||
- **Solutions**:
|
||||
- Verify LVA is running: `docker ps` (if using Docker) or check if the service started
|
||||
- Check the WebSocket URL is correct
|
||||
- Ensure firewall allows traffic on port 6055
|
||||
- Check browser console (F12) for detailed error messages
|
||||
|
||||
### No Events Appearing
|
||||
- **Problem**: Connected but no events in feed
|
||||
- **Solutions**:
|
||||
- Trigger an event manually (speak a wake word, click a button)
|
||||
- Check that the LVA peripheral API server is properly initialized
|
||||
- Verify the WebSocket connection is truly active (status should show "connected")
|
||||
|
||||
### Volume/State Not Updating
|
||||
- **Problem**: Controls don't seem to work
|
||||
- **Solutions**:
|
||||
- Confirm "connected" status is shown
|
||||
- Check that LVA is not muted at the system level
|
||||
- Try stopping and reconnecting
|
||||
- Check LVA logs for errors
|
||||
|
||||
### CORS or Mixed Content Errors
|
||||
- **Problem**: Console shows security errors
|
||||
- **Solutions**:
|
||||
- Use `http://` with `ws://` (not `https://` with `wss://`)
|
||||
- Serve the HTML over HTTP if testing locally
|
||||
- Ensure your LVA server is configured for WebSocket connections
|
||||
|
||||
## Protocol Details
|
||||
|
||||
The console communicates with LVA using JSON over WebSocket:
|
||||
|
||||
**Messages from LVA (Events):**
|
||||
```json
|
||||
{"event": "event_name", "data": {...}}
|
||||
```
|
||||
|
||||
**Messages to LVA (Commands):**
|
||||
```json
|
||||
{"command": "command_name", "data": {...}}
|
||||
```
|
||||
|
||||
**Initial Snapshot (on connect):**
|
||||
```json
|
||||
{
|
||||
"event": "snapshot",
|
||||
"data": {
|
||||
"muted": false,
|
||||
"volume": 1.0,
|
||||
"ha_connected": true,
|
||||
"last_stt_text": "...",
|
||||
"last_tts_text": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For detailed protocol documentation, see `peripheral_api.py` in the Linux Voice Assistant repository.
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Accessing Remotely
|
||||
To access the console from another computer:
|
||||
|
||||
1. **Expose LVA server** to your network (modify firewall/port forwarding)
|
||||
2. **Open console** from remote machine
|
||||
3. **Update WebSocket URL** to your LVA server's network address:
|
||||
```
|
||||
ws://your-lva-server-ip:6055
|
||||
```
|
||||
|
||||
### Integration with Peripherals
|
||||
This console mirrors the interface used by physical peripherals (LED boards, buttons, etc.):
|
||||
- Hardware peripherals use the same WebSocket API
|
||||
- Testing here helps debug peripheral integrations
|
||||
- Both console and hardware can be connected simultaneously
|
||||
|
||||
### Development & Debugging
|
||||
Use browser Developer Tools (F12) to:
|
||||
- Monitor WebSocket messages in Network tab
|
||||
- Check console for JavaScript errors
|
||||
- Inspect HTML structure and styling
|
||||
- Test custom commands before deploying to hardware
|
||||
Reference in new issue
Block a user