Blog

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!