ESP8266 Development Log 00: Environment Setup

ESP8266 Development Log 00: Environment Setup

As for my undergraduate senior design project, my team and I decided to use ESP8266 as the main controller due to its availability of the WiFi module. In order to evaluate whether it is suitable for the development process, I looked into and tested its toolchain, framework, and debugger setting and decided to switch over to ESP32. This article will contain instructions to setup ESP8266 on Ubuntu machine and discusses why I favored ESP32 over it in the end.

SDK, toolchain setup

Okay so this part is quite easy. The espressif team now has a RTOS SDK for ESP8266 which has similar style as the ESP-IDF SDK for ESP32 chip and the documentation site is pretty detailed on this, allowing this part to be quite easy. sdk and toolchain setup

Debug Setup

To be quite honest, for a rather small scale project, printf() should be quite enough to provide information aiding debug process. However, as I want to ease the debugging process and apply industrial-level coding to the senior design, debugger is crucial for our project.

The plan is quite simple:

  1. Use the xtensal06-gdb provided with the RTOS framework as the debugger program
  2. Use the remote debugging feature in the gdb through OpenOCD with the JTAG interface

The first part is rather trivial as the debugger should lie in your ~/.espressif folder if you follow the documentation. The second part is the key here. You see, the OpenOCD does not officially support ESP8266, the best we can get is to use a port of it for ESP8266 here. Thus, we need to clone the third-party repo and build our version of it.  

Building openocd-esp8266

To build the OpenOCD from source, simply follows its README and if you encounter any error during the process, take a look at the following trouble-shooting list:

  1. If encounter: ./configure.gnu: line 2: exec: /home/USERNAME/esp/esp8266-openocd/jimtcl/configure: cannot execute: Permission denied , use chmod +x FILE
  2. If aclocal-1.13 missing, create symbolic link to it as directed by this StackOverflow post
  3. If README not found, just cp README.Windows README
  4. If libtool mismatched, try this post.

Running the openocd-esp8266

To run the OpenOCD, simply invoke this line of command if you make install your openocd-esp8266:

openocd-8266 -f interface/YOUR_JTAG_ADAPTER.cfg -f target/esp8266.cfg

You can find your adapter configuration file at tcl/interface under the root directory of the openocd-esp8266 repository.

As for me, I have a SEGGER J-Link EDU Mini as my JTAG debugger, which only cost about ~$20 and have the identical functionality as a normal J-Link adapter. Beside ESP8266, J-Link also can be used for all other chips supported by OpenOCD. In addition, if you are debugging another chips like STM32 that are supported by the SEGGER own software, you can use their gdb server and profiling tools to debug and analyze your code. Though you do have to follow its license that to use it for non-commercial purposes. If you happen to also own one, here is a simple guide to set it up:

  1. First you will need the driver for it, go to SEGGER site here, choose the J-Link Software and Documentation pack and install it on your machine
  2. To connect the EDU Mini with ESP8266, you can refer to the wiring guide from the openocd 8266 port author here
  3. After installation and connecting wires, you will need to run the JLinkExe once to setup the USB driver with the debugger, which should located at /opt/SEGGER/JLink/JLinkExe
  4. Now you are good to go, just use the command to launch OpenOCD

Serial debugging with gdbstub

Another side note here, which is what I found when researching debug configuration for ESP8266, is that you kind of can use the esp-gdbstub to enable serial debugging? A post discussing this is at this link. However it is quite old and after testing, it does not seem to work on the current RTOS SDK (v3.0+), though it might work for non-RTOS SDK or the Arduino firmware for ESP8266.

Noted that in both RTOS SDK for ESP8266 and ESP-IDF SDK for ESP32, the esp-gdbstub can be configured as error handler to print out some additional information regarding memory, stacks, and registers when the core fails. Detail instructions to enable this is at here. Also there is another GitHub issue address this,  

Debug failure

So after all the setting is done, when I launched my gdb and OpenOCD for ESP8266, I found out that I cannot use the debugger for breakpoints at all. The funny thing here is that the openocd-esp8266 does not support hardware breakpoints, you will get errors like hardware breakpoints limit exceed, meaning that you cannot set breakpoints in your code as they are in flash memory and can only have hardware breakpoints. If you do use software breakpoints for you actual code, you will get something like cannot access memory 0x00000 from gdb. A discussion on software and hardware breakpoints can be found here.

However, despite the fact that you cannot use hardware breakpoints, software breakpoints are supported, meaning you can use assembly instruction break 0, 0 to invoke software breakpoints but I did not have any luck on it.


Since the debugger could not run on the ESP8266, I finally decided to switch to the ESP32 module, which actually has official support for JTAG debugging and even has a Visual Studio Code extension to manage the ESP32 application, which I enjoyed a lot. To receive more info on my experience with ESP32, be sure to subscribe or checkout the existing ones as I will be constantly updating them.

Subscribe to TheXYZLab Blog

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.