:orphan: .. _microchip-mplab-vscode-debugging: 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. .. code-block:: console 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: .. zephyr-app-commands:: :zephyr-app: samples/basic/blinky :board: :goals: build After a successful build, the Zephyr ELF file is available at: .. code-block:: console 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: .. code-block:: console .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. .. code-block:: json { "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: .. code-block:: json "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: .. code-block:: json { "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: - `MPLAB® Extension for Visual Studio Code`_ - `Microchip Developer Help`_ - `Microchip Packs Repository`_ - `pycmsisdapswitcher`_ .. _MPLAB® Extension for Visual Studio Code: https://marketplace.visualstudio.com/items?itemName=microchip.mplab-core-da .. _Microchip Packs Repository: https://packs.download.microchip.com/ .. _pycmsisdapswitcher: https://pypi.org/project/pycmsisdapswitcher/ .. _Microchip Developer Help: https://developerhelp.microchip.com/ .. _Visual Studio Code: https://code.visualstudio.com/