pioarduino-vscode-debug

A VSCode debugger extension for PlatformIO/Arduino projects with full MI3/MI4 support.

Features

• GDB-based debugging via Machine Interface (MI) protocol
• Support for MI2, MI3, and MI4 protocol versions
• Breakpoint management (including multi-location breakpoints)
• Variable inspection and modification
• Memory viewer and editor
• CPU register inspection
• Disassembly view
• Peripheral viewer for embedded systems
• Call stack navigation
• Step debugging (step in, step over, step out)

Requirements

• VSCode: Version 1.82.0 or newer
• GDB: Version 7.0 or newer (12.0+ recommended for MI4 support)
• OpenOCD: Version 0.10.0 or newer (0.12.0+ recommended)
• PlatformIO: For Arduino/embedded development

Installation

npm install
npm run build

GDB/MI Protocol Support

This extension supports multiple versions of the GDB Machine Interface protocol:

MI2 (GDB 7.x - 8.x)

Legacy support for older GDB versions.

MI3 (GDB 9.x - 11.x)

• Enhanced multi-location breakpoint support
• Improved handling of template functions and inline code
• Better breakpoint output format

MI4 (GDB 12.x+)

• Script field as list for breakpoint commands
• Latest protocol improvements
• Recommended for new projects

The extension automatically adapts to the MI version used by your GDB instance. No configuration changes are required.

Usage

1. Open your PlatformIO/Arduino project in VSCode
2. Set breakpoints in your code
3. Start debugging (F5)
4. Use the debug toolbar to control execution

Debugging Features

• Breakpoints: Click in the gutter to set/remove breakpoints
• Conditional Breakpoints: Right-click on a breakpoint to add conditions
• Watch Variables: Add variables to the watch panel
• Memory View: Inspect memory contents at specific addresses
• Disassembly: View assembly code for your functions
• Registers: Monitor CPU register values
• Peripherals: View hardware peripheral states (embedded systems)

Configuration

The extension works with standard VSCode launch configurations. Example:

{
  "type": "gdb",
  "request": "launch",
  "name": "PlatformIO Debug",
  "executable": "${workspaceFolder}/.pio/build/target/firmware.elf",
  "target": "localhost:3333",
  "cwd": "${workspaceFolder}",
  "gdbpath": "arm-none-eabi-gdb"
}

Compatibility

Tested Platforms

• Arduino (AVR, ARM)
• ESP32 / ESP8266
• STM32 (all series)
• Raspberry Pi Pico (RP2040)
• Nordic nRF52
• Other ARM Cortex-M microcontrollers

Debug Probes

• ST-Link
• J-Link
• CMSIS-DAP
• Black Magic Probe
• USB-to-Serial adapters (for ESP32/ESP8266)

Troubleshooting

Breakpoints not working

1. Ensure your code is compiled with debug symbols (-g flag)
2. Check that GDB version is 7.0 or newer: gdb --version
3. Verify OpenOCD is running and connected to your target

Multi-location breakpoints

If you're debugging template functions or inline code and breakpoints behave unexpectedly, ensure you're using GDB 9.0+ (MI3) for proper multi-location breakpoint support.

Connection issues

1. Check that OpenOCD is running: openocd -f interface/stlink.cfg -f target/stm32f4x.cfg
2. Verify the target port (default: 3333)
3. Check firewall settings

Development

Building

npm run build

Testing

npm test

Test Coverage

npm run test:coverage

Architecture

src/
├── backend/          # GDB communication layer
│   ├── adapter.ts    # Debug adapter implementation
│   ├── mi2/          # MI protocol implementation
│   │   ├── mi2.ts    # MI command interface
│   │   └── types.ts  # MI data types
│   ├── mi_parse.ts   # MI output parser
│   └── symbols.ts    # Symbol management
├── frontend/         # VSCode UI providers
│   ├── configprovider.ts
│   ├── disassembly_*.ts
│   ├── memory_*.ts
│   ├── peripheral.ts
│   └── registers.ts
├── extension.ts      # Extension entry point
└── common.ts         # Shared utilities

Contributing

Contributions are welcome! Please ensure:

1. All tests pass: npm test
2. Code follows TypeScript best practices
3. New features include tests
4. Documentation is updated

License

See LICENSE file for details.

Changelog

Version 1.1.0

• Added MI3/MI4 protocol support
• Enhanced multi-location breakpoint handling
• Improved compatibility with GDB 9.0+ and 12.0+
• Added comprehensive breakpoint parsing tests
• Better error handling for breakpoint operations

Version 1.0.0

• Initial release
• MI2 protocol support
• Basic debugging features

References

• GDB Machine Interface Documentation
• OpenOCD Documentation
• VSCode Debug Adapter Protocol
• PlatformIO Documentation

Support

For issues and feature requests, please use the GitHub issue tracker.