esp32-claude-robbie/docs/setup_guide.md

# Setup Guide - Claude's Eyes

## Voraussetzungen

### Hardware
- Waveshare ESP32-S3-Touch-LCD-2
- OV5640 Kamera mit 120° Weitwinkelobjektiv
- Freenove 4WD Car Kit
- USB-C Kabel zum Flashen
- Powerbank (oder LiPo Akku)

### Software
- [PlatformIO](https://platformio.org/) (VS Code Extension oder CLI)
- Python 3.9+
- Git

---

## Teil 1: ESP32 Firmware

### 1.1 Repository klonen

```bash
cd ~/Dokumente/programmierung/esp32
# Das Projekt ist bereits in claudes_eyes/
```

### 1.2 WiFi konfigurieren

Öffne `esp32_firmware/src/config.h` und ändere:

```cpp
#define WIFI_SSID "DEIN_WLAN_NAME"
#define WIFI_PASSWORD "DEIN_WLAN_PASSWORT"
#define API_KEY "dein_geheimer_api_key"
```

### 1.3 Firmware kompilieren

```bash
cd claudes_eyes/esp32_firmware

# Mit PlatformIO CLI:
pio run

# Oder in VS Code:
# PlatformIO Icon -> Build
```

### 1.4 Firmware flashen

1. ESP32-S3 via USB-C anschließen
2. Boot-Modus aktivieren (falls nötig: BOOT-Taste halten beim Einstecken)

```bash
pio run --target upload

# Monitor öffnen:
pio device monitor
```

### 1.5 Erfolg prüfen

Im Serial Monitor solltest du sehen:

```
╔═══════════════════════════════════════╗
║        Claude's Eyes v1.0             ║
║   Autonomous Exploration Robot        ║
╚═══════════════════════════════════════╝

[Main] Initializing display...
[Main] Initializing camera...
[Camera] PSRAM found, using double buffering
...
╔═══════════════════════════════════════╗
║          SYSTEM READY                 ║
║   IP: 192.168.178.xxx                 ║
║   Waiting for Claude...               ║
╚═══════════════════════════════════════╝
```

---

## Teil 2: Python Bridge

### 2.1 System-Dependencies installieren (ZUERST!)

PyAudio und pyttsx3 benötigen System-Bibliotheken, die VOR pip install installiert werden müssen:

**Debian/Ubuntu:**
```bash
sudo apt install portaudio19-dev python3-pyaudio espeak-ng
```

**Arch Linux/Manjaro:**
```bash
sudo pacman -S portaudio espeak-ng
```

**Fedora:**
```bash
sudo dnf install portaudio-devel espeak-ng
```

**Mac:**
```bash
brew install portaudio espeak
```

**Windows:**
```bash
pip install pipwin
pipwin install pyaudio
# espeak nicht nötig - pyttsx3 nutzt SAPI5
```

### 2.2 Python Environment einrichten

**Einfachste Methode (empfohlen):**

```bash
cd python_bridge

# Automatisches Setup - erstellt venv und installiert alles
./start_venv.sh --reset

# Bridge starten
./start_venv.sh --run
```

Das `start_venv.sh` Script:
- Erstellt eine neue virtuelle Umgebung
- Installiert alle Dependencies aus `requirements.txt`
- Versucht PyAudio zu installieren (optional, für STT)
- Aktiviert die venv automatisch

**Manuelle Installation (falls nötig):**

```bash
cd python_bridge

# Virtuelle Umgebung erstellen
python3 -m venv venv

# Aktivieren
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# Dependencies installieren
pip install -r requirements.txt

# PyAudio separat (optional, für STT)
pip install pyaudio
```

**Falls PyAudio fehlschlägt (Debian/Ubuntu):**
```bash
# System-PyAudio nutzen
sudo apt install python3-pyaudio

# Dann venv mit System-Paketen neu erstellen
rm -rf venv
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install -r requirements.txt
```

**Flatpak/VS Code Problem:**
Wenn du VS Code als Flatpak nutzt, laufen Befehle im Container und sehen die System-Pakete nicht. Lösung: Terminal AUSSERHALB von VS Code nutzen, oder:
```bash
flatpak-spawn --host python3 chat_audio_bridge.py
```

### 2.3 Konfiguration anpassen

Kopiere die Konfiguration:

```bash
cp config.yaml config.local.yaml
```

Bearbeite `config.local.yaml`:

```yaml
esp32:
  host: "192.168.178.XXX"  # IP des Roboters
  api_key: "dein_api_key"  # Muss mit config.h übereinstimmen!

claude:
  api_key: ""  # Oder setze ANTHROPIC_API_KEY Environment Variable
```

### 2.4 Anthropic API Key

Erstelle einen API Key auf https://console.anthropic.com/

```bash
# Linux/Mac:
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows (PowerShell):
$env:ANTHROPIC_API_KEY="sk-ant-..."
```

### 2.5 Bridge starten

**Mit start_venv.sh (empfohlen):**
```bash
# Normale Ausführung
./start_venv.sh --run

# Mit Debug-Logging
./start_venv.sh --run -d

# Nach Python-Update oder bei Problemen
./start_venv.sh --reset
```

**Manuell:**
```bash
source venv/bin/activate
python chat_audio_bridge.py

# Mit Debug-Logging:
python chat_audio_bridge.py -d

# Mit eigener Config:
python chat_audio_bridge.py -c config.local.yaml
```

### 2.6 Keyboard-Shortcuts während der Bridge läuft

| Taste | Funktion |
|-------|----------|
| **M** | Mikrofon Mute/Unmute - schaltet STT stumm |
| **N** | Neuer Chat starten (bei Bilder-Limit) |
| **Q** | Bridge beenden |
| **Ctrl+C** | Bridge beenden |

**Tipps:**
- Nutze **Mute** wenn du nicht willst dass Hintergrundgeräusche aufgenommen werden
- Das Mikrofon startet standardmäßig **gemutet** - drücke **M** zum Aktivieren
- Claude.ai erlaubt max. **100 Bilder pro Chat**. Bei 90/95 Bildern warnt die Bridge
- Mit **N** startest du einen neuen Chat und die Instruktionen werden erneut gesendet
- Bilder werden nur hochgeladen wenn sie sich geändert haben (spart Limit!)

---

## Teil 3: Hardware zusammenbauen

### 3.1 Freenove Kit

1. Folge der Freenove Anleitung für den mechanischen Aufbau
2. **NICHT** den mitgelieferten ESP32 einbauen!
3. Motorverkabelung zum Shield notieren

### 3.2 Waveshare Board einbauen

1. Montiere das Waveshare Board anstelle des Freenove ESP32
2. Verbinde die Kabel gemäß `docs/gpio_mapping.md`
3. Kamera an den 24-Pin Connector anschließen

### 3.3 Verkabelung

```
Freenove Shield          Waveshare Board
─────────────────────────────────────────
Motor A IN1      <--->   GPIO 39
Motor A IN2      <--->   GPIO 40
Motor A PWM      <--->   GPIO 41
Motor B IN1      <--->   GPIO 42
Motor B IN2      <--->   GPIO 2
Motor B PWM      <--->   GPIO 1
Servo 1 (Pan)    <--->   GPIO 38
Servo 2 (Tilt)   <--->   GPIO 37
US Trigger       <--->   GPIO 21
US Echo          <--->   GPIO 47
5V               <--->   5V
GND              <--->   GND
```

### 3.4 Stromversorgung

- Option A: USB-C Powerbank am ESP32
- Option B: LiPo Akku am Waveshare Batterieanschluss
- Motoren können separate Stromversorgung brauchen

---

## Teil 4: Testen

### 4.1 Mock-Server (ohne Hardware!)

Du kannst die Bridge testen BEVOR die Hardware ankommt:

**Schritt 1: Testbilder vorbereiten**

Mach 10-20 Fotos aus deiner Wohnung und leg sie in `python_bridge/test_images/`:

```bash
cd python_bridge
mkdir -p test_images
# Kopiere JPG/PNG Dateien hierher
# z.B. 01_flur.jpg, 02_wohnzimmer.jpg, 03_kueche.jpg ...
```

**Schritt 2: Mock-Server starten**

```bash
cd python_bridge
./start_venv.sh  # Aktiviert venv
python mock_esp32.py
```

Der Server läuft auf `http://localhost:5000`

**Schritt 3: Config anpassen**

In `config.yaml`:
```yaml
esp32:
  host: "localhost"
  port: 5000
  api_key: "claudes_eyes_secret_2025"
```

**Schritt 4: Bridge starten (in neuem Terminal)**

```bash
cd python_bridge
./start_venv.sh --run
```

Claude "fährt" jetzt durch deine Testbilder! Bei jedem `forward` Befehl
wird das nächste Bild geladen.

---

### 4.2 API testen (echte Hardware)

```bash
# Im Browser:
http://192.168.178.XXX/

# Kamera testen:
http://192.168.178.XXX/api/capture?key=dein_api_key

# Status abrufen:
curl "http://192.168.178.XXX/api/status?key=dein_api_key"

# Motor testen:
curl -X POST "http://192.168.178.XXX/api/command?key=dein_api_key" \
     -H "Content-Type: application/json" \
     -d '{"action":"forward","speed":30,"duration_ms":500}'
```

### 4.3 TTS/STT testen

```bash
python tts_engine.py
python stt_engine.py
```

---

## Troubleshooting

### ESP32 bootet nicht
- USB-Kabel prüfen (manche sind nur zum Laden)
- Boot-Taste beim Einstecken halten
- COM-Port in PlatformIO prüfen

### Kamera funktioniert nicht
- Flexkabel prüfen (richtig eingesteckt?)
- PSRAM aktiviert? (sollte automatisch sein)
- Pin-Konflikte mit Display prüfen

### WiFi verbindet nicht
- SSID und Passwort prüfen
- 2.4 GHz Netzwerk? (5 GHz wird nicht unterstützt)
- Router in Reichweite?

### Motoren drehen nicht
- Stromversorgung prüfen
- GPIO-Pins korrekt verbunden?
- `ENABLE_MOTORS` in config.h auf `true`?

### TTS/STT funktioniert nicht
- PyAudio korrekt installiert?
- Mikrofon-Berechtigung erteilt?
- Audio-Ausgabegerät prüfen
- Bei "eSpeak not found": `sudo apt install espeak-ng`
- gTTS als Alternative (braucht Internet): In `config.yaml` setze `tts.engine: "gtts"`

### venv kaputt / "cannot execute: required file not found"
Das passiert wenn die venv mit einer anderen Python-Version erstellt wurde:
```bash
cd python_bridge
./start_venv.sh --reset  # Erstellt venv komplett neu
```

### VS Code Flatpak sieht System-Pakete nicht
VS Code als Flatpak läuft in einem Container. Lösung:
- Normales Terminal nutzen (nicht VS Code Terminal)
- Oder: `flatpak-spawn --host ./start_venv.sh --run`

---

## Nächste Schritte

1. Hardware zusammenbauen
2. GPIO-Pins verifizieren und ggf. in `config.h` anpassen
3. Firmware flashen
4. Python Bridge einrichten
5. Ersten Testlauf machen
6. Claude die Wohnung erkunden lassen!

---

*Viel Spaß beim Erkunden! 🤖*