Microchip MPLAB VS Code Debugging

Microchip devices can be debugged from Visual Studio Code using the MPLAB® Extension for Visual Studio Code. The extension provides integration with Microchip debug tools and allows applications to be launched and debugged directly from VS Code.

This section describes how to configure VS Code debugging for a Microchip target using the MPLAB debugger extension and a launch.json configuration.

Typical supported debug tools include:

MPLAB PICkit™ debuggers/programmers
MPLAB SNAP debuggers
MPLAB ICD debuggers
On-board debuggers available on selected Microchip development boards

The exact list of supported devices and tools depends on the installed MPLAB extension, Microchip tool packs, and device family packs.

Requirements

Before starting a debug session, install and configure the following tools:

Visual Studio Code
MPLAB® Extension for Visual Studio Code
Required Microchip device packs
A supported Microchip debug probe or on-board debugger
A firmware image built with debug information enabled

The ELF file generated by the build system is used for source-level debugging.

build/zephyr/zephyr.elf

Installing the MPLAB Extension

To install the MPLAB extension:

Open Visual Studio Code.
Open the Extensions view.
Search for MPLAB.
Install the official Microchip MPLAB extension.
Restart VS Code if required.

After installation, verify that the extension can detect the required Microchip debug tools and device support packs.

Building a Zephyr Application

Build the Zephyr application before starting the debug session.

Example:

# From the root of the zephyr repository
west build -b <board> samples/basic/blinky

After a successful build, the Zephyr ELF file is available at:

build/zephyr/zephyr.elf

This ELF file should be referenced by the program field in .vscode/launch.json.

VS Code Debug Configuration

VS Code debug configurations are stored in the following file:

.vscode/launch.json

The MPLAB extension uses the mplab-core-da debug adapter type.

The following launch.json configuration is provided as an example. The exact configuration may vary by board. To use the correct launch.json for a specific board, refer to the documentation page for that board.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "MPLAB Debug Zephyr : pic32cm_jh01_cpro",
      "type": "mplab-core-da",
      "request": "launch",
      "program": "${workspaceFolder}/zephyr/build/zephyr/zephyr.elf",
      "tool": "${command:pickTool}",
      "stopOnEntry": true,
      "device": "PIC32CM5164JH01100"
    }
  ]
}

The tool field uses the following command:

"tool": "${command:pickTool}"

This allows the MPLAB extension to prompt for the connected debug tool when the debug session starts.

Using a Specific Debug Tool Serial Number

If more than one compatible debug tool is connected, a specific probe can be selected by adding the serial field to the configuration.

Example:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "MPLAB Debug Zephyr : pic32cm_jh01_cpro",
      "type": "mplab-core-da",
      "request": "launch",
      "program": "${workspaceFolder}/zephyr/build/zephyr/zephyr.elf",
      "tool": "${command:pickTool}",
      "stopOnEntry": true,
      "device": "PIC32CM5164JH01100",
      "serial": "020107402RYN000062"
    }
  ]
}

Note

The serial value must match the serial number of the connected Microchip debug probe. If only one debug tool is connected, this field is usually not required. The serial number can be found by entering the command MPLAB: List connected tools in the VS Code command palette.

Configuration Fields

The main fields in the debug configuration are:

name: Display name shown in the VS Code Run and Debug view.
type: Debug adapter type used by the MPLAB extension. For MPLAB core debugging, use mplab-core-da.
request: Debug request type. Use launch to start a new debug session.
program: Path to the ELF file to debug. This is typically ${workspaceFolder}/zephyr/build/zephyr/zephyr.elf. This can also be replaced with an absolute path.
device: Target Microchip device name. For example, PIC32CM5164JH01100.
tool: Debug tool selection. ${command:pickTool} lets the MPLAB extension prompt for the connected debug tool.
stopOnEntry: If set to true, execution stops at the program entry point when the debug session starts.
serial: Optional debug tool serial number. This is useful when multiple debug probes are connected.

Starting a Debug Session

To start debugging:

Connect the Microchip debug probe to the target board.
Power the target board.
Open the Zephyr workspace in VS Code.
Build the application.
Confirm that the ELF file exists.
To start the debugging, In menu bar, Run -> Start Debugging (F5)
For further debugging, use the debug toolbar to perform actions such as Continue, Step Over, Step Into etc, as needed.

Note

If multiple debug configurations are defined in launch.json, the desired configuration can be selected from the drop-down menu in the Run and Debug view in the VS Code side toolbar.

When the session starts, the MPLAB extension prompts the user to select a connected debug tool. After the tool is selected, the extension connects to it, loads the ELF file, and starts the debugger.

During debugging, VS Code can be used to:

Set and clear breakpoints
Step through source code
Continue and pause execution
Inspect local and global variables
View call stacks
Watch expressions
Inspect registers, depending on extension support

Troubleshooting

Debugger Tool Is Not Detected

If the debug tool is not detected:

Check the USB connection.
Make sure the debug probe is supported by the MPLAB extension.
Verify that the probe firmware is up to date.
Disconnect and reconnect the probe.
Restart VS Code.
Ensure no other application is using the debug tool.

Device Is Not Recognized

If the device is not recognized:

Verify that the device field matches the exact Microchip device name.
Install or update the required Microchip device pack.
Confirm that the target board is powered.
Check the debug connector and wiring.
Verify that the selected probe supports the target device.

ELF File Is Not Found

If the debug session cannot find the program file:

Confirm that the Zephyr application was built successfully.
Check that build/zephyr/zephyr.elf exists.
Update the program path in launch.json.
Prefer ${workspaceFolder}/zephyrproject/zephyr/build/zephyr/zephyr.elf for portable projects.

Breakpoints Are Not Hit

If breakpoints are not hit:

Ensure the application was built with debug symbols.
Rebuild the application after changing source files.
Make sure the source tree matches the ELF file being debugged.
Reduce compiler optimization if source-level debugging is unreliable.
Confirm that the target was programmed with the expected firmware image.

Debugger Mode

Microchip debug tools, including on-board debuggers on supported development boards and external debug probes such as MPLAB SNAP and MPLAB ICD, are shipped in MPLAB mode by default. If the debugger has been switched to CMSIS-DAP v2 mode using the pycmsisdapswitcher utility, the MPLAB debug adapter cannot detect the tool. Restore the debugger to MPLAB mode and reconnect the tool.

Additional Documentation

For more information, see: