How to debug
Below, some ways to debug:
- Arduino IDE 2 (Supported and recommended way)
- Eclipse and Sloeber
- PlatformIO
- Visual Studio and VisualGDB
- Visual Studio Code and Arduino extension
- Command line GDB
Warning
Only the Arduino IDE 2 is officially supported.
Note
Requires a ST-Link/V2 or ST-Link/V3 device connected to the PC over USB and to the board via the SWD interface.
-
If not already done, Getting-Started#Install-Arduino.cc-IDE
-
Configure the IDE to the desired board. Here the Nucleo L476RG which already includes a ST-Link.
See Getting-Started#configuring-ide
-
Open the Blink sketch from the "File> Examples > 01.Basics > Blink".
-
Select the "Optimize for debugging" in the "Sketch" menu:
- Click the upload button
See Getting-Started#upload-method to change the upload method.
- Click the start debugging button:
Tip
Refer to official documentation to see how Using the Debugger.
-
If you do not have any Eclipse package installed
Download Eclipse installer from Eclipse website , choose Eclipse IDE for C/C++ Developers and follow the installer instructions . -
If you already have an Eclipse packages (Java, Java EE, …) on your system
You can install the CDT (C/C++ Development Tooling ) plugin as follow :
- Launch "Eclipse > Help > Install New Software".
- In the “Work with” section, choose: Oxygen - http://download.eclipse.org/releases/oxygen (depending on your Eclipse packages version).
- In the “Name” box, expand “Programming Language” and choose “C/C+ Development Tools > Next > Finish”.
1.1.1. Install OpenOCD from the GNU MCU Eclipse plug-ins
The GNU MCU Eclipse plug-ins provide multiple tools based on the GNU toolchains to ease project development. To use Eclipse debugging features, it is necessary to download OpenOCD, an open source software that provides debugging and in-system programming for embedded device.
Launch Eclipse, go to “Help > Eclipse Marketplace” and search for the "GNU MCU plug-in".
In the tree view, expand “GNU MCU Eclipse {version}” and uncheck all items. In previous versions, you had to choose the OpenOCD entry. Since there is no such entry, you cannot select it. OpenOCD will automatically be installed. Confirm and follow the recommended instructions. Then restart Eclipse.
To finish the OpenOCD plug-in configuration, and for a simpler integration, install OpenOCD binaries by following the “How to install the OpenOCD binaries” tutorial. This Guide will tell you to extract the openocd binaries to a specific path (Windows).
From the Eclipse main tab, go to “Help > Eclipse Marketplace” and search for Sloeber.
Download the "Sloeber plugin" , follow the recommended instructions and restart Eclipse.
By now, the main tab should look like the following:
Open “Arduino > Preferences”.
In the tree view that pops up, go to “Arduino > Third party index url’s” and add the STM32 support package URL:
Hit “Apply and Close” then re-open the “Arduino > Preferences” menu. The STM32 Core is now available in the “Platforms and Boards” menu.
Select the latest core version and hit “Apply and Close”.
Tip
Make sure your board is correctly connected before go any further.
There is multiple options to start a new project.
--> Option A: From the “Arduino“ menu, click on “New Sketch”.
--> Option B: Click on the new sketch icon directly from the toolbar.
--> Option C: From the “File > New > Project…” click on “Arduino New Sketch”.
Regardless of the chosen method, set your “Project name” and the “Location” of your project. Then, push the “Next” button. Complete the Arduino required information (board type, port number …) form and click “Next”.
Do not forget to select the “Platform folder” that corresponding to the STM32 Core version previously installed.
Note
If you plan to debug, select "Debug (-g)" from the "Optimize" list else you will not have debugging symbols.
From there, you can create your own sketch or use pre-configured examples.
In this case, we will try the “Blink” example.
From the “select code” bar, apply “Sample sketch” and then choose “Examples > 01.Basics > Blink” and “Finish”.
Note
As the GCC ARM Toolchain is provided by the STM32 core, you do not have to download it in order to program your board.
Use the “Arduino” menu or the upload button on the toolbar to upload your sketch. If the setup is correct, the LED should blink on your board.
First, make sure your board can work with STLink. The debugger support is currently fully tested with the board supported by the STM32Core (Full list on Supported boards section).
Two standard tools are required in order to debug the code:
- GDB, the GNU Debugger. The STM32 core provides a GDB executable. This executable is located in the arm-none-eabi-gcc binaires folder in your STM32 core package. The path should look like this one:
<Eclipse installation path>\eclipse\arduinoPlugin\packages\STM32\tools\arm-none-eabi-gcc\6-2017-q2-update\bin\arm-none-eabi-gdb.exe
- OpenOCD, installed in 1.1.1 section.
Important
Make sure these tools are correctly installed on your platform before proceeding any further.
Important
Do not forget to select "Debug (-g)" to the "Optimize" list in the "Arduino Board Selection" of your project else you will not have debugging symbols.
If you are using sloeber directly, not CDT with the plugin. The you probably will not find the below mentioned menu "Debug Configurations" under "Run". This is, because you are in the arduino view. In this view, all "unnecessary" menus are hidden. To overcome this, you can change the view:
You can choose the regular C/C++ view. Alternatively you can also reach the debug configurations menu by right-click on your project under the arduino view.
From the “Run” menu, select “Debug Configurations”. Double-click on “GDB OpenOCD Debugging” to create a new configuration and set the configuration name.
Move to the “Debugger” tab in order to configure OpenOCD and GDB.
- First, set the OpenOCD executable path. If OpenOCD was installed following the recommended instructions from the GNU MCU plug-in installation guide (see section 1.1.1), Eclipse should auto detect the latest version of OpenOCD and you should be able to use global variable to define your path. Your executable path should look like this one :
${openocd_path}/${openocd_executable}
The “Actual executable” field show the full executable path.
-
Set the “GDB port” to 3333 , the “Telnet port” to 4444 and the “Tcl port” to 6666.
-
Finally, set the debugger configuration in the “Config options” field; specify the script path folder and configuration files (.cfg) related to your MCU. In this case, we use a Nucleo F030R8, so the configuration arguments are :
-s "${openocd_path}/../scripts" -f interface/stlink-v2-1.cfg -f target/stm32f0x.cfg
Important
Do not forget to replace the config files with the version of the board you are using.
In the “Debugger” tab, scroll to the GDB Client setup field.
- Set the “Executable name” field to the path of the arm-none-eabi-gdb executable by adding:
${A.COMPILER.PATH}/arm-none-eabi-gdb
By now, the “Debugger” tab should look like the following:
Move to the “Startup” tab, scroll until the “Run/Restart Commands” fields and add:
monitor reset halt
monitor reset init
Then go to the “Common” tab and check “Debug” and “Run” in the “Display in favorites menu”. Finally, click on “Apply” and “Close”.
Launch the debug session from the “Debug” or “Run” button in the toolbar.
If the configuration process runs correctly, you will be able to see the debug capabilities of the chip in the Debug console (number of breakpoints, watchpoints, …).
If you are facing problems with messages like "binary not found" you should try to click on the drop down menu and then on your configuration instead of just click on the debug icon.
Now, you can easily debug your code by using the Eclipse debug features including running step-by-step mode, live breakpoint, inspecting memory access, live view of variable contents and many more.
PlatformIO is an open source ecosystem for IoT development. Cross-platform IDE and unified debugger. Remote unit testing and firmware updates.
It's built on top of GitHub's Atom and Microsoft's Visual Studio Code – free, open source, and MIT licensed editors
It now supports the STM32Duino core:
https://docs.platformio.org/en/latest/platforms/ststm32.html#configuration
This tutorial shows how to develop Arduino-based projects for the STM32 boards using the Arduino_Core_STM32, Visual Studio and VisualGDB.
See the Visual Studio Code extension for Arduino README.md.
- Linux, tested in Ubuntu 18.04
- Requires Arduino IDE with stm32duino installed
- STLink compatible dongle
- assuming Blue Pill board, but it probably work with any other STM32 board
- In the Arduino IDE, go to menu File->Preferences and check compilation verbose
- Open your code, for example, the blink code
- In the Arduino IDE, go to Tools->Optimize->Debug. This will include -g in the compilation process, including debug symbols
- Connect the stlink probe to the board and the computer. I am assuming stlink driver is already installed. If it is the first time you are using the Stlink dongle, it might be necessary to update the dongle's firmware.
- Compile and upload in the Arduino IDE. If the compilation is successful, you will see something like this in the Arduino IDE console window.
/home/lsa/.arduino15/packages/STM32/tools/xpack-arm-none-eabi-gcc/9.2.1-1.1/bin/arm-none-eabi-size -A /tmp/arduino_build_742171/Blink-stm32.ino.elf
Sketch uses 9816 bytes (14%) of program storage space. Maximum is 65536 bytes.
Global variables use 588 bytes (2%) of dynamic memory, leaving 19892 bytes for local variables. Maximum is 20480 bytes.
-------------------------------------------------------------------
STM32CubeProgrammer v2.2.1
-------------------------------------------------------------------
ST-LINK SN : 3B1108013212374D434B4E00
ST-LINK FW : V2J35S7
Voltage : 3,18V
SWD freq : 4000 KHz
Connect mode: Under Reset
Reset mode : Hardware reset
Device ID : 0x410
Device name : STM32F101/F102/F103 Medium-density
Flash size : 64 KBytes
Device type : MCU
Device CPU : Cortex-M3
Memory Programming ...
Opening and parsing file: Blink-stm32.ino.bin
File : Blink-stm32.ino.bin
Size : 10104 Bytes
Address : 0x08000000
Erasing memory corresponding to segment 0:
Erasing internal memory sectors [0 9]
Download in Progress:
File download complete
Time elapsed during download operation: 00:00:00.614
RUNNING Program ...
Address: : 0x8000000
Application is running
Start operation achieved successfully
- Open a terminal and run
st-infoto start gdbserver - Open another terminal and run
~/.arduino15/packages/STM32/tools/xpack-arm-none-eabi-gcc/9.2.1-1.1/bin/arm-none-eabi-gdb /tmp/arduino_build_742171/Blink-stm32.ino.elfto run the gdb used by stm32duino. Note that the path to the ELF file was figure out in the compilation messages in the Arduino IDE, shown in the previous section. - Now in the GDB console, run the following commands:
target remote localhost:4242
# it adds breakpoint to the setup and loop functions
b setup
b loop
# it runs until it reaches the setup and show the code
c
l
# it runs until it reaches the loop and show the code
c
l
# sets break point to line 37, in the middle of the toggle loop
b 37
# see the led blinking every time you continue
c
c
c
c
c
- It is also possible to debug with GUI, such as
ddd. It requires software installation with the commandsudo apt-get install -y ddd. - To run
ddd, open a terminal and typeddd --debugger ~/.arduino15/packages/STM32/tools/xpack-arm-none-eabi-gcc/9.2.1-1.1/bin/arm-none-eabi-gdb /tmp/arduino_build_742171/Blink-stm32.ino.elf.
Note
Check to point to the appropriate gdb and ELF file.