Helper Scripts Reference

Complete list of all helper scripts on your Batocera device and what they do.

📁 Location

All scripts are in: /userdata/voice-assistant/

Production Scripts (Use These!)

`voice_assistant_wake.py` (8.7K)

Purpose: Main wake word voice assistant

What it does:

Listens continuously for “Hey Jarvis” wake word
Records 5 seconds after wake word detection
Transcribes with whisper.cpp
Gets LLM response from Ollama
Speaks response via Piper TTS
Returns to listening mode automatically

Usage:

cd /userdata/voice-assistant
python3 voice_assistant_wake.py

Requirements:

whisper-cli and all .so libraries
hey_jarvis.onnx wake word model
Python libraries: sounddevice, scipy, numpy, ollama, openwakeword
Ollama running with llama3.2 model

`voice_assistant_button.py` (7.1K)

Purpose: Button-triggered voice assistant

What it does:

Waits for button press on GPIO 23
LED on GPIO 25 blinks during operation
Records 5 seconds after button press
Transcribes with whisper.cpp
Gets LLM response from Ollama
Speaks response via Piper TTS

Usage:

cd /userdata/voice-assistant
python3 voice_assistant_button.py

Requirements:

whisper-cli and all .so libraries
Button wired to GPIO 23
LED wired to GPIO 25 (optional)
Python libraries: sounddevice, scipy, numpy, ollama
Ollama running with llama3.2 model

Setup Scripts

`setup-voice-assistant.sh` (6.9K)

Purpose: Initial setup and model downloads

What it does:

Creates directory structure (/userdata/voice-assistant/)
Downloads required models:
- Whisper model (ggml-base.en.bin)
- Wake word model (hey_jarvis.onnx)
- Voice model (en_US-amy-medium.onnx)
Downloads and installs Piper TTS
Creates environment setup script (setup-env.sh)
Checks for whisper-cli (but doesn’t compile it)
Provides clear instructions for manual steps

Usage:

cd /userdata/voice-assistant
bash setup-voice-assistant.sh

IMPORTANT: This script sets up everything EXCEPT:

whisper.cpp compilation (must be done on Mac with Docker)
Python library installation (must be copied to lib/)
Ollama installation (separate process)

Run this on a clean Pi to download all models.

`start.sh` (3.4K)

Purpose: Convenient startup script with error checking

What it does:

Sets up environment variables
Starts Ollama if not running
Checks for required models
Validates whisper-cli and libraries exist
Runs either wake word or button mode
Provides clear error messages if something is missing

Usage:

cd /userdata/voice-assistant

# Start wake word mode (default)
bash start.sh

# Or explicitly
bash start.sh wake

# Start button mode
bash start.sh button

Benefits:

Automatic Ollama startup
Clear error messages
Validates all dependencies before starting

`install-service.sh` (4.0K)

Purpose: Install systemd service for auto-start on boot

What it does:

Creates systemd service file
Configures service to start on boot
Allows choosing between wake word or button mode
Creates Ollama dependency service if missing
Enables and starts the service

Usage:

cd /userdata/voice-assistant
sudo bash install-service.sh

After installation, manage with:

# Start/stop
sudo systemctl start voice-assistant
sudo systemctl stop voice-assistant

# Check status
sudo systemctl status voice-assistant

# View logs
sudo journalctl -u voice-assistant -f

# Disable auto-start
sudo systemctl disable voice-assistant

`setup-env.sh` (Created by setup-voice-assistant.sh)

Purpose: Set environment variables for voice assistant

What it does:

Sets LD_LIBRARY_PATH to include voice assistant directory
Sets PYTHONPATH to include lib/ directory

Usage:

cd /userdata/voice-assistant
source setup-env.sh
python3 voice_assistant_wake.py

Note: start.sh does this automatically, so you usually don’t need to run this manually.

📝 Optional/Utility Scripts

`create_beep.sh` (753B)

Purpose: Create placeholder sound files

What it does:

Creates empty placeholder .wav files in sounds/ directory
These are placeholders for future sound effects

Usage:

bash create_beep.sh

Note: Not essential - the voice assistant works without these.

Complete File Inventory

Current State of `/userdata/voice-assistant/`

/userdata/voice-assistant/
├── voice_assistant_wake.py      ⭐ Main wake word script (8.7K)
├── voice_assistant_button.py     ⭐ Main button script (7.1K)
├── whisper-cli                  ⭐ STT binary (compiled for Pi 5)
├── libwhisper.so.1              ⭐ Required library
├── libggml.so.0                 ⭐ Required library
├── libggml-base.so.0            ⭐ Required library
├── libggml-cpu.so.0             ⭐ Required library
├──
├── setup-voice-assistant.sh     🛠️ Setup script (6.9K)
├── start.sh                      🛠️ Startup script (3.4K)
├── install-service.sh            🛠️ Service installer (4.0K)
├── setup-env.sh                🛠️ Environment setup (auto-created)
├──
├── create_beep.sh              📝 Optional utility (753B)
├──
├── README.md                    📚 Project overview
├── setup-guide.md              📚 Complete setup instructions
├── wake-word-working.md        📚 Wake word breakthrough details
├── wrong-assumptions.md        📚 Lessons learned
├──
├── models/
│   ├── hey_jarvis.onnx         🎯 Wake word model
│   ├── ggml-base.en.bin        🎯 Whisper model
│   └── en_US-amy-medium.onnx   🎯 Piper voice model
├──
├── piper/
│   └── piper                   🗣️ TTS binary
├──
├── lib/                        🐍 Python libraries
│   ├── sounddevice/
│   ├── scipy/
│   ├── numpy/
│   ├── ollama/
│   └── openwakeword/
└──
└── temp/                       📝 Temporary audio files

Quick Start Workflows

Fresh Install on New Pi

# 1. Run setup to download models
bash setup-voice-assistant.sh

# 2. Compile whisper.cpp on your Mac (see setup-guide.md Section 5)
#    Then copy whisper-cli and .so files to Pi

# 3. Copy Python libraries to lib/

# 4. Install Ollama (see setup-guide.md Section 1)

# 5. Test
bash start.sh

Daily Usage

# Wake word mode
bash start.sh

# Button mode
bash start.sh button

# Or directly
python3 voice_assistant_wake.py
python3 voice_assistant_button.py

Enable Auto-Start

sudo bash install-service.sh
# Choose mode (wake or button)
# Service will start on every boot

Important Notes

What’s Missing from Scripts

The helper scripts do not and cannot do these things (must be done manually):

Compile whisper.cpp - Must be done on Mac with Docker (see setup-guide.md)
Install Python libraries - Must be copied to lib/ directory
Install Ollama - Separate download and installation

These are documented in setup-guide.md with detailed instructions.

What the Scripts Do Well

The helper scripts excel at:

✓ Downloading models (whisper, wake word, voice)
✓ Installing Piper TTS
✓ Setting up directory structure
✓ Validating dependencies
✓ Managing startup and services
✓ Providing clear error messages

🔧 Script Comparison

Script	Purpose	Run Once?	Interactive?	When to Use
setup-voice-assistant.sh	Initial setup	✅ Yes	⚠️ Prompts	First install
start.sh	Start assistant	❌ No	❌ No	Every time you want to run
install-service.sh	Auto-start setup	✅ Yes	✅ Yes	Want boot-time startup
setup-env.sh	Environment vars	❌ No	❌ No	Manual Python execution
create_beep.sh	Sound placeholders	✅ Yes	❌ No	Optional customization

🎓 Best Practices

Use start.sh instead of running Python directly - it validates everything
Run setup-voice-assistant.sh only once - it downloads models you keep
Use install-service.sh if you want the assistant to always run
Check setup-guide.md if anything fails - it has detailed troubleshooting
Read wrong-assumptions.md if you’re debugging - it documents common mistakes

📞 Troubleshooting

“whisper-cli not found”

You need to compile whisper.cpp on your Mac
See setup-guide.md Section 5

“Module not found” errors

Python libraries are missing from lib/
Copy them from a working system

“Ollama not running”

Run bash start.sh instead - it starts Ollama automatically
Or manually: /userdata/ollama/bin/ollama serve &

Wake word not detecting

Check audio: arecord -D plughw:0,0 -r 16000 -f S16_LE -d 3 /tmp/test.wav
Verify levels: Speak clearly 6-12 inches from mic
Check model: ls -la models/hey_jarvis.onnx

🎉 Summary

You now have a complete, clean set of helper scripts:

2 production scripts (wake + button)
4 setup/utility scripts (setup, start, service install, env)
4 documentation files (README, SETUP_GUIDE, WAKE_WORD, WRONG_ASSUMPTIONS)
All temporary/failed attempts cleaned up
All scripts updated to reflect the working implementation

Everything is ready to use and properly documented! 🚀

Keyboard shortcuts

Botface Voice Assistant Documentation