9.1 KiB

Raw Blame History

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 (VS Code Extension oder CLI)
Python 3.9+
Git

Teil 1: ESP32 Firmware

1.1 Repository klonen

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

1.2 WiFi konfigurieren

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

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

1.3 Firmware kompilieren

cd claudes_eyes/esp32_firmware

# Mit PlatformIO CLI:
pio run

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

1.4 Firmware flashen

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

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:

sudo apt install portaudio19-dev python3-pyaudio espeak-ng

Arch Linux/Manjaro:

sudo pacman -S portaudio espeak-ng

Fedora:

sudo dnf install portaudio-devel espeak-ng

Mac:

brew install portaudio espeak

Windows:

pip install pipwin
pipwin install pyaudio
# espeak nicht nötig - pyttsx3 nutzt SAPI5

2.2 Python Environment einrichten

Einfachste Methode (empfohlen):

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):

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):

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

flatpak-spawn --host python3 chat_audio_bridge.py

2.3 Konfiguration anpassen

Kopiere die Konfiguration:

cp config.yaml config.local.yaml

Bearbeite config.local.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/

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

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

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
Q	Bridge beenden
Ctrl+C	Bridge beenden

Tipp: Nutze Mute wenn du nicht willst dass Hintergrundgeräusche oder Gespräche mit anderen aufgenommen werden. Das Mikrofon nimmt sonst alles auf!

Teil 3: Hardware zusammenbauen

3.1 Freenove Kit

Folge der Freenove Anleitung für den mechanischen Aufbau
NICHT den mitgelieferten ESP32 einbauen!
Motorverkabelung zum Shield notieren

3.2 Waveshare Board einbauen

Montiere das Waveshare Board anstelle des Freenove ESP32
Verbinde die Kabel gemäß docs/gpio_mapping.md
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/:

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

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:

esp32:
  host: "localhost"
  port: 5000
  api_key: "claudes_eyes_secret_2025"

Schritt 4: Bridge starten (in neuem Terminal)

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)

# 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

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:

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

Hardware zusammenbauen
GPIO-Pins verifizieren und ggf. in config.h anpassen
Firmware flashen
Python Bridge einrichten
Ersten Testlauf machen
Claude die Wohnung erkunden lassen!

Viel Spaß beim Erkunden! 🤖

9.1 KiB Raw Blame History