Written by Abhijit Bose, an Embedded, Analog and Hardware Engineer and new member of the Zephyr community
This blog originally ran on Abhijit’s personal website. For more content like this, click here.
In this blog, we are going to look at an example of Blinky running on STM32F3DISCOVERY Board and debugging on the Zephyr RTOS – all while using Manjaro (Arch Linux).
This is Part 2 in the series of post on Zephyr OS. In Part 1 ,we saw how to setup the development environment. In Part 3, we will look at how to get started with Application Development on Zephyr OS using our custom blinky projects on STM32F3 Discovery Board .
1. Quick look at STM32F3DISCOVERY Board
This board host the STM32F303VCT6 Microcontroller.
This board has a built in ST-LINK/V2 or ST-LINK/V2-B embedded debug tool. The distinction can be done based on the board color. If the color is Green – it’s the older board with ST-LINK/V2. Then, if the color is Blue – this is the latest one and has ST-LINK/V2-B. This information would become relevant while performing debugging. It took me a while to figure this. Due to which much time was lost.
Here are some of the features of this board:
- STM32F303VCT6 microcontroller featuring 256‑Kbyte Flash memory and 48‑Kbyte RAM in an LQFP100 package
- USB Full Speed Support
- ST MEMS motion sensor, 3-axis digital output gyroscope L3GD20H
- ST MEMS system-in-package featuring a 3D digital linear acceleration sensor and a 3D digital magnetic sensor LSM303DLHC
- Ten LEDs:
- LD1 (red) for 3.3 V power on
- LD2 (red/green) for USB communication
- Eight user LEDs: LD3/10 (red), LD4/9 (blue), LD5/8 (orange) and LD6/7 (green)
- 1 user and reset push-buttons
- Board connectors:
- USB FS Mini-B connector
- ST-LINK Mini-B USB connector
- Extension header for all LQFP100 I/Os for quick connection to prototype board and easy probing
- Flexible power-supply options:
- ST-LINK USB connector or USB FS connector
- External 3 V or 5 V supply voltage
- On-board debugger/programmer ST-LINK/V2 for PCB version A or B, or ST-LINK/V2-B for PCB version C and newer:
- Debug port
- Mass storage and Virtual COM port with ST-LINK/V2-B only
From ST Microelectronics (STM32F3DISCOVERY) website
I have the latest STM32F3DISCOVERY Board with PCB version C hence the ST-LINK/V2-B.
1.a. Zephyr OS support for STM32F3DISCOVERY Board
This board is officially supported by Zephyr OS.https://docs.zephyrproject.org/latest/boards/arm/stm32f3_disco/doc/index.html
Hence all drivers and device computability are well built in.
This was the reason I selected this particular board. Though old, this board has lots of peripherals and interesting pieces to demonstrate under Zephyr OS.
1.b. To Buy STM32F3DISCOVERY Board in भारत (India)
Well there are several ways to buy this board. The easiest would be via a distributor.https://www.semikart.com/search/STM32F3DISCOVERY
I have used https://www.semikart.com in the past. Hence, got this board from them. They might need number of follow-ups, but they do deliver this board safely.
2. cmake Generators and version
The Zephyr OS environment uses the newer version of cmake. Hence, they have a round about way to fix this in ubuntu. In our case Manjaro (Arch Linux) has much newer versions than debian or ubuntu. So the fuss about cmake is not a problem here.
A CMake Generator is responsible for writing the input files for a native build system. Exactly one of the CMake Generators must be selected for a build tree to determine what native build system is to be used.
From CMake Documentation
We would use – Ninja https://cmake.org/cmake/help/latest/generator/Ninja.html for building firmware.
Which is the preferred default generator to use for Zephyr OS.
And for IDE we would be using Eclipse specifically –Eclipse CDT4 https://cmake.org/cmake/help/latest/generator/Eclipse%20CDT4.html
In short our string for Generator Command would be :
cmake -G"Eclipse CDT4 - Ninja"
3. Setting up Eclipse
Though I like the VS Code IDE there is no target support as explained in the earlier section.
I have used Eclipse Embedded CDT in the past for some embedded projects. It is well supported for Embedded Development using additional plugins. It stands of Eclipse C/C++ Development Tooling or CDT for short.
We would be using the GNU MCU Eclipse plugin. This plugin would help with Hardware Debugging in Eclipse CDT.
3.a Download the Eclipse CDT Edition
Eclipse Foundation has a separate location for diffrent versions/packs:https://www.eclipse.org/downloads/packages/
Download the Eclipse IDE for C/C++ Developers (includes Incubating components) package. In our case the OS is Linux X64 hence:https://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/2020-03/R/eclipse-cpp-2020-03-R-incubation-linux-gtk-x86_64.tar.gz
After downloading extract the file – it should generate eclipse folder.
The contained eclipse file in this folder is the Eclipse CDT executable.
3.b Set Workspace in Eclipse CDT
Remember last time we created the Workspace this would become useful now.
Just replace the <User Name> with your Linux User Name. One can lookup their User Name by the command whoami.
Close the Welcome screen that pop-ups. You should have this environment:
3.c Install the GNU MCU Eclipse in Eclipse CDT
In order to install we would need to open the Help => Eclipse Marketplace... menu.
Select the GNU MCU Eclipse by entering the the Find Box and pressing Go.
Click on Install button to begin installing.
In the next screen make the selection only for Debugging support. We don’t need project templates. We would be using cmake to generate the projects.
Click on Confirm > to begin the installation.
Next accept the License Agreement by selecting the option.
Click on Finish to complete.
There would be a short warning of sorts just select Install anyway.
Finally the Eclipse IDE would request to restart – Restart Now. It should start the IDE again.
4. Getting the Blinky example for STM32F3DISCOVERY Board
We are now ready with our Eclipse CDT and debugging plugin.
It’s time let’s setup the first blinky project for STM32F3DISCOVERY Board.
Fortunately the Zephyr OS already has the project sources for us. Let’s get it to our Workspace directory.
1 2 3 4 5 6 7 8 9 10 11 | # Go the Workspace cd ${HOME}/Workspace # Run the Environment Configuration script source ${HOME}/Workspace/env.sh # Copy the example from inside the 'zephyr' main folder cp -aT ${HOME}/Workspace/zephyr/samples/basic/blinky ./01_blinky # Create the Build Directory mkdir ${HOME}/Workspace/01_blinky_build_STM32F3DISCOVERY |
We should now have the blinky example copied in the 01_blinly directory in our Workspace.
The last step of creating the build directory helps to bind things for cmake. It’s like <Project Name>_build_<Board Name>.
5. Perform cmake based project generation of Blinky example
We talked about the "Eclipse CDT4 - Ninja" earlier for cmake Generators. It’s time to make use of that.
1 2 3 4 5 | # Go the Build directory cd ${HOME}/Workspace/01_blinky_build_STM32F3DISCOVERY # Initiate the cmake command for STM32F3DISCOVERY Board using Eclipse CDT with Ninja tool cmake -G "Eclipse CDT4 - Ninja" -DBOARD=stm32f3_disco ${HOME}/Workspace/01_blinky |
If everything work you should get the message
-- Build files have been written to: /home/<User Name>/Workspace/01_blinky_build_STM32F3DISCOVERY
In case you don’t see this message then possibly you might have missed some step. Go through the environment setup explained in Part 1 in the series.
6. Import Blinky project in Eclipse CDT IDE
Let’s now actually see the whole project in Eclipse CDT.
Note: The project files of Eclipse CDT are stored in the${HOME}/Workspace/01_blinky_build_STM32F3DISCOVERY directory
not the source directory ${HOME}/Workspace/01_blinky.
In Eclipse CDT window select File => Import....
Select under General => Existing Projects into Workspace and
click Next >.
Using Browse... button locate the 01_blinky_build_STM32F3DISCOVERY directory.
Eclipse CDT would automatically detect the project. Just click on Finish to complete the project import.
Browse the [Source Directory] in the project to find the actual sources.
7. Build the Blinky Example from Eclipse CDT and command prompt
In case of Eclipse CDT just click on the hammer icon to Build the current project.
On command line:
1 2 3 4 5 6 7 8 9 10 11 12 | # Go the Build directory cd ${HOME}/Workspace/01_blinky_build_STM32F3DISCOVERY # We use 'west' tool to clean up the last build west build -t clean # We use the 'west' tool from Zephyr OS west build # Or we can also use Ninja ninja clean ninja |
This should show some output like
[1/124] Preparing syscall dependency handling
[119/124] Linking C executable zephyr/zephyr_prebuilt.elf
Memory region Used Size Region Size %age Used
FLASH: 12268 B 256 KB 4.68%
SRAM: 4184 B 40 KB 10.21%
IDT_LIST: 120 B 2 KB 5.86%
[124/124] Linking C executable zephyr/zephyr.elf
Well for a blinky the space used might look overkill. But, for more complex examples the benefits of Zephyr OS will become clear.
8. Flashing the Blinky example in STM32F3DISCOVERY Board
Before doing this step:
- STM32F3DISCOVERY Board must be plugged in from the USB ST-LINK marked USB Mini-B connector
- The blinky project must have been built once.
1 2 3 4 5 | # Go the Build directory cd ${HOME}/Workspace/01_blinky_build_STM32F3DISCOVERY # Flashing command using 'west' tool in Zephyr OS west flash |
This command won’t work for newer STM32F3DISCOVERY Board
Remember the discussion earlier about STM32F3DISCOVERY Board with PCB version C and ST-LINK/V2-B. It’s time use that info in case you face the similar problem.
1 2 3 4 5 6 7 8 | # Go the Build directory cd ${HOME}/Workspace/01_blinky_build_STM32F3DISCOVERY # Direct flashing command using 'openocd' openocd -s /usr/share/openocd/scripts \ -f interface/stlink-v2-1.cfg \ -f target/stm32f3x.cfg \ -c "program zephyr/zephyr.bin verify reset exit 0x08000000" |
Note: The Hex files and bin files for the project are stored in the ${HOME}/Workspace/01_blinky_build_STM32F3DISCOVERY/zephyr directory. If you ever need to manually upload to the board or keep backup just use them. More details about this in Zephyr Project Documentation .
Note: The location 0x08000000 in the start location of flash in the STM32 Microcontroller.
9. Creating Debug configuration in Eclipse CDT for Blinky example
In order to have better debugging we need to enable CONFIG_DEBUG option. More details on this in Zephyr Project Documentation .
9.a Create a copy of the original Blinky example and update it
Let’s create a copy of our Blinky project to begin.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | # Go the Workspace cd ${HOME}/Workspace # Run the Environment Configuration script source ${HOME}/Workspace/env.sh # Copy the example from inside the 'zephyr' main folder cp -aT ${HOME}/Workspace/zephyr/samples/basic/blinky ./02_blinky_debug # Create the Build Directory mkdir ${HOME}/Workspace/02_blinky_debugbuild_STM32F3DISCOVERY # Append the config file with 'CONFIG_DEBUG' option echo "CONFIG_DEBUG=y" >> ${HOME}/Workspace/02_blinky_debug/prj.conf # Go to the Build directory cd ${HOME}/Workspace/02_blinky_debugbuild_STM32F3DISCOVERY # Generate the Eclipse CDT files cmake -G "Eclipse CDT4 - Ninja" -DBOARD=stm32f3_disco ${HOME}/Workspace/02_blinky_debug |
Finally import the project in Eclipse CDT using method explained earlier. Only this time selecting the 02_blinky_debugbuild_STM32F3DISCOVERY directory.
9.b Create Blinky Example Debug Configuration in Eclipse CDT for STM32F3DISCOVERY Board
Make sure before you do anything the build of the new project is successful.
By default we only get a build configuration. There is no Debug Configuration in Eclipse CDT. Let’s use the GNU MCU Eclipse plugin to achieve this.
In Eclipse CDT select Run => Debug Configurations...
In the Debug Configuration window double click on the GDB OpenOCD Debugging option.
Set the Name correctly to 02_blinky STM32F3DISCOVERY Debug Configuration.
And select zephyr/zephyr.elf the correct C\C++ Application using Search Project... Button.
Next we look at the Debugger Tab. In the OpenOCD Setup section change the Executable Path to actual one – /usr/bin/openocd.
And in the Config Options: area add the correct options as per your board:
- For Older Green Board ST-LINK/V2 / PCB version A or B :
-s /usr/share/openocd/scripts
-f board/stm32f3discovery.cfg
- For Newer Blue Board ST-LINK/V2-B / PCB version C and newer :
-s /usr/share/openocd/scripts
-f interface/stlink-v2-1.cfg
-f target/stm32f3x.cfg
In the GDB Client Setup section change the Executable Name to actual one – /usr/bin/arm-none-eabi-gdb
Next in the Common Tab select the Shared file: option.
Click Apply button to save the configuration.
9.c Debugging the Blinky example on STM32F3DISCOVERY Board using Eclipse CDT IDE
Finally click on Debug to begin the debugging operation in Debug Configuration window. Or use the Bug Icon on Top right to start debugging.
For the first time you might be asked permission to switch into the Debug perspective. Just click Switch and check Remember my decision.
The execution would stop just below void main(void) :
Set a break point at the line gpio_pin_set(dev, PIN, (int)led_is_on);.
Press Resume button or F8 Key to begin debugging press.
Every time you press F8 Key the LED 6 on STM32F3DISCOVERY Board should blink.
Note: There is a delay k_msleep(SLEEP_TIME_MS); which is initially 1000ms or 1 second. Hence don’t press F8 or Resume button too frequently.
You can change the delay SLEEP_TIME_MS specified in the main.c file to see the difference in blinking.
10. Success At last !
Yes, now you have a working debug setup for Blinky Example running using Zephyr OS on STM32F3DISCOVERY Board. It look me quite a while to figure out the things and iron out issues.
In fact this post has crossed the 500 line marker.
Hope that this article helps you in getting started with Zephyr OS. If you have any confusion about the development environment, have a look at Part 1 in the series.
