Hacker-Software
/
esp32-claude-robbie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
esp32-claude-robbie/docs/setup_guide.md

10 KiB
Raw Permalink 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

  1. ESP32-S3 via USB-C anschließen
  2. 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!

chat:
  url: "https://claude.ai/chat/..."  # URL deines Claude-Chats

Wichtig: Diese Bridge nutzt Claude.ai direkt im Browser (via Selenium), NICHT die Anthropic API. Du brauchst einen Claude.ai Account aber keinen API Key!

2.4 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.5 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!)

2.6 Spracheingabe (STT) - Wie es funktioniert

Die Spracheingabe sammelt deine Worte intelligent:

  1. Aufnahme startet sobald du sprichst
  2. Heartbeat pausiert automatisch während du redest
  3. Mehrere Sätze werden gesammelt und zusammengefügt
  4. Nach 5 Sekunden Stille gilt die Eingabe als komplett
  5. Mit dem nächsten TICK wird alles an Claude gesendet

Beispiel-Ablauf:

Du: "Hallo Claude..."        → 🎤 Stefan spricht...
Du: "...kannst du mal..."    →   → Hallo Claude
Du: "...nach links schauen?" →   → kannst du mal
                             →   → nach links schauen?
[5 Sekunden Stille]          → ✓ Stefan (komplett): Hallo Claude kannst du mal nach links schauen?
[TICK wird gesendet]         → Claude bekommt die komplette Nachricht

Warum 5 Sekunden?

  • Gibt dir Zeit zum Nachdenken zwischen Sätzen
  • Verhindert dass halbe Sätze gesendet werden
  • Claude bekommt immer den kompletten Gedanken

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

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

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