esp32-claude-robbie/claudes_eyes/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 Python Environment einrichten

```bash
cd claudes_eyes/python_bridge

# Virtuelle Umgebung erstellen (empfohlen)
python -m venv venv

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

# Dependencies installieren
pip install -r requirements.txt
```

### 2.2 PyAudio installieren (für Mikrofon)

**Linux:**
```bash
sudo apt install python3-pyaudio portaudio19-dev
pip install pyaudio
```

**Windows:**
```bash
pip install pipwin
pipwin install pyaudio
```

**Mac:**
```bash
brew install portaudio
pip install pyaudio
```

### 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

```bash
# Normal:
python bridge.py

# Mit eigener Config:
python bridge.py --config config.local.yaml

# Simulation ohne Hardware:
python bridge.py --simulate

# Debug-Modus:
python bridge.py --debug
```

---

## 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 API testen

```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.2 Python Client testen

```bash
python esp32_client.py 192.168.178.XXX
```

### 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

---

## 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! 🤖*