Prepare and config

Debuggoid’s embeded software is a port of Black Magic Probe to the esp8266, which allows wireless debugging of blackmagic-supported ARM targets through SWD, such as Yahu.

Prepare and flash the Debuggoid

Serial connection

To flash and interact with the Debuggoid, you need a 3.3V-TTL serial port, like a 3.3V USB-UART data cable with a FTDI converter.

  1. Connect a 3.3V USB-UART data cable connected to the pins GND/TX/RX. Power can also be provided by connecting the 3.3V pin. For more details on the pinout, see the Debuggoid page.
  2. Identify the correponding port: typically /dev/ttyUSB0 or /dev/ttyACM0 on GNU/Linux, COM5 on Windows systems
  3. Power-up or Reset the Debuggoid while pressing the boot button to enable the flashing mode of the bootloader.

Getting the firmware

By download
  1. Download the latest release of the Debuggoid Firmware here (TODO)
  2. Upload firmware using one of the tools available like Esptool or Tasmotizer. Using Esptool:
    1. Install Esptool the first time, eg. under Linux sudo pip3 install esptool
    2. Identify the serial port of the 3.3V USB-UART data cable, eg. under Linux /dev/ttyUSB0
    3. Send the firmware on the serial port, eg. esptool.py --port /dev/ttyUSB0 write_flash 0x2000 debuggoid-firmware.bin
    4. Once the upload done, reset the Debuggoid by pressing the RESET button.
  3. Enjoy and start debugging!
By compilation

Using this docker image avoids the cross-compilation of the toolchain and the installation of all the tools:

  1. Install DockerCE the first time (example on Debian). On Linux, you may add the current user in the docker group
  2. Pull the docker image docker pull beetix/esp-open-rtos
  3. Clone the Debbugoid software repository using git git clone git@lab.iut-blagnac.fr:testbed/utils/debuggoid/software.git and go to this directory in the terminal
  4. Enter the docker virtual machine: docker run --rm -it --device=/dev/ttyUSB0 -v $PWD:/esp-open-rtos/examples/project beetix/esp-open-rtos /bin/bash
  5. In the virtual machine:
    1. Modify /esp-open-rtos/examples/project/src/platforms/debuggoid/private_ssid_config.h according to the WiFi configuration (SSID/WPA key)
    2. Apply the patch open_rtos_hostname.patch
      1. cd /esp-open-rtos
      2. git apply --stat examples/project/src/platforms/debuggoid/open_rtos_hostname.patch
      3. git apply --check examples/project/src/platforms/debuggoid/open_rtos_hostname.patch
      4. If no error: git apply examples/project/src/platforms/debuggoid/open_rtos_hostname.patch
    3. From the /esp-open-rtos/examples/project/src directory, run make PROBE_HOST=debuggoid flash to build and flash the Debuggoid with the firmware
  6. Enjoy and start debugging!

Interact with the Debuggoid

Format

Commands can be sent to the debuggoid via to the ESP8266’s UART.

Commands are JSON objects in the following format:

1
2
3
4
{
    "command":"cmd",
    "payload": JSON_OBJECT
}

where cmd is a command in:

  • help: print help,
  • config: debuggoid configuration,
  • reboot: reboot the module,
  • send: send ASCII payload via MQTT (typically, the node console)

The JSON string can be sent in a 1-line format, without newline chars nor indentation. The JSON string can be sent:

  • by connecting the 3.3V USB-UART data cable connected to the pins GND/TX/RX (and no target connected to the SWD port),
  • by the target connected via the SWD cable.

Configuration

The debuggoid is configured via the config command. The following JSON illustrate all the parameters available:

1
2
3
4
5
6
7
8
9
{
    "command":"config",
    "payload":{
        "ssid":"testbed",
        "pass":"WPA_password",
        "hostname":"debuggoid1",
        "broker":"broker-test.mqtt.org"
    }
}

Sending an empty payload dumps the configuration:

1
2
3
4
{
    "command":"config",
    "payload":{}
}

To change few parameters, you can limit the payload field. For example, to adjust only the wifi parameters:

1
2
3
4
5
6
7
{
    "command":"config",
    "payload":{
        "ssid":"testbed",
        "pass":"WPA_password",
    }
}

If you do not have a 3.3V USB-UART data cable, the target can be used to send a new configuration to the Debuggoid. For example, the following Arduino sketch reconfigures the MQTT broker and, then, sends text payload every seconds to test the new configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
void setup()
{
  Serial.begin(115200);
  delay(1000);
  Serial.println("{ \"command\":\"config\", \"payload\": \
                  { \"broker\":\"lab.iut-blagnac.fr\" } }");
}

void loop()
{
  Serial.println("{ \"command\":\"send\", \"payload\": \
                  { \"topic\": \"log\", \"payload\": \"toto\" } }");
  delay(1000);
}