Integrierten USB-Debugger vom ESP32-S3 benutzen

Ein sehr nützliches Werkzeug beim Programmieren ist der Debugger, mit dem das Programm an definierten Breakpoints angehalten und dann die aktuellen Werte der Variablen, der Weg durchs Programm zur aktuellen Position, genannt Call Stack, und noch vieles mehr angeschaut werden können. Dadurch lassen sich viele Fehler entdecken, ohne zusätzliche Ausgaben ins Programm einzubauen.

Die meisten Programmiersprachen haben einen Debugger eingebaut, der zum Beispiel im Editor VS Code direkt aufgerufen werden kann.

Nicht ganz so einfach ist es, wenn man ein Programm auf einem Mikrocontroller wie dem Arduino debuggen möchte: Um Mikrocontroller zu debuggen, ist für gewöhnlich ein externer Debugger notwendig, der an den Mikrocontroller angeschlossen wird.

Deutlich einfacher ist es beim ESP32-S3 Mikrocontroller von Espressif, der auf der neuesten Version des Heltec WiFi LoRa 32 V3 Dev-Boards zum Einsatz kommt, mit dem ich meine Gartensensoren gebaut habe: Manawyrm hat mir den Tipp gegeben, dass der ESP32-S3 einen eingebauten USB JTAG Debugger hat.

Leider ist der USB-Anschluss vom Heltec-Board nicht an die USB-Schnittstelle vom ESP32 angeschlossen, sondern stattdessen an einen zusätzlichen USB-TTL-Wandler. Um trotzdem den eingebauten USB-Debugger verwenden zu können, habe ich ein USB-Kabel direkt an die entsprechenden Pins gelötet.

Im Folgenden erkläre ich, wie ich den internen USB JTAG Debugger vom ESP32-S3 auf dem Heltec WiFi LoRa 32 V3 verwendet habe.

Material

• Dev-Board mit ESP32-S3.
• Ein altes USB-Kabel, alternativ ein USB Anschlussbuchse Breakout-Board.
• Ein PlatformIO-Setup in Visual Studio Code.

Schritte

1. Ein altes USB-Kabel auftrennen.
2. Die einzelnen Litzen vom USB-Kabel folgendermaßen an das Heltec-Board löten:
   • GPIO 19 an DATA- (weiß)
   • GPIO 20 an DATA+ (grün)
   • GND an GND (schwarz)
   • 5V an VUSB (rot)
3. Den eingebauten USB-Port nicht verbinden! Stattdessen das zusätzlich ran gelötete USB-Kabel mit dem Computer verbinden. Es sollte ein USB-Gerät namens „USB JTAG/serial debug unit“ auftauchen.
4. In der platformio.ini folgendes hinzufügen:

debug_tool = esp-builtin
build_type = debug

5. Nicht vergessen, Breakpoints im Code zu setzen!
6. Jetzt sollte der Debugger erfolgreich attachen, wenn man in VS Code unter Run and Debug oben auf das grüne Start Debugging Play-Icon klickt. Daneben sollte PIO Debug ausgewählt sein.

Achtung: Der interne USB-Port vom Heltec-Board hat zwischen VBUS und 5V noch eine Fuse. Die wird hier übersprungen, da der interne VUSB-Pin nicht nach außen geführt wird. Der Hack kann also theoretisch dazu führen, dass das Board durch Spannungsspitzen zerstört wird.

Der Hack sollte für alle ESP32-S3 basierten Boards funktionieren. Die Schritte sind dabei immer folgende: USB-Pinouts auf dem Dev-Board identifizieren, Kabel ran löten, debuggen.

Darüber hinaus ist der interne USB-Anschluss vom ESP32 interessant, da darüber auch andere USB-Devices wie Eingabegerät, Massenspeicher und so weiter erzeugt werden können. Damit habe ich mich allerdings nicht beschäftigt. Details dazu gibt es in der Espressif-Dokumentation.

Was ich noch nicht herausgefunden habe ist, wie ich Debugger und serielle Konsole zeitgleich verwenden kann.

Viel Spaß beim Debuggen!

Links

• How to use JTAG built-in debugger of the ESP32-S3 in PlatformIO
• USB Serial/JTAG Controller Console
• PlatformIO Debugging
• Github-Issue zu ESP32-S3 Built-in debugging support
• ESP32-S3 Technical Reference Manual
  • Kapitel 8, Chip Boot Control, erläutert die Funktion von GPIO 0 zur Steuerung des USB-Modus. GPIO 0 ist beim Heltec-Board standardmäßig auf 1 und kann über den Button PRG auf 0 gezogen werden.
  • Kapitel 33, USB Serial/JTAG Controller, erläutert die genauen Funktionen vom integrierten JTAG-Debugger. Unter anderem lässt sich der Debugger auch verwenden, um andere Dev-Boards ohne eingebauten Debugger per JTAG zu debuggen!