Ladění programu na ESP32 z visual studio code a použití raspberry pi jako JTAG adaptéru

Daniel Skopalík sdílel návod, jak použít populární jednodeskový počítač RaspberryPi jako JTAG programátor například ESP32.

Výhody a vlastnosti:

– Možnost přidávání brakepointů v kódu, krokování, sledování stavu proměnných atd.

– Není potřeba žádný placený software ani registrace nikam (jako třeba platform.io).

– Raspberry pi zero w je levnější než většina JTAG adaptérů na trhu.

– Raspberry komunikuje s vaším počítačem přes wifi – možnost galvanického oddělení PC od debugované desky.

– Funguje s jakýmkoliv ESP32 modulem, který má dostupné JTAG piny. (např. LOLIN32)

– VSCode Arduino addon – ve vs code jsou dostupné všechny funkce Arduino studia (library manager, atd)

– Nezávislé na OS vašeho počítače, mělo by to fungovat i na linuxu nebo macu

– Složitější nastavení, placené platform.io nastavíte snadněji.

Tento návod je pouze pro ESP32. Adaptér by měl být použitelný i pro ESP8266, AVR nebo STM32, konfigurace ale bude jiná (Jiný toolchain, jiné parametry gdb, možná bude potřeba upravit jiné konfigurační soubory.

Úvodem

V dalším postupu budu používat 2 pracovní složky:
D:develESP32tools kde mám uloženy nástroje.
C:UsersxxxxxDocumentsArduinoYourProject kde je uložen sketch a další pracovní soubory.

Postup uvedený níže byl otestován s několika různými ESP moduly, nicméně nenesu jakoukoliv odpovědnost za případná poškození vašeho hardware nebo software.

Je zapotřebí mít nainstalováno Arduino IDE verze 1.8 nebo vyšší. Verze z windows store není podporována, je potřeba verze instalovaná běžným instalátorem z https://www.arduino.cc

Do visual studio code je potřeba doinstalovat následující addony:

Arduino https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.vscode-arduino

Native debug https://marketplace.visualstudio.com/items?itemName=webfreak.debug

Také doporučuji (přidává intelisense do C a C++)

C/C++ https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools

V Arduino IDE nebo vs code přes board manager nainstalovat podporu pro ESP32

Pro ssh přístup k raspberry pi je potřeba nainstalovat putty a zvolit plnou instalaci (včetně plink a pscp). Ke stažení na oficiálních stránkách https://www.putty.org/

Postup – část první – příprava raspberry pi

1. Stáhnout zip s image system. Image je pro raspberry pi 1 nebo zero. Na raspberry pi 2/3 je potřeba připravit image vlastní viz poslední sekce. Odkaz pro stažení připraveného image https://uloz.to/!3LhurmpOVlvI/rasbian-pi-zero-openocd-zip

2. Použít program Etcher nebo Win32 disk imager pro zapsaní image na kartu. V případě použití win32 disk imager je potřeba zip soubor napřed rozbalit. Stačí SD karta o velikosti 2GB.

3. Systém přistupuju ke kartě jako read only. Raspbery pi není potřeba vypínat příkazem, stačí odpojit napájení, nehrozí že by došlo k poškození souborového systému. Nevýhodou read only SD karty je že nelze použít trik s wpa_suplicant.conf souborem pro jednoduchou konfiguraci wifi.

4. Vložit sd kartu do raspberry, připojit monitor a klávesnici.

5. Po nabootování se přihlásit do konzole, uživatelské jméno je pi, heslo raspberry, stejné jako ve výchozím image raspbianu.

6. Spustit příkaz rw, tím přepneme souborový systém do režimu pro zápis a provedené změny budou platné I po restartu.

7. Spustit příkaz sudo raspi-config, a pomocí tohoto průvodce nastavit připojení k vaší wifi síti, doporučuji také změnit heslo.

8. Příkaz ro pro přechod do read only režimu.

9. Po restartu by se raspberry mělo připojit k vaší wifi.

10. Pomocí putty se z vašeho počítače připojit k raspberry. Alespoň jednou je nutné se připojit a potvrdit certifikát, jinak nebude možné navázání ssh spojení ze scriptu.

Postup – část druhá – nástroje na PC

11. Stáhnout xtensa-esp32-elf toolchain. Toto je debugger (gdb client) pro procesor který používá ESP32. toolchain je ke stažení na stránce https://docs.espressif.com/projects/esp-idf/en/latest/get-started/windows-setup-scratch.html v sekci Alternative Setup.

Rozbalit do D:develESP32tools , vznikne zde složka xtensa-esp32-elf

12. Stáhnout powershell script UploadOverRpi.ps1 a umístit jej do D:develESP32tools.

13. Spustit powershell a zadat příkaz. Toto umožní spuštění nepodepsaných powershell skriptů.
set-executionpolicy Unrestricted

14. Ve scriptu UploadOverRpi.ps1 nahradit IP adresu 192.168.128.110 skutečnou IP adresou raspbery pi ve vaší síti.

15. Ve složce s projektem(tam kde je .ino soubor) je složka .vscode, v ní je soubor launch.json ve kterém je potřeba také změnit IP adresu.

16. V případě že namísto D:develESP32tools chcete použít jiný adresář, je potřeba upravit cesty v launch.json, task.json, UploadOverRpi.ps1

17. Pokud máte putty nainstalováno jinde než ve výchozím adresáři (c:Program Files (x86)PuTTY), tak je potřeba upravit tuto cestu v UploadOverRpi.ps1

Postup – připojení JTAG a kontrola funkce

18. Zapojení JTAG.

TDI adaptéru spojit s TDI na ESP, stejně TDO spojit s TDO. JTAG datové linky se NEKŘÍŽÍ jako RX/TX na uart rozhraní!!!

19. Spuštění openOCD

Připojit se přes SSH na raspberry a spustit openOCD následujícím příkazem:
sudo openocd -s /usr/local/share/openocd/scripts/ -f interface/raspberrypi-native.cfg -f board/esp-wroom-32.cfg

Výstup by měl vypadat nějak takto:

OpenOCD by měl detekovat 2 procesorová jádra v ESP32 a poslouchat na TCP portu 3333

20. Test spojení z GDB clienta. Pro tento test doporučuji do ESP nahrát blink příklad z arduina nebo jiný program který blikáním LEDky nebo jiný způsobem bude indikovat běh/zastavení programu.

Otevřít nový příkazový řádek a spustit
D:develESP32toolsxtensa-esp32-elfbinxtensa-esp32-elf-gdb.exe

Do gdb konzole postupně zadat následující příkazy, IP adresu 192.168.128.110 v prvním příkazu nahradit skutečnou IP adresou vašeho raspberry.

První příkaz otevře spojení na gdb server (openOCD obsahuje gdb server)

Druhý příkaz zastaví procesor na ESP, LEDka by měla přestat blikat.

Continue – pokračování programu, LEDka opět bliká.

Takhle by to mělo vypadat v příkazovém řádku:

21. Pokud se neobjevila žádná chyba, znamená to, že zapojení JTAG adaptéru je správné a konfigurace openOCD a gdb je v pořádku.

Postup – část čtvrtá – konfigurace projektu

Následující json soubory jsou ve složce .vscode

1. Úprava arduino.json

arduino.json soubor by měl být vytvořen automaticky při otevření Arduino sketche v vs code. Do totoho souboru je potřeba doplnit nastavení cesty ke složce, kam se bude ukládat zkompilovaný výsledek. Stačí přidat řádek: „output“: „BuildOutput/“

celý soubor může vypadat nějak takto:

2. launch.json a tasks.json

launch json obsahuje nastavení debugeru. Tasks.json obsahuje definici tasku který zkopíruje binárku programu do paměti raspberry, spustí programování ESP32 přes JTAG a následně přes spustí openOCD na raspberry.

3. Spuštění ladění:

Zkompilovat kód (Arduino – verify)

V kódu si nastavit brakepointy dle libosti.

V vs code přejít na panel debug (Ctrl + Shift + D)

Vybrat debugger Arduino-GDB-openOCD-upload

Mít otevřený hlavní .ino soubor (to je důležité kvůli relativním cestám k .elf)

Klávesou F5 spustit debug

Ukázkový projekt: Vzorové kódy zde

Příprava image pro raspberry pi

Pokud nevěříte mnou připravenému image nebo z jakéhokoli jiného důvodu si chce připravit vlastní, zde je návod:

1. Stáhnout čistý raspbian stretch lite

2. Nahrát image na kartu (etcher, disk32imager)

3. Nabootovat, nastavit síť, povolit ssh.

4. OpenOCD z repozitářů nepodporuje interface bcm2835gpio, proto je nutné si openocd zkompilovat. Návod k tomu zde: https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi/compiling-openocd nebo:
sudo apt-get install git autoconf libtool make pkg-config libusb-1.0-0 libusb-1.0-0-dev

mkdir openOcdSrc

cd openOcdSrc/

git clone https://github.com/espressif/openocd-esp32

cd openocd-esp32/

ls

./bootstrap

./configure –enable-sysfsgpio –enable-bcm2835gpio

make

sudo make install

5. Upravit konfigurační soubory openOCD: esp32.cfg, esp-wroom-32.cfg, raspberrypi-native.cfg V /usr/local/share/openocd/scripts/. Upravené cfg soubory a shell skripty jsou v přiloženém zip souboru. Paranoici nechť si obsah těchto 6ti krátkých souborů zkontrolují.

6. Z přiloženého zipu zkopírovat do home adresáře složku s .sh skripty.
https://uloz.to/!z1PI5vQpcSI1/debug-pi-config-zip

7. Vytvořit simlink (pokud je karta read only, domovský adresář není zapisovatelný). V případě že se rozhodnete nechat SD kartu v read/write režimu, stačí vytvořit složku s názvem upload. Symlink vytvoříte příkazem:

sudo ln -s /tmp /home/pi/upload

8. Doplňková funkce – udělat SD kartu read only, to vám umožní bez problému vypínat raspberry prostým odpojením napájení. Mám vyzkoušený tento skript https://learn.adafruit.com/read-only-raspberry-pi/overview

wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/read-only-fs.sh

sudo bash read-only-fs.sh

V mnou připraveném image je povoleno použití read/write jumperu na pinu 21. Můžete si jej zakázat nebo povolit na jiném pinu podle potřeby.

Pokud nechcete použít skript z adafruit, tady je alternativní návod: http://hallard.me/raspberry-pi-read-only/ pro raspberry pi zero s wifi je potřeba udělat i ty kroky které jsou v návodu v sekci pro raspberry pi 3.

Také aliasy ro a rw nejsou součástí skriptu z adafruit, pokud je chcete doplnit je potřeba editovat konfigurační soubor bashe dle tohoto návodu.

Zdroje:

[1] https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html

[2] https://community.platformio.org/t/esp32-pio-unified-debugger/4541/20

[3] https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi/compiling-openocd

[4] http://hallard.me/raspberry-pi-read-only/

[5] https://learn.adafruit.com/read-only-raspberry-pi/overview

A taky stackoverflow a mnoho dalších.