The Arduino for ESP8266 project comes with a GDB Stub that allows us to remotely attach to our board and debug it from the USB Serial connection! Nevertheless this GDB Stub is not very mature, and setting it up can be quite a struggle.
This post summarizes the steps to have the latest working Arduino for ESP8266 GDB Stub available (28/05/2019).
The simplest most structured way to use it, is not to rely on the Arduino IDE. We will be using the makeEspArduino project.
First we need to download and install the Arduino for ESP8266 project. I keep all my arduino tools in ~/programs/arduino
folder.
cd ~/programs/arduino git clone https://github.com/esp8266/Arduino esp8266 cd esp8266/tools git checkout 2.5.2 python get.py
The latest version that I could get properly working is 2.5.2, so we need to checkout to that branch.The get.py
python script will download the required tools.
Then we need to download the makeEspArduino project
cd ~/programs/arduino git clone https://github.com/esp8266/Arduino
Now we can configure our project! We just need to create a Makefile and include the provided makeEspArduino.mk
ESP_ROOT := $(HOME)/programs/arduino/esp8266 ESP_LIBS := $(ESP_ROOT)/libraries UPLOAD_PORT := /dev/ttyUSB0 BOARD := nodemcu FLASH_DEF := 4M1M SKETCH := project.ino LIBS := $(ESP_LIBS)/ESP8266WiFi \ $(ESP_LIBS)/ESP8266WebServer \ $(ESP_LIBS)/ESP8266HTTPClient \ $(ESP_LIBS)/EEPROM \ $(ESP_LIBS)/GDBStub \ BUILD_EXTRA_FLAGS := -Og -ggdb include $(HOME)/programs/arduino/makeEspArduino/makeEspArduino.mk
The -Og -ggdb
compiler flags includes the required debugging symbols in the final binary required by GDB. We can disable this flags once we are done debugging. In LIBS
we include all the different libraries we want to use. We can find them in ~/programs/arduino/esp8266/libraries
.
We also need to include the GDB Stub in our Arduino code as follows:
#include <Arduino.h> #include <GDBStub.h> void setup() { Serial.begin(115200); gdbstub_init(); } void loop() { Serial.println("Running"); delay(100); }
And we are ready to go. To build and upload the program we just need to connect the board via USB and run:
make flash
Now we need to launch the xtensa gdb tool. We can create an alias that we can store in our .bashrc for convenience:
alias gdb-esp='$HOME/programs/arduino/esp8266/tools/xtensa-lx106-elf/bin/xtensa-lx106-elf-gdb'
Now we just need to run gdb-esp
. Next we need to set some hardware configurations. We need to run the following commands in GDB:
set remote hardware-breakpoint-limit 1 set remote hardware-watchpoint-limit 1 set remote interrupt-on-connect on set remote kill-packet off set remote symbol-lookup-packet off set remote verbose-resume-packet off mem 0x20000000 0x3fefffff ro cache mem 0x3ff00000 0x3fffffff rw mem 0x40000000 0x400fffff ro cache mem 0x40100000 0x4013ffff rw cache mem 0x40140000 0x5fffffff ro cache mem 0x60000000 0x60001fff rw set serial baud 115200
Now we can load the generated elf file. We can find the file using the following command:
sudo find /tmp -name '*.elf'
We load the file in GDB:
file /tmp/mkESP/project_nodemcu/project.elf
We can add these configurations to a .gdbinit
in the project root folder. We should also launch gdb-esp
from this root folder.
Once we have loaded the configuration and the elf file, we can attach to our board:
target remote /dev/ttyUSB0
It will interrupt the program. It has to be notice that only one breakpoint can be set at a time. The thb
(Temporary Hardware Breakpoint) command is quite convenient in order to set temporary break points. We can set one in the loop function, and continue.
thb loop continue list
And now we should be ready to continue debugging our program!
To sum up, everything is pretty good explained in the Arduino ESP8266 Wiki. The only important thing missing is to know that the latest working version is 2.5.2 and that we need to correctly set the -Og -ggdb
compilation flags.
Happy debugging!