pyr0ball
173f7f37d4
Ports prior voice assistant research and prototypes from devl/Devops into the Minerva repo. Includes: - docs/: architecture, wake word guides, ESP32-S3 spec, hardware buying guide - scripts/: voice_server.py, voice_server_enhanced.py, setup scripts - hardware/maixduino/: edge device scripts with WiFi credentials scrubbed (replaced hardcoded password with secrets.py pattern) - config/.env.example: server config template - .gitignore: excludes .env, secrets.py, model blobs, ELF firmware - CLAUDE.md: Minerva product context and connection to cf-voice roadmap
184 lines
4.3 KiB
Markdown
Executable file
184 lines
4.3 KiB
Markdown
Executable file
# Maixduino Scripts
|
|
|
|
Scripts to copy/paste into MaixPy IDE for running on the Maix Duino board.
|
|
|
|
## Files
|
|
|
|
### 1. maix_test_simple.py
|
|
**Purpose:** Hardware and connectivity test
|
|
**Use:** Copy/paste into MaixPy IDE to test before deploying full application
|
|
|
|
**Tests:**
|
|
- LCD display functionality
|
|
- WiFi connection
|
|
- Network connection to Heimdall server (port 3006)
|
|
- I2S audio hardware initialization
|
|
|
|
**Before running:**
|
|
1. Edit WiFi credentials (lines 16-17):
|
|
```python
|
|
WIFI_SSID = "YourNetworkName"
|
|
WIFI_PASSWORD = "YourPassword"
|
|
```
|
|
2. Verify server URL is correct (line 18):
|
|
```python
|
|
SERVER_URL = "http://10.1.10.71:3006"
|
|
```
|
|
3. Copy entire file contents
|
|
4. Paste into MaixPy IDE
|
|
5. Click RUN button
|
|
|
|
**Expected output:**
|
|
- Display will show test results
|
|
- Serial console will print detailed progress
|
|
- Will report OK/FAIL for each test
|
|
|
|
---
|
|
|
|
### 2. maix_voice_client.py
|
|
**Purpose:** Full voice assistant client
|
|
**Use:** Copy/paste into MaixPy IDE after test passes
|
|
|
|
**Features:**
|
|
- Wake word detection (placeholder - uses amplitude trigger)
|
|
- Audio recording after wake word
|
|
- Sends audio to Heimdall server for processing
|
|
- Displays transcription and response on LCD
|
|
- LED feedback for status
|
|
|
|
**Before running:**
|
|
1. Edit WiFi credentials (lines 38-39)
|
|
2. Verify server URL (line 42)
|
|
3. Adjust audio settings if needed (lines 45-62)
|
|
|
|
**For SD card deployment:**
|
|
1. Copy this file to SD card as `main.py`
|
|
2. Board will auto-run on boot
|
|
|
|
---
|
|
|
|
## Deployment Workflow
|
|
|
|
### Step 1: Test Hardware (maix_test_simple.py)
|
|
```
|
|
1. Edit WiFi settings
|
|
2. Paste into MaixPy IDE
|
|
3. Click RUN
|
|
4. Verify all tests pass
|
|
```
|
|
|
|
### Step 2: Deploy Full Client (maix_voice_client.py)
|
|
**Option A - IDE Testing:**
|
|
```
|
|
1. Edit WiFi settings
|
|
2. Paste into MaixPy IDE
|
|
3. Click RUN for testing
|
|
```
|
|
|
|
**Option B - Permanent SD Card:**
|
|
```
|
|
1. Edit WiFi settings
|
|
2. Save to SD card as: /sd/main.py
|
|
3. Reboot board - auto-runs on boot
|
|
```
|
|
|
|
---
|
|
|
|
## Hardware Requirements
|
|
|
|
### Maix Duino Board
|
|
- K210 processor with KPU
|
|
- LCD display (built-in)
|
|
- I2S microphone (check connections)
|
|
- ESP32 WiFi module (built-in)
|
|
|
|
### I2S Pin Configuration (Default)
|
|
```python
|
|
Pin 20: I2S0_IN_D0 (Data)
|
|
Pin 19: I2S0_WS (Word Select)
|
|
Pin 18: I2S0_SCLK (Clock)
|
|
```
|
|
|
|
**Note:** If your microphone uses different pins, edit the pin assignments in the scripts.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### WiFi Won't Connect
|
|
- Verify SSID and password are correct
|
|
- Ensure WiFi is 2.4GHz (not 5GHz - Maix doesn't support 5GHz)
|
|
- Check signal strength
|
|
- Try moving closer to router
|
|
|
|
### Server Connection Fails
|
|
- Verify Heimdall server is running on port 3006
|
|
- Check firewall allows port 3006
|
|
- Ensure Maix is on same network (10.1.10.0/24)
|
|
- Test from another device: `curl http://10.1.10.71:3006/health`
|
|
|
|
### Audio Initialization Fails
|
|
- Check microphone is properly connected
|
|
- Verify I2S pins match your hardware
|
|
- Try alternate pin configuration if needed
|
|
- Check microphone requires 3.3V (not 5V)
|
|
|
|
### Script Errors in MaixPy IDE
|
|
- Ensure using latest MaixPy firmware
|
|
- Check for typos when editing WiFi credentials
|
|
- Verify entire script was copied (check for truncation)
|
|
- Look at serial console for detailed error messages
|
|
|
|
---
|
|
|
|
## MaixPy IDE Tips
|
|
|
|
### Running Scripts
|
|
1. Connect board via USB
|
|
2. Select correct board model: Tools → Select Board
|
|
3. Click connect button (turns red when connected)
|
|
4. Paste code into editor
|
|
5. Click run button (red triangle)
|
|
6. Watch serial console and LCD for output
|
|
|
|
### Stopping Scripts
|
|
- Click run button again to stop
|
|
- Or press reset button on board
|
|
|
|
### Serial Console
|
|
- Shows detailed debug output
|
|
- Useful for troubleshooting
|
|
- Can copy errors for debugging
|
|
|
|
---
|
|
|
|
## Network Configuration
|
|
|
|
- **Heimdall Server:** 10.1.10.71:3006
|
|
- **Maix Duino:** Gets IP via DHCP (shown on LCD during test)
|
|
- **Network:** 10.1.10.0/24
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
After both scripts work:
|
|
1. Verify Heimdall server is processing audio
|
|
2. Test wake word detection
|
|
3. Integrate with Home Assistant (optional)
|
|
4. Train custom wake word (optional)
|
|
5. Deploy to SD card for permanent installation
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- **Project overview:** `../PROJECT_SUMMARY.md`
|
|
- **Heimdall setup:** `../QUICKSTART.md`
|
|
- **Wake word training:** `../MYCROFT_PRECISE_GUIDE.md`
|
|
- **Server deployment:** `../docs/PRECISE_DEPLOYMENT.md`
|
|
|
|
---
|
|
|
|
**Last Updated:** 2025-12-03
|
|
**Location:** `/Library/Development/devl/Devops/projects/mycroft-precise/maixduino-scripts/`
|