Debugging ESP32-C3 with PlatformIO and VS Code on macOS

TL;DR

Add the following to platformio.ini:

debug_tool = esp-builtin

This guide covers how to set up PlatformIO to debug your ESP32-C3 project using C/C++ in VS Code on macOS, with breakpoints and variable inspection. Additionally, it provides steps to verify and install necessary drivers (FTDI, CH340, or CP210x) required for the ESP32-C3 to be recognized.

Prerequisites

macOS with VS Code and PlatformIO extension installed.
ESP32-C3 development board connected via USB.
FTDI, CH340, or CP210x drivers installed (depending on the board).
A C/C++ project already set up with PlatformIO.

Step 1: Check if Drivers are Installed on macOS

The ESP32-C3 board often requires drivers for the USB-to-serial chip used by the board (FTDI, CH340, or CP210x). Follow these steps to check if the drivers are installed on macOS:

Open Terminal on macOS.
List USB devices connected to your system using the following command:
```
ioreg -p IOUSB -l | grep -E "FTDI|CH340|CP210"
```
If the correct driver is installed, you’ll see an entry related to your board, such as:
- FTDI: "FT232R USB UART"
- CH340: "USB-Serial Controller D"
- CP210x: "CP2102 USB to UART Bridge Controller"

If no output appears or your board isn’t listed, you may need to install the appropriate driver.

Step 2: Install Drivers (If Necessary)

If your ESP32-C3 board’s USB-to-serial chip isn’t detected, download and install the appropriate driver:

FTDI Driver:
- Download: FTDI VCP Drivers
- Install and reboot your Mac.
CH340 Driver:
- Download: CH340 macOS Driver
- Install and reboot.
CP210x Driver:
- Download: CP210x macOS Driver
- Install and reboot.

After installation, reconnect the ESP32-C3 board and run the ioreg command again to confirm the device is detected.

Step 3: Verify Device Connectivity

After ensuring the drivers are installed:

Reconnect the ESP32-C3 board to your Mac via USB.
Open VS Code and in the terminal, type:
```
pio device list  
```
Confirm that the ESP32-C3 is listed with a serial port similar to /dev/cu.usbserial-XXXXX.

Step 4: Configure `platform.ini`

Below is an example platform.ini configuration for debugging:

[env:esp32-c3]  
platform = espressif32  
board = esp32-c3-devkitm-1  
framework = espidf   ; Or 'arduino' if using Arduino libraries  
monitor_speed = 115200  

; Debugging configuration  
debug_tool = esp-builtin  
debug_init_break = tbreak app_main  

; Upload configuration  
upload_port = /dev/cu.usbserial-XXXXX  
upload_speed = 921600  

; Optional: GDB logging for troubleshooting  
debug_log = yes  
debug_speed = 115200

Step 5: Start a Debugging Session

Open your project folder in VS Code.
Set breakpoints by clicking next to the line numbers in your code.
Click on the Run and Debug tab (bug icon) and select PlatformIO Debug.
Press F5 or click Start Debugging.

PlatformIO will compile, upload the code, and launch the debugger. It will pause at the first breakpoint (or app_main if specified).

Step 6: Debugging Features

Breakpoints: Execution pauses at your breakpoints.
Step Controls:
- F10: Step over
- F11: Step into
- Shift + F11: Step out
- F5: Continue execution
Variables and Watch Panels: Inspect and monitor variables at runtime.
Call Stack: Track the flow of function calls.

Troubleshooting

Issue: Board Not Detected

Verify drivers are installed and the correct serial port is listed with pio device list.
Press the BOOT button on the board during upload if there are connection issues.

Issue: Breakpoints Not Working

Ensure debug_tool = esp-builtin is set in platform.ini.
Check if debug_init_break points to the correct function (app_main() for ESP-IDF).
Lower the upload_speed if uploads are unstable.

Conclusion

By following this guide, you should now be able to:

Set up PlatformIO to debug your ESP32-C3 project using C/C++ in VS Code on macOS.
Verify and install necessary drivers (FTDI, CH340, or CP210x) for USB connectivity.
Successfully use breakpoints, inspect variables, and step through code during debugging.

This configuration ensures smooth debugging with PlatformIO, allowing you to identify and resolve issues effectively.

brennanMKE/README.md