Esp-prog debugging with vscode

I haven’t find documentation how to use esp-prog to debug esphome by setting visual breakpoints in cpp code.

Here is what I’ve done, using ubuntu 23.10 and an esp32dev:

  • Connect the esp-prog to the esp32 (see Wiring connection)

  • xtensa-esp32-elf-gdb needs libpython2.7, but it’s not packaged for ubuntu 23.10

    wget --no-check-certificate 2.7.11.tgz
    tar -xzf Python-2.7.11.tgz  
    cd Python-2.7.11
    ./configure --program-suffix=2  --enable-shared --enable-unicode=ucs4 
    sudo make install
    sudo ldconfig
  • Be sure to update platformio udev rules:

    sudo wget | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
    sudo /etc/init.d/udev restart
  • update your config/mydevice.yaml:

        debug_tool: esp-prog
        # allow color output
        monitor_filters: direct
        monitor_speed: 115200
        upload_speed: 115200
        # needed if platformio is not able to auto detect ports
        upload_port: /dev/ttyUSB0
        monitor_port: /dev/ttyUSB0
        # set initial breakpoint in main.cpp:setup
        debug_init_break: tbreak main.cpp:setup
  • Generate cpp code:

    esphome compile --only-generate config/mydevice.yaml
  • Using the same python venv as esphome, open folder config/.esphome/build/mydevice

  • Plug the esp32, then the esp-prog.
    (I think that there is a problem between udev rules and ports auto detection in platformio: so I’ve hardcoded upload_port and monitor_port in platformio_options).

You should now be able to use the debugger in vscode, setting breakpoints, and step execution line by line.

Well, this is the theory, and sometimes, something goes wrong. You can try to:

  • disconnect/reconnect usb, try '/etc/init.d/udev restart`
  • if error Target is already running an algorithm: press ‘boot’ while uploading on esp32.
  • if error Failed to communicate with the flash chip: hold on ‘rst’ on the esp-prog while uploading.

I’m not sure if my config is minimal or if my workaround when something goes wrong are correct. This Is mainly why I post here, so you can post here the way you use esp-prog!