Create a WiFi Black Magic GDB Probe from ESP8266

Thanks to the work of Valmantas Palikša (walmis) you can now convert an ESP8266 into a Black Magic Probe, to use over WiFi!

This allows you to cost effectively add a WiFi GDB Debugger to a variety of SAM/SAMD/STM32/MBED boards, as you would a standard Black Magic Probe.

 

Follow the Sections below as needed, we reccomend the Quick Start section in the first instance to get going...

To get up and running quickly, we have a pre-compiled binary and upload script, which allow you to flash your ESP8266 right away

Flashing the ESP8266 Device

Note Icon Note:

You will need to install the ESP8266 Boards and Tools before proceeding with this section.
  1. Download the Pre-Compiled Binary file from here.
  2. Extract to a location on your PC (ensure no spaces in path name)
  3. Ensure your ESP8266 is connected to your PC and is ready for programming over Serial
  4. Run the UploadToESP8266.bat, and enter the COM port when prompted
Command Prompt for BIN Flasher Script

Once completed you can reset the ESP8266 board, and a new WiFi Network should appear, blackmagic_XXXXXX, where XXXXXXX is an ID per ESP8266 board.

Blackmagic_A634FE1A WiFi Network

The Password for this network is "helloworld".

Upload Target Image

Note Icon Note:

This will be updated once integrated into Visual Micro as a Menu option.
  1. Ensure you have connected your target board to the PC for upload as normal
  2. Set vMicro > Debugger > Debug : Hardware
  3. Set vMicro > Debugger > Debugger : Black Magic (External)
  4. Set vMicro > Debugger > Compiler Optimization : No Project Optimization
  5. Add a Local board.txt
  6. Add Entry to File:
    tools.bmp_upload.debug.args=-nh -b 115200 -ex "target extended-remote 192.168.4.1:2022" -ex "monitor swdp_scan" -ex "attach 1" -ex "interrupt"
  7. Save and Close board.txt
  8. Build and Upload your Project to your Target board as normal

Connecting Debugger to Target

Note Icon Note:

The pinout of your boards SWD interface may differ, and ensure that it is a 3v3 line connected to VREF. You may need an adapter to breakout the SWD Pins on your target board (as shown in the below image).
ESP8266 Pin Usage
3v3 3v Pin
GND Ground Pin
GPIO0 SWDIO
GPIO2 SWCLK
Wiring ESP8266 BMP to Target Board

Now Connect both boards to a power supply and re-connect to the WiFi network....

Attach the Debugger in your Project in Visual Micro, and you should be going!

Read more about all of the other features of this ESP8266 Firmware on GitHub

If you want to connect the ESP8266 to an existing network instead of it acting as an AP, or take advantage of the OTA TFTP Updates you can make to the probe once deployed, you will need to build a custom image.

Install Build Environment

ESP RTOS SDK

Follow the guide from Espressif for sections 1.4 - 1.7, and test with 1.8.

ESP8266 RTOS SDK User Manual

Note Icon Note:

Use the Pre-Built MSYS2 Environment to make this as simple as possible

Black Magic Firmware

Follow the instructions to add the additional packages into the build environment.

Black Magic Proble Hosted on ESP-IDF

Potential Additional Packages

You may also need to install ZLIB using MINGW32, and the command pacman -S zlib-devel.

Output from pacman -S zlib-devel

Building and Uploading

Configure

Using make menuconfig you will be able to configure WiFi and GDB Pin assignments for the ESP BMP Probe:

Make Menuconfig for the ESP BMP Firmware

Build

Simply run make to build the new BIN image once you are happy with the configuration.


Upload

Use the Command output at the end of Make to upload to the board.