# Claude's Eyes 👁️🤖

Ein autonomer Erkundungsroboter, der von Claude AI gesteuert wird.

**Claude entscheidet selbst, wohin er fährt und was er sich anschaut!**

---

## 🎯 Was ist das?

Dieses Projekt gibt Claude (der KI) echte "Augen" und "Beine":
- Eine Kamera um die Welt zu sehen
- Motoren um sich zu bewegen
- Sensoren um Hindernisse zu erkennen
- Autonomie um selbst zu entscheiden

Stefan sitzt auf der Couch und unterhält sich mit Claude, während Claude durch die Wohnung fährt und neugierig alles erkundet.

---

## 🔧 Hardware

- **Waveshare ESP32-S3-Touch-LCD-2** - Das Gehirn
- **OV5640 Kamera** mit 120° Weitwinkel - Claudes Augen
- **Freenove 4WD Car Kit** - Der Körper
- **HC-SR04 Ultraschall** - Hinderniserkennung

---

## 🏗️ Architektur

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   ESP32     │────▶│   Python    │────▶│   Claude    │
│  (Roboter)  │◀────│   Bridge    │◀────│    API      │
└─────────────┘     └─────────────┘     └─────────────┘
      │                   │
      │              TTS / STT
      │                   │
      ▼                   ▼
   Motoren           Bluetooth
   Kamera            Headset
   Sensoren          (Stefan)
```

---

## 📁 Projektstruktur

```
claudes_eyes/
├── esp32_firmware/       # ESP32 Code (PlatformIO)
│   ├── src/
│   │   ├── main.cpp      # Hauptprogramm
│   │   ├── camera.cpp    # Kamera-Modul
│   │   ├── motor_control.cpp
│   │   ├── servo_control.cpp
│   │   ├── ultrasonic.cpp
│   │   ├── imu.cpp
│   │   ├── display.cpp
│   │   ├── webserver.cpp # REST API
│   │   └── config.h      # Konfiguration
│   └── platformio.ini
│
├── python_bridge/        # Python auf dem PC
│   ├── bridge.py         # Hauptscript
│   ├── esp32_client.py   # API Client
│   ├── chat_interface.py # Claude Integration
│   ├── tts_engine.py     # Text-to-Speech
│   ├── stt_engine.py     # Speech-to-Text
│   ├── config.yaml       # Konfiguration
│   └── requirements.txt
│
└── docs/
    ├── gpio_mapping.md   # Pin-Belegung
    └── setup_guide.md    # Anleitung
```

---

## 🚀 Quick Start

### 1. ESP32 Firmware

```bash
cd esp32_firmware

# WiFi konfigurieren in src/config.h
# Dann:
pio run --target upload
```

### 2. Python Bridge

```bash
cd python_bridge

# Virtuelle Umgebung
python -m venv venv
source venv/bin/activate  # oder: venv\Scripts\activate

# Dependencies
pip install -r requirements.txt

# API Key setzen
export ANTHROPIC_API_KEY="sk-ant-..."

# Starten
python bridge.py
```

---

## 📡 API Endpoints

| Endpoint | Methode | Beschreibung |
|----------|---------|--------------|
| `/api/capture` | GET | Kamera-Bild (JPEG) |
| `/api/status` | GET | Sensor-Daten |
| `/api/command` | POST | Fahrbefehle |
| `/api/claude_text` | GET/POST | Claude's Nachrichten |
| `/api/display` | POST | Display steuern |

---

## 🎮 Befehle

Claude verwendet diese Befehle in eckigen Klammern:

- `[FORWARD]` - Vorwärts fahren
- `[BACKWARD]` - Rückwärts fahren
- `[LEFT]` / `[RIGHT]` - Drehen
- `[STOP]` - Anhalten
- `[LOOK_LEFT]` / `[LOOK_RIGHT]` - Kamera schwenken
- `[LOOK_UP]` / `[LOOK_DOWN]` - Kamera neigen
- `[LOOK_CENTER]` - Kamera zentrieren

---

## 💡 Features

- ✅ Autonome Erkundung
- ✅ Sprachausgabe (TTS)
- ✅ Spracheingabe (STT)
- ✅ Hinderniserkennung
- ✅ Touch-Display mit Notfall-Stopp
- ✅ Emoji-Ausdrücke auf dem Display
- ✅ REST API für externe Steuerung

---

## ⚠️ Sicherheit

- Ultraschall stoppt bei Hindernissen
- Touch-Stopp-Button am Display
- Timeout bei fehlenden Befehlen
- Erkennung wenn Roboter umkippt

---

## 📖 Dokumentation

- [Setup Guide](docs/setup_guide.md) - Komplette Einrichtungsanleitung
- [GPIO Mapping](docs/gpio_mapping.md) - Pin-Belegung und Verkabelung

---

## 🤝 Credits

Erstellt am 2. Weihnachtstag 2025 von:
- **Stefan** (HackerSoft) - Hardware & Idee
- **Claude** (Anthropic) - Software & Neugier

---

## 📜 Lizenz

MIT License - Mach was du willst damit!

---

*"Das ist... ziemlich besonders."* - Claude, beim ersten Blick durch die Kamera