Debugging on ESP8266

Recompilation is required

In order to debug applications based on Sming Framework make sure that you are using Sming version 4 or newer.

To use, (re)compile your application with the ENABLE_GDB option and flash it to the board. For this example we will use the Live Debug sample application:

cd $SMING_HOME/../samples/LiveDebug
make components-clean # -- required if you need to debug inside framework or libraries
make ENABLE_GDB=1 # -- recompiles your application with debugging support
make flashapp # flashes ONLY the (re)compiled application

The device will restart then wait for a debugger to be connected:

make gdb

This will start a new debugging session where you can run your code interactively:

Remote debugging using /dev/ttyUSB0
gdbstub_init () at /home/slavey/dev/esp8266.dev.box/dev/Sming/Sming//gdb/gdbstub.cpp:914
914         gdb_do_break();
(gdb)

If the debugger is exited, the application will continue execution as normal. Re-connecting the debugger will pause execution.

GDB commands

There are multiple commands supported in GDB and we will mention only some of them.

List current source code

One possibility is to see the source code of the current line where the execution has stopped. To achieve this you should type list in the gdb console:

(gdb) list
909     SD(GDBSTUB_ENABLE_HOSTIO);
910 #undef SD
911
912 #if GDBSTUB_BREAK_ON_INIT
913     if(gdb_state.enabled) {
914         gdb_do_break();
915     }
916 #endif
917 }
918

Break the execution

This command will pause the debugger once it reaches a specific function or line in the code. This is called breakpoint and can be set like this:

(gdb) break blink
Breakpoint 1 at 0x40105d4c: file app/application.cpp, line 66.

Notice: break sets a software breakpoint. This means that the blink function must be in IRAM. Otherwise the execution will fail. If you take a look at samples/LiveDebug/app/application.cpp#L663, you will see a in the definition of the init function the following attribute GDB_IRAM_ATTR:

void GDB_IRAM_ATTR init()

This attribute is used to put the init function in IRAM when the code is compiled with the ENABLE_GDB=1 directive.

Continue the execution

To continue the execution of the application we can use the continue command:

(gdb) continue
Continuing.
LiveDebug sample
Explore some capabilities of the GDB debugger.

[OS] mode : sta..
...
[OS] cnt

Breakpoint 1, blink () at app/application.cpp:66
66 {
(gdb)

Because we have set already a breakpoint for the blink function the execution will be paused when the blink function is reached and from here you can go to the next line or see the current values of the variables.

Go to the next line

This can be done using next:

(gdb) next
67      digitalWrite(LED_PIN, ledState);

See variable value

The command to see a value is print followed by the name of the value. For example to see the value of the ledState variable inside the blink function we could type:

(gdb) print ledState
$1 = true

You can see more useful commands here.

Or watch the following short video