ESP-IDF v5.5.4 einrichten und ESP-Claw bauen – Schritt für Schritt

Nachdem ich euch in Teil 1 meiner ESP-Claw-Serie die Vision vorgestellt habe, einen lokalen KI-Agenten auf einem HMI-Board zum Leben zu erwecken, geht es in diesem Beitrag darum die Entwicklungsumgebung einzurichten. Daher zeige ich euch jetzt Schritt für Schritt, wie ich die Entwicklungsumgebung ESP-IDF v5.5.4 aufgesetzt und ESP-Claw zum ersten Mal kompiliert habe. Ich beschreibe den Weg unter Windows 11 – unter Linux und macOS ist das Prozedere ähnlich, nur die Installer und Pfade sind etwas anders.

Diese Anleitung enthält eine wichtige Lektion, die mich einen halben Abend gekostet hat und die ich euch deshalb gleich am Anfang mitgeben möchte.

Die richtige ESP-IDF-Version Installieren

Mein erster Versuch ging schief. Ich hatte mir aus Gewohnheit die „Espressif-IDE 3.1.0 with ESP-IDF v5.3.1“ heruntergeladen. Es ist ein Komplettpaket, das die Espressif-eigene Eclipse-basierte IDE mit einer älteren ESP-IDF-Version bündelt. Sieht nach dem bequemsten Einstieg aus und stand ganz oben bei Espressif auf der Download Seite. Aber genau hier müsst ihr etwas aufpassen.

Der Grund: ESP-Claw benötigt mindestens ESP-IDF v5.5.x. Und für eine reibungslose Installation des Python-Hilfstools esp-bmgr-assist, das ESP-Claw zwingend benötigt, sollte es ESP-IDF v5.5.4 sein. Bei v5.3.1 stieß ich auf folgendes Problem:

• Der in v5.3.1 hinterlegte Python-Paket-Mirror war auf dem Stand vom 06. März 2023.
• esp-bmgr-assist wurde aber erst danach veröffentlicht.
• Ergebnis: pip install esp-bmgr-assist findet das Paket nicht und der Build von ESP-Claw schlägt fehl.

Daraufhin habe ich die ESP-IDF v5.5.4 als separaten Offline-Installer nachinstalliert. pip install esp-bmgr-assist lief dort sofort durch, und der Build startete fehlerfrei.

HIer geht es zu der Espressif Donload Seite: https://dl.espressif.com/dl/esp-idf/

ESP-IDF v5.5.4

Meine Empfehlung an euch

Gute Nachricht: Ihr könnt beide ESP-IDF-Versionen problemlos parallel auf dem Rechner installieren. Sie kommen sich nicht in die Quere, solange ihr jeweils die passende PowerShell-Verknüpfung verwendet.

Phase 1: ESP-IDF v5.5.4 herunterladen

Geht auf die offizielle Espressif-Downloadseite und achtet wie oben gezeigt genau darauf die aktuelle Version herunter zu laden.

Link: https://dl.espressif.com/dl/esp-idf/

Dort findet ihr eine Auswahl verschiedener Installer. Wählt für Windows folgendes aus:

• Version: ESP-IDF v5.5.4 oder neuer
• Variante: Offline Installer (ca. 1,6 GB)

Der Offline-Installer bringt alle Python-Pakete und Toolchains direkt mit. Ihr seid damit unabhängig von Mirror-Engpässen und langen Online-Downloads während der Installation.

Phase 2: ESP-IDF installieren

Startet den heruntergeladenen Installer und folgt dem Assistenten. Achtet besonders auf den Installationspfad:

• Wählt einen kurzen Pfad ohne Leerzeichen und ohne Sonderzeichen.
• Bei mir: D:\Programme\Espressif554\
• Vermeidet C:\Program Files (x86)\... – das Leerzeichen und die Klammern können später zu Build-Fehlern führen.

Wenn ihr gefragt werdet, welche Komponenten installiert werden sollen, lasst die Standardauswahl. Der Installer richtet euch automatisch eine „ESP-IDF 5.5 PowerShell“ als Verknüpfung im Startmenü ein. Genau diese Verknüpfung braucht ihr später.

Nach erfolgreicher Installation einmal die PowerShell die sich am Ende der Installation geöffnet hatte neu starten. Nur so wurden bei mir die Umgebungsvariablen sauber übernommen. Bis ich darauf kam hatte ich schon wieder eine kleine Weile Fehleranalyse betrieben denn eigentlich war ja die ESP-PowerShell frisch gestartet worden.

Phase 3: Die richtige PowerShell öffnen

Das ist ein Punkt, an dem viele Anfänger stolpern: ESP-IDF-Befehle funktionieren nur in der speziell vorbereiteten ESP-IDF-PowerShell, nicht in einer normalen Windows-PowerShell.

Im Startmenü findet ihr nach der Installation den Eintrag:

• ESP-IDF 5.5 PowerShell

Diese Verknüpfung lädt im Hintergrund das ESP-IDF-Environment, setzt die Pfade richtig und aktiviert die richtige Python-Umgebung. Ihr erkennt sie daran, dass beim Start eine Zeile wie diese erscheint:

Using Python in D:\Programme\Espressif554\python_env\idf5.5_py3.11_env\Scripts

Falls ihr versehentlich die v5.3.1-PowerShell verwendet: Schließt das Fenster und öffnet die richtige. Die beiden Umgebungen lassen sich nicht innerhalb derselben Session umschalten.

ESP-IDF v5.5.4 PowerShell

Phase 4: ESP-Claw von GitHub klonen

Jetzt holen wir uns den ESP-Claw-Quellcode. Ich habe ESP-Claw bewusst außerhalb des ESP-IDF-Verzeichnisses geklont, damit die beiden sauber getrennt bleiben.

In meiner ESP-IDF-PowerShell wechsle ich in ein eigenes Arbeitsverzeichnis und klone das Repository:

Befehl: cd D:\

Befehl: mkdir esp32-claw

Befehl: cd esp32-claw

Befehl: git clone --recursive https://github.com/espressif/esp-claw.git

Der Schalter --recursive ist wichtig — ESP-Claw bringt eine ganze Reihe an Git-Submodulen mit, die sonst fehlen würden.

Nach dem Klonen sieht meine Verzeichnisstruktur so aus:

• D:\esp32-claw\esp-claw\application\edge_agent\ – die Hauptanwendung, die wir bauen werden
• D:\esp32-claw\esp-claw\components\ – die wiederverwendbaren ESP-Claw-Komponenten

Phase 5: esp-bmgr-assist installieren

Damit ESP-Claw seine Board-Konfiguration verarbeiten kann, brauche ich noch ein Python-Hilfstool von Espressif. Das wird einfach per pip in die ESP-IDF-Python-Umgebung installiert:

Befehl: pip install esp-bmgr-assist

Ihr solltet eine Ausgabe ähnlich dieser sehen:

Successfully installed esp_bmgr_assist-0.8.1

Falls ihr hier eine Fehlermeldung bekommt, dass das Paket nicht gefunden wird: Dann seid ihr versehentlich in der falschen PowerShell gelandet (vermutlich v5.3.1) oder habt die richtige wie eingangs beschrieben nicht einmal neu gestartet nach der Installation. Schließt das Fenster und öffnet die ESP-IDF 5.5 PowerShell aus dem Startmenü.

Phase 6: Den ESP32-P4 als Ziel-Chip einstellen

Jetzt wechsle ich in das edge_agent-Verzeichnis der ESP-Claw-Anwendung und teile ESP-IDF mit, dass ich für den ESP32-P4 bauen möchte:

Befehl: cd D:\esp32-claw\esp-claw\application\edge_agent

Befehl: idf.py set-target esp32p4

Dieser Schritt erzeugt die initiale sdkconfig-Datei und lädt alle benötigten Abhängigkeiten herunter Bei mir waren das 76 Komponenten, darunter ESP-Hosted, LVGL, esp_codec_dev und viele andere. Das dauert beim ersten Mal einige Minuten. Habt Geduld und holt euch einen Kaffee.

Phase 7: Die Stolperfalle mit der Chip-Revision

Jetzt kommt ein Punkt, den die offizielle ESP-Claw-Doku verschweigt und der mich nochmal eine Stunde Fehlersuche gekostet hat:

Die Standard-Konfiguration von ESP-IDF erwartet einen ESP32-P4 mit Silizium-Revision v3.0 oder neuer. Mein Guition JC1060P470 verwendet aber einen frühen ESP32-P4-Chip mit Revision v1.3. Das ist ein typisches Phänomen bei Boards aus 2024/Anfang 2025 und war auf der Seite des Händler von AliExpress so nicht zu erkenne. Okay dafür hat das Board mit Porto auch nur 25,-€ gekostet. Mit der Default-Einstellung weigert sich der Bootloader, die Firmware zu starten.

Die Lösung ist eine kleine Anpassung in menuconfig:

Befehl: idf.py menuconfig

In dem nun erscheinenden Konfigurationsmenü navigiere ich zu:

• Component config -> Hardware Settings -> Chip revision

Dort aktiviere ich folgende Option:

• Select ESP32-P4 revisions <3.0 (No >=3.x Support)
• Minimum supported chip revision: Rev v0.0
• Maximum supported chip revision: Rev v1.99

Bis ich das gefunden hatte hat es etwas gedauert. Ich hoffe das Menü bleibt stabil und ändert sich nicht da es echt viele Punkte und Unterpunkte hat.

Mit S speichere ich die Konfiguration und mit Q verlasse ich das Menü. Ab jetzt akzeptiert der Bootloader auch ältere P4-Silizium-Revisionen wie meine v1.3.

Wichtig: Wenn ihr ein Board mit neuerem P4-Chip (v3.0+) habt wie z. B. den ESP32-P4 Function EV Board oder den M5Stack Tab5 dann überspringt diesen Schritt einfach. Die Default-Einstellung passt dann für euch.

Phase 8: Der erste Build

Jetzt kommt der spannende Moment. Mit einem einzigen Befehl starte ich den kompletten Build:

Befehl: idf.py build

Beim ersten Mal dauert das je nach Rechner zwischen 5 und 15 Minuten. ESP-IDF kompiliert nicht nur den ESP-Claw-Code, sondern auch alle 76 Abhängigkeiten -— vom WiFi-Stack über LVGL bis zur Lua-Runtime.

Wenn alles glatt läuft, erscheint am Ende eine Ausgabe wie diese:

edge_agent.bin binary size 0x2392d0 bytes. Smallest app partition is 0x400000 bytes. 0x1c6d30 bytes (44%) free.

Mit anderen Worten: Die Firmware ist etwa 2,3 MB groß, und auf der OTA-Partition mit 4 MB ist noch reichlich Platz für Erweiterungen. Genau das brauche ich später für meine eigenen Skills.

Phase 9: Was habe ich jetzt erreicht?

Nach diesen Schritten habe ich:

• Eine sauber installierte ESP-IDF v5.5.4-Entwicklungsumgebung
• Eine lokale Kopie von ESP-Claw samt allen Submodulen
• Eine fertig kompilierte Firmware-Datei edge_agent.bin für meinen ESP32-P4
• Den ersten Beweis, dass meine Build-Toolchain funktioniert

Was ich noch nicht habe: Eine passende Board-Adaption für mein Guition JC1060P470. Die Firmware ist aktuell für den ESP32-P4 Function EV Board konfiguriert. Also ein Espressifs eigenes Referenz-Board. Wenn ich diese Firmware so auf mein Guition flashen würde, würden Display, Touch, Audio und ESP-Hosted/WiFi nicht funktionieren, weil die Pin-Belegung anders ist.

Ganz ehrlich jetzt ging die Suche nach einem passenden Beispiel von dem ich lernen konnte wie so eine Board-Adaption aussehen könnte für das JC1060P470 richtig los.

Genau diese Board-Adaption ist das Thema von Teil 3 meiner Serie – und es ist ehrlich gesagt der spannendste und gleichzeitig kniffligste Teil des ganzen Projekts.

Mein persönliches Fazit zu Teil 2

Die Einrichtung der ESP-IDF-Entwicklungsumgebung ist keine Raketenwissenschaft, aber es gibt drei Stolperfallen, die euch mehrere Stunden kosten können, wenn ihr sie nicht kennt:

1. Die richtige ESP-IDF-Version – v5.5.4 für ESP-Claw, nicht v5.3.1.
2. Die richtige PowerShell – die „ESP-IDF 5.5 PowerShell“ aus dem Startmenü und auch gerne einmal die PowerShell neustarten.
3. Die Chip-Revision – bei älteren ESP32-P4-Chips muss menuconfig angepasst werden.

Wenn ihr diese drei Punkte beherzigt, kompiliert ESP-Claw beim ersten Versuch hoffentlich ohne Fehler. Damit habt ihr die Basis geschaffen, um in den nächsten Beiträgen tiefer einzusteigen. Dann geht es von der Board-Adaption über die Ollama-Anbindung bis hin zu eigenen Skills.

Im nächsten Teil zeige ich euch, wie ich für mein Guition JC1060P470 eine eigene Board-Adaption von Grund auf geschrieben habe. Das klappte aber nur weil ich ein Beispiel gefunden hatte mit YAML-Konfigurationsdateien für Peripherie und Geräte, einer eigenen setup_device.c und dem Einsatz des ESP Board Managers. Ein Thema, bei dem ich viel über die innere Architektur von ESP-Claw gelernt habe.

Wir lesen uns im nächsten Teil!

Was kommt in den nächsten Beiträgen?

• Teil 1: Auftakt und Vorstellung der Vision
• Teil 2 (dieser Beitrag): ESP-IDF v5.5.4 einrichten und ESP-Claw bauen – Schritt für Schritt
• Teil 3: Ein neues Board zu ESP-Claw hinzufügen – meine Board-Adaption für das Guition JC1060P470
• Teil 4: ESP-Claw mit dem eigenen Ollama-Server verbinden – Konfiguration und erste Chats
• Teil 5: Capabilities und Skills verstehen – die Architektur eines ESP-Claw-Agenten
• Teil 6: Eine eigene Skill schreiben – das Roboter-Auto fernsteuern oder den Geschirrspühler erklären
• Teil 7: Sprache rein, Sprache raus – das HMI-Board als echter Voice-Assistant zur Unterstützung an der Waschmaschine
• Teil 8: Lua-Skripte für Verhaltensmuster – wenn der Agent eigenständig handelt