February 1, 2022

STM32CubeIDE Hands-on

STM32CubeIDE Hands-on

In this post, we will be introducing the official development tools offered by STMicro. It is called STM32CubeIDE and is based on Eclipse and the GNU/GCC toolchain. Eclipse is a very popular integrated development environment (IDE) among embedded developers.

STM32CubeIDE is pretty stable and supports multiple platforms (Windows, Mac and Linux). We will be walking through the setup of the Windows version (1.8.0).

Hardware Platform

In this post, we will be using an STM32L475 IoT Discovery board (B-L475E-IOT01A) as an example. You may check out more details at its product website B-L475E-IOT01A.

If you need more Flash memory, SRAM and higher CPU speed, you may consider the newer STM32L4S5 IoT Discovery board (B-L4S5I-IOT01A), which comes with a generous 2MB Flash and 640KB SRAM (compared to 1MB Flash and 128KB SRAM of the STM32L475 variation). However this board is currently out-of-stock with a long lead time.

Installation

  1. Download the installer from STM32 website: STM32CubeIDE – Integrated Development Environment for STM32 – STMicroelectronics.
    Select version 1.8.0 for Windows.
STM32CubeIDE download page
  1. Review the license agreement. After accepting it, you will be asked to login to your STM32 account to start the download. Create an account if you have not done so already.
  2. Download should automatically start. If not, click the Download button again.
  3. Unzip the downloaded file and run the installation .exe program. Follow the on-screen instruction to complete the installation. It is suggested that you keep the default installation directory (C:\ST\STM32CubeIDE_1.8.0) as we may refer to it later on. Ensure the option for “ST-LINK drivers” is checked.
STM32CubeIDE install location
STM32CubeIDE ST-LINK drivers
  1. The installed application is named STM32CubeIDE 1.8.0. On first run, your Windows firewall may prompt you to allow network access. The application requires a network port to communicate with the debugger (OpenOCD or ST-LINK GDB Server). The following screenshot shows enabling the option to allow private network access.
STM32CubeIDE workspace information center

Workspace

  1. In Eclipse, a workspace is your working environment containing one or more projects. This allows you to configure global settings shared among multiple projects. You may also quickly change your environment by switching to a different workspace. Every time when Eclipse is launched, you will be asked to select your workspace directory. By default it is set to C:\Users\<username>\STM32CubeIDE\workspace_1.8.0. It is recommended that you leave it as default. After selecting your workspace directory, click the Launch button to launch the main application window.
  2. When STM32CubeIDE is started for the first time, the main window shows the Information Center. It allows you to quickly create a new project or import an example project based on your hardware platform. In this post, we will start with a common baseline project which is already setup (available from github. See later). Go ahead to close the Information Center.

Import Project

  1. Download the baseline project from Gallium IO’s github link (https://github.com/galliumio/platform-stm32l475-disco-stm32ide.git). Here we use the STM32L475 IoT Discovery board as an example. You will find more platforms as they are added. We assume your local folder is named by default as platform-stm32l475-disco-stm32ide.
  2. Open Project Explorer by selecting from the top menu Window > Show View > Project Explorer. Click Import projects…
  1. Select General > Existing Projects into Workspace and click the Next button. Navigate to and select our example project folder (by default named as platform-stm32l475-disco-stm32ide). Click the Select Folder button.
  1. Next, you will be presented the Import Projects window. You should see the project named platform-stm32l475-disco checked in the Projects box. Leave all options as default. In particular, DO NOT check the “Copy projects into workspace” option to keep the source in the original folder.
  1. Finally, the imported project platform-stm32l475-disco appears in the Project Explorer panel. Click the > icon next to the project name to expand the project folders.

Build Project

  1. Right-click on the project name in the Project Explorer to bring up the context menu. There are a few important items here:
    • Build Project – To compile and link the source code to generate executable elf and binfiles.
    • Clean Project – To clean the project. You may run this before archiving your source folder, or to resolve any dependency issues.
    • Properties – To configure project settings such as compiler and linker flags, environment variables, etc.
    • Delete – To delete the project from the Project Explorer. Note: Make sure the option “Delete project contents on disk” is UNCHECKED if you want to keep the source folder on disk so that you can re-import the project later. This is useful when you need to switch between different source folders with the same project names.
  1. Click Build Project and you should see a message similar to the following when it is built successfully:
arm-none-eabi-objcopy  -O binary  platform-stm32l475-disco.elf  "platform-stm32l475-disco.bin"
   text    data     bss     dec     hex filename
 493916     648   81192  575756   8c90c platform-stm32l475-disco.elf
Finished building: default.size.stdout
Finished building: platform-stm32l475-disco.bin
Finished building: platform-stm32l475-disco.list
15:25:20 Build Finished. 0 errors, 41 warnings. (took 21s.476ms)

It is OK to have warnings but there should be no errors. Most of the warnings are caused by 3rd party libraries.

Debugger Setup

Under the top menu bar, there are three small icons which are used to start the debugger.

The leftmost icon is to start or configure the Debugger. The rightmost icon is to start or configure External Tools. There are a couple ways to launch the debugger and they are described in the following sections.

Built-in OpenOCD

  1. Click the down arrow next to the Debugger icon to pull down a menu. Click the “Debug Configurations…” menu item.
  2. Click STM32 Cortex-M C/C++ Application >platform-stm32l475-disco on the left side panel.
  3. The imported project should come with proper default settings. Review those settings with the following screenshots (one for each tab).
  4. Click the Debug button at the bottom-right corner to start debugging. Alternatively you may launch it via the favorite link named platform-stm32l475-disco at the top of the pull-down menu. It will take some time (<30s) to download and flash the program to the target. When it is completed successfully, you should see logs ending like these:
Info : accepting 'gdb' connection on tcp/3333
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08066e28 msp: 0x20018000
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08066e28 msp: 0x20018000
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
2000
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08066e28 msp: 0x20018000
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
Info : Padding image section 0 at 0x08000194 with 12 bytes
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08066e28 msp: 0x20018000
  1. This method is convenient since it launches OpenOCD automatically, but it may be slower since it needs to relaunch OpenOCD for each debug session.

External OpenOCD (Optional)

  1. Another way to launch a debug session is to start OpenOCD as an external tool. In order to do that, we need to first setup OpenOCD by clicking the down arrow next to the External Tools icon to pull down a menu. Click the “External Tools Configurations…” menu item.
  2. Create a new tool configuration under Program on the left side panel. Name this configuration OpenOCD STM32L4 Discovery. The key configurations are the path to the openocd.exe, path to the scripts folder and the specific board cfg file for our platform. It is assumed that you have OpenOCD installed previously. In the example below, OpenOCD has been installed under C:\Users\Public\Documents\Projects\openocd (There will be another post to show you how to install openocd and custom GNU toolchain).
  1. Click the Run button at the bottom-right corner to start OpenOCD. Alternatively you may run it via the favorite link named OpenOCD STM32L4 Discovery at the top of the pull-down menu. If it is started successfully, the console shows these log messages:
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 500 kHz
Info : STLINK V2J39M27 (API v2) VID:PID 0483:374B
Info : Target voltage: 3.246592
Info : stm32l4x.cpu: Cortex-M4 r0p1 processor detected
Info : stm32l4x.cpu: target has 6 breakpoints, 4 watchpoints
Info : starting gdb server for stm32l4x.cpu on 3333
Info : Listening on port 3333 for gdb connections
  1. Now we go back to set up our debug configuration. Click the down arrow next to the Debugger icon to pull down a menu. Click the “Debug Configurations…” menu item.
  2. Click GDB Hardware Debugging >platform-stm32l475-disco (Ext Tool) on the left side panel. Review the default settings which are similar to those in the Built-in OpenOCD section above, except for the Debugger tab shown below.
  1. Click the Debug button at the bottom-right corner to start debugging. Alternatively you may launch it via the favorite link named platform-stm32l475-disco (Ext Tool) at the top of the pull-down menu. When the program is downloaded and flashed successfully, you should see logs ending like these:
xPSR: 0x41000000 pc: 0x08015a9c msp: 0x20017f78
Info : Unable to match requested speed 500 kHz, using 480 kHz
Info : Unable to match requested speed 500 kHz, using 480 kHz
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08066e28 msp: 0x20018000
2000
Info : Unable to match requested speed 500 kHz, using 480 kHz
Info : Unable to match requested speed 500 kHz, using 480 kHz
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08066e28 msp: 0x20018000
Info : Padding image section 0 at 0x08000194 with 12 bytes
Info : Unable to match requested speed 500 kHz, using 480 kHz
Info : Unable to match requested speed 500 kHz, using 480 kHz
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08066e28 msp: 0x20018000
  1. This method is less convenient as you would need to start OpenOCD manually prior to launching a debug session. However it may be faster since OpenOCD remains running in the background across multiple debug sessions.
  2. In some cases you may need to stop OpenOCD manually. For example, when you unplug the target board while Eclipse is still running, OpenOCD will lose its connection to the target and show an error message repeatedly. To stop OpenOCD, click the Red Stop button and the Double Cross button at the top-right corner of the console window.

Run and Debug

  1. Before running our program, you should first start a terminal program on Windows, such as teratherm. Select the COM port with the name “STMicroelectronics STLink Virtual COM Port”. Click Setup > Serial port… and configure the serial port to use 115200bps N81.
  1. The Debug window should show the program stopped at the beginning of main(). In the code window, it shows SystemClock_Config() since main() calls this function immediately.:
  1. The program control toolbar is at the top left corner. Run the program by clicking the green Play/Resume button. You may suspend/break the program at any time and step into/over/out of a function, etc. Like other debugger IDE, you can set up breakpoints, inspect registers, variables and memory.
  1. As the program is running on the target, you should see its debug log in the terminal program, which looks like this:
...
*******************************
*   Console STM32L475 Disco  *
*******************************
7 CONSOLE_UART1> 205 SYSTEM(1): Prestarting IDLE_CNT_TIMER
205 SYSTEM(1): maxIdleCnt = 7494000
205 SYSTEM(1): Prestarting EXIT
205 SYSTEM(1): Starting1 ENTRY
205 NODE(15): Stopped NODE_START_REQ from SYSTEM(1) seq=6
205 NODE(15): Stopped EXIT
205 NODE(15): Starting ENTRY
205 WIFI(14): Stopped WIFI_START_REQ from NODE(15) seq=0
206 WIFI(14): Stopped EXIT
206 WIFI(14): Starting ENTRY
206 WIFI(14): Starting DONE from WIFI(14) seq=0
206 WIFI(14): Starting EXIT
...
  1. You should be able to interact with the console. Try to enter the command “fib” and see what happens. Just hit enter again to stop the command.
  2. If you want to restart the program from the beginning (without downloading again), you may click the Restart button and select “Reset init” from the pull-down menu.
  3. When you are done with a debug session, click the red Stop/Terminate button to terminate the session. You can switch back to the C/C++ perspective by clicking its button at the top-right corner. You can then start a new code > build > debug cycle.

This post was originally published on Setting up the New STM32CubeIDE Gallium IO.