openclaw-voice-assistant/QUICKSTART.md

# Quick Start Guide - Bilingual Voice Assistant

**AI Now Inc - Del Mar Demo Unit**  
**Laboratory Assistant:** Claw 🏭

## 🚀 Installation (5 minutes)

### Step 1: Clone and Install

```bash
# Navigate to workspace
cd /home/pi

# Clone or copy the voice-assistant folder
# (If copying from another machine, use scp or git)

# Make install script executable
cd voice-assistant
chmod +x install.sh

# Run installation
sudo ./install.sh
```

### Step 2: Configure

Edit the configuration file:

```bash
nano config.local.json
```

Update these settings:
- `openclaw.ws_url`: Your OpenClaw server address
- `openclaw.api_key`: Your API key (if required)
- `music.library_path`: Path to your music files

### Step 3: Add Music (Optional)

```bash
# Copy MP3 files to music directory
cp /path/to/your/music/*.mp3 /home/pi/Music/

# Or download sample music
# (Ensure you have rights to the music)
```

### Step 4: Test

```bash
# Run in demo mode first
./venv/bin/python3 main.py --mode demo

# Or run in test mode
./venv/bin/python3 main.py --mode test
```

### Step 5: Run

```bash
# Start the service
sudo systemctl start voice-assistant

# Or run manually
./start.sh
```

## 🎤 Voice Commands

### Hotword
First, say the hotword to activate:
- **English:** "Hey Osiris"
- **Mandarin:** "你好 Osiris"

### General Commands

| English | Mandarin | Description |
|---------|----------|-------------|
| "Hello" | "你好" | Greeting |
| "What time is it?" | "现在几点？" | Get current time |
| "How are you?" | "你好吗？" | Greeting response |
| "Ask Claw: [question]" | "问 Claw：[问题]" | Ask OpenClaw |

### Music Commands

| English | Mandarin | Description |
|---------|----------|-------------|
| "Play [song name]" | "播放 [歌曲名]" | Play music |
| "Play music" | "播放音乐" | Play any music |
| "Pause" | "暂停" | Pause playback |
| "Resume" | "继续" | Resume playback |
| "Stop" | "停止" | Stop playback |
| "Next" | "下一首" | Next track |
| "Previous" | "上一首" | Previous track |
| "Volume up" | "音量大" | Increase volume |
| "Volume down" | "音量小" | Decrease volume |

## 🔧 Troubleshooting

### Microphone Not Working

```bash
# Check if microphone is detected
arecord -l

# Test recording
arecord -d 3 test.wav
aplay test.wav

# Check volume levels
alsamixer
# Press F4 to see capture levels
# Use arrow keys to adjust
```

### No Sound Output

```bash
# Check audio output
speaker-test -t wav

# Set default output
alsamixer
# Press F6 to select output device
```

### Hotword Not Detecting

1. **Check microphone sensitivity:**
   ```bash
   alsamixer
   # Adjust capture levels
   ```

2. **Reduce background noise**

3. **Speak clearly and closer to microphone**

4. **Adjust sensitivity in config:**
   ```json
   {
     "speech": {
       "hotword_sensitivity": 0.6  // Higher = more sensitive
     }
   }
   ```

### Music Not Playing

```bash
# Check if files are in correct location
ls -la /home/pi/Music/

# Verify file format (MP3, WAV, OGG, FLAC)
file /home/pi/Music/song.mp3

# Test playback manually
./venv/bin/python3 -c "from music_player import MusicPlayer; p = MusicPlayer(); p.play(list(p.music_library.values())[0])"
```

### OpenClaw Not Connecting

1. **Check network connection:**
   ```bash
   ping 192.168.1.100  # Replace with your server IP
   ```

2. **Verify OpenClaw is running:**
   ```bash
   # On server
   openclaw status
   ```

3. **Check firewall:**
   ```bash
   sudo ufw status
   ```

## 📊 Logs

### View Live Logs

```bash
# Service logs
sudo journalctl -u voice-assistant -f

# Installation logs
cat /var/log/voice-assistant-install.log

# Application logs (if configured)
tail -f /var/log/voice-assistant.log
```

### Debug Mode

```bash
# Run with debug logging
./venv/bin/python3 main.py --mode run --log-level DEBUG
```

## 🔄 Updates

### Update Installation

```bash
cd /home/pi/voice-assistant

# Pull latest changes (if using git)
git pull

# Reinstall dependencies
source venv/bin/activate
pip install -r requirements.txt --upgrade
```

### Update Configuration

```bash
# Edit local config
nano config.local.json

# Restart service
sudo systemctl restart voice-assistant
```

## 🛑 Uninstall

```bash
# Run uninstaller
sudo ./uninstall.sh

# Or manually:
sudo systemctl stop voice-assistant
sudo systemctl disable voice-assistant
sudo rm -rf /home/pi/voice-assistant
sudo rm /etc/systemd/system/voice-assistant.service
```

## 📚 Additional Resources

- [Full Documentation](README.md)
- [Google AIY Voice Kit Docs](https://github.com/google/aiyprojects-raspbian)
- [Porcupine Hotword Detection](https://github.com/Picovoice/porcupine)
- [OpenClaw Documentation](https://docs.openclaw.ai)

## 🆘 Support

For issues or questions:
1. Check the [README.md](README.md)
2. Review logs: `sudo journalctl -u voice-assistant`
3. Test in demo mode first
4. Ensure all dependencies are installed

---

**AI Now Inc** - Del Mar Show Demo Unit  
**Version:** 1.0.0  
**Last Updated:** 2026-02-28