Circuit-Forge/minerva
3
0
Fork 0
Code Issues 10 Pull requests Projects Releases Packages Wiki Activity Actions
minerva/hardware/maixduino/README.md
pyr0ball 173f7f37d4 feat: import mycroft-precise work as Minerva foundation 
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
2026-04-06 22:21:12 -07:00

4.3 KiB
Executable file
Raw Blame History

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): 
    WIFI_SSID = "YourNetworkName"
WIFI_PASSWORD = "YourPassword"
  2. Verify server URL is correct (line 18): 
    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)

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/