In this article we are going to set-up a ready-to-use Eclipse-based toolchain named ChibiStudio for the development on STM32. We will also explore this development toolchain explaining some basic operations necessary for daily development. So we will introduce the ChibiOS project, we will setup ChibiStudio taking a tour of some parts of it, we will import some ready to use projects and perform our first flash and run. Note that to proceed with this tutorial is necessary the installation of ST-Link drivers: this procedure has been shown in the previous article From 0 to STM32.
Notes about programming language
We are going to use C.
The ChibiOS project
Until now we have referred to ChibiOS as an Embedded Library and this is the most simplistic and general way to qualify it. To be more specific, ChibiOS stand for Small Operating System (Chibi is a Japanese word which means small) but today it is much more than an OS.
History in brief
ChibiOS (formerly ChibiOS/RT) is a project born in the 80s and published on Sourceforge in 2007 by my mentor and friend Giovanni Di Sirio. In the beginning the project was named ChibiOS/RT because it was basically a Real Time Operating System (or RTOS). After some months of development, the project starts to include a set of device drivers for testing purposes.
Growing up, the device drivers branch became self-consistent. It was splitted from RT and named as HAL. Prior the version 3.0.0, the HAL an the RT were joint together and interdependent. Starting from 3.0.0, the two parts have been separated and interconnected through an Operating System Abstraction Layer (also known as OSAL) in this way HAL became able to run independently from the underlying Operating System.
The ChibiOS project has now a portfolio of four software products which could be used separately or joint-together. It now counts two different kernels : the first is RT and now the name ChibiOS/RT refers to RT only; the second one is another OS which could be considered a subset of RT designed to be the smallest RTOS ever and is named ChibiOS/NIL).
The HAL, the hardware abstraction layer, has been renamed as ChibiOS/HAL. Starting from the latest version, ChibiOS include also a new set of complex drivers: it’s name is ChibiOS/EX and stands for external peripherals. We will properly describe all these products as we start to use them. For this tutorial we are going to use some demos based on ChibiOS/RT + ChibiOS/HAL.
Here a collection of useful links related to ChibiOS. We will deepen them later but right now is good to have all the quick references grouped in the same place:
- ChibiOS project has an Official Website (chibios.org) and a support forum (forum.chibios.org): I suggest you to explore the website because has interesting technical information, documentation and news. Another good idea is to subscribe the forum and get in touch with the community: it could be an irreplaceable source of knowledge.
- This project has an Official Facebook page: like and follow it to receive news about releases or events related to the project.
- The code comes with a detailed documentation (there is a document for each sub-project): this is very useful while developing. Anyway, the documentation is auto-generated from code using a tool named Doxygen. This mean that exploring the code you will be able to find all the information needed. We will deepen this point later during hands-on.
- The project is distributed through Sourceforge. On the project page you will find a link to the SVN repository and a directory with all the downloadable files.
As final note, PLAY Embedded has a lot of resources to learn of to work with ChibiOS. We often offer support to people who comment our articles or subscribes our forum (forum.playembedded.org).
We highly recommend to ask help on our forum only for problems strictly related to PLAY Embedded articles/demos.
When you ask for help the most important think is to give precise information about the version of ChibiOS you are using.
In the beginning ChibiOS was versioned using a numerical system M.m.p where:
- p indicates the patch, a number incremented in case of small bug fixes;
- m indicates the minor, a number incremented in case of small changes or even addition of features which in any case do not impact on APIs;
- M indicates the major, a number incremented in case APIs change or addition of big features which requires a change of the design.
So the first stable release of ChibiOS was versioned as 1.0.0 and this numbering version has been used for the whole project until version 3.0.4. Starting from 3.0.0, as said, the project was divided in more sub-projects: at that point each sub-project started to have its own version number. To avoid confusion the whole package started to be released with a different numbering mechanism. This method is yy.m.p “codename” where:
- yy indicates the release year (less significant two digits) and changes only on major releases;
- m indicates the release month number and changes only on major releases as well as year;
- p indicates the patch, a number incremented in case of small bug fixes so on minor releases;
- codename is an identifier for the current patch.
So the M.m.p system is still valid for each sub-project. Right now ChibiOS/RT has reached version 4.0.0, ChibiOS/HAL 5.0.0 and ChibiOS/NIL 2.0.0. ChibiOS/EX instead is a collection of driver individually versioned, the latest ChibiOS package instead has reached version 17.6.0 “Adagio” also indicated as ChibiOS176 “Adagio”.
Each ChibiOS sub-project has its own version number identified by three numbers M.m.p. The whole package is versioned with a three number plus one word system yy.m.p “codename”.
As final note there is full compatibility between two different patch numbers. Because of that code which now runs on ChibiOS 17.6.0 will run on ChibiOS 17.6.1.
How to use it
Basically ChibiOS is a software library: if we download it from the repository it would looks like a folder containing source code and other plain text files. There is no way to use ChibiOS itself without a toolchain!
Dealing with programming, more so with embedded programming, you will often hear about “toolchains”. A toolchain is a set of distinct software development tools linked (chained) together used to perform a complex software development. In case of embedded systems, there is a subtle but simple truth which somehow explains the need of a toolchain: We are compiling a code which will run on a machine which is not our Computer. So, we need specific embedded libraries able to address our MCU and a compiler able to generate code which will run most likely on a different architecture: this is know as cross-compiler. Once the code is compiled the output will be a binary firmware which have to be flashed on our STM32 and, in a decent development system, this procedure is performed through a debugger.
As already said, fortunately ChibiOS comes with a ready to use toolchain named ChibiStudio which we are now going to install.
Note that ChibiStudio has a different version number. Do not confuse between ChibiStudio and ChibiOS: ChibiStudio is a toolchain which includes the latest available stable version of ChibiOS. ChibiOS is the embedded library: a collection of folder and text files.
Setup of ChibiStudio
Before to show how to do setup the toolchain let me point out requirement and steps. The toolchain is pre-assembled for Microsoft Windows: it is possible to re-assemble the same toolchain under Linux or Mac OS and you can find some guides about that on the ChibiOS website (I have seen ChibiStudio running under Mac OS X Sierra and under Linux Mint).
I am not used to Linux but I have planned to write an article about how to assemble ChibiStudio under a Linux. Right now, in case you are following this tutorial, my suggestion is to temporarily install virtual machine. If some one wants to contribute to the Linux setup article just comment this post: help is always welcome.
What follow is a “Learn by doing” section: from here and out is highly suggested to repeat the same steps on your own. Practice is the best way to understand!
There are some requirements to install ChibiStudio:
- Windows 7 or Higher with Administration Rights;
- Java 32-bit since ChibiStudio is based on Eclipse 32-bit. Note that to install Java 32-bit you have not to uninstall Java 64-bit;
- Install the latest version of 7-zip: ChibiStudio is compressed as .7z and this can prevent problems during the extraction.
- Uninstall all the antiviruses and enable Windows Defender.
Let me do some clarifications about latest point. The toolchain contains a lot of executable like make.exe from GCC or openocd.exe. These executables are so anonymous that common antiviruses detect them like viruses killing them as they are called to execute their normal functions. This generates unexpected behaviour of your toolchain. Some antiviruses can be also temporarily disabled but in my experience they continue to work in background even if disabled.
A funny remark, in 2014 Brian Dye, a Symantec’s senior vice president for Info-Sec said that antivirus “is dead”: Dye told the Wall Street Journal that hackers increasingly use novel methods and bugs in the software of computers to perform attacks, resulting in about 55% cyberattacks going unnoticed by commercial antivirus software. My suggestion remains the same: uninstall all the antiviruses and enable Windows Defender; the best antivirus is your finger.
Step by step guide
The setup of ChibiStudio could be performed extracting the toolchain from the archive under C:\.
In case is article is out of date, install the latest version of ChibiStudio anyway. If there will be important differences between the version here used and the latest one let us know and we will promptly update this article.
Note that the ChibiStudio package is hosted on Sourceforge. To get the latest version of this toolchain just search “chibistudio sourceforge” on google and you will be able to find the download page. By the way, this is the link to ChibiStudio archives.
The setup can be performed following these simple steps:
- Download the latest version of ChibiStudio.
- Extract it under C:\ using 7zip.
- Copy the link “Chibi Studio GCC 6.3” or “Chibi Studio GCC 4.7” on the desktop and use it to launch the toolchain.
The two link are quite the same except for the compiler version used by ChibiStudio: the first uses gcc-arm-eabi 6.3 and the second gcc-arm-eabi 4.7.
It is very important that toolchain is extracted under C:\ because batch file and Eclipse are preconfigured: the toolchain will work if the its files are placed at C:\ChibiStudio!
To make thinks simplest, this short video will show you how to execute the previous enumerated steps.
If you are not able to run ChibiStudio and an error windows prompts most likely you haven’t installed Java 32-bit correctly or something went wrong during extraction.
Some necessary concepts
Startup with ChibiStudio could be thorny, especially if you are new to Eclipse. We are going to introduce some general concept related to Eclipse pointing out which are the ChibiStudio specific customisation: this would improve your experience. Feel free to jump to paragraph 4.2 if you are already experienced with ChibiStudio.
First of all, Eclipse is an Integrated Development Environment (often abbreviated IDE). An IDE is a tool which aim to simplify the development process with visual aids like code highlighting, autocomplete content assist, advanced code browsing, debugging windows and so on.
Eclipse is completely open source and is widely used but not strictly necessary: it is possible also to write code in a text editor and compile it using a shell if you prefer. Anyway, a well configured IDE is always a good help to develop code quickly, especially if you are not used to shell and scripting languages.
Workbench and workspace
Eclipse is organised in Workbenches: a workbench is practically the Eclipse main window. It is the bench where you can organise your programming instruments, hence the different views and editors. Views and editors are your instruments to manipulate sources and data. and you can arrange them at hand for specific tasks (exploring, debugging, coding, etc.).
All the configuration related to Workbench (settings, IDE related variables, perspectives, history, imported projects, etc.) are saved as metadata in a specific location which is named Workspace. The workspace folder is also the default location where new projects are saved.
ChibiStudio comes with more than a release of ChibiOS for matter of back compatibility. As example, ChibiStudio Preview 19 comes with three different version of ChibiOS:
- ChibiOS 176 “Adagio” (located at C:\ChibiStudio\chibios176), which was the latest stable version of ChibiOS when ChibiStudio Preview 19 has been released;
- ChibiOS 161 (located at C:\ChibiStudio\chibios161), which is the previous version of ChibiOS. The specific version added to ChibiStudio is 16.1.8 which was the latest patch available when the toolchain has been released.
- ChibiOS Trunk (located at C:\ChibiStudio\chibios_trunk). Trunk represent the development version of ChibiOS which by definition is not stable updated at the latest revision number available when ChibiStudio Preview 19 has been released.
The presence of oldest version of ChibiOS would be a kind of bridge between old version and new one: having the previous and the latest version of ChibiOS in the same toolchain could be the chance to port 161 projects to 176 using the same toolchain. The trunk instead could be used to test new features and is also used from us to continue the development. Note that is possible to work on trunk updating it to the latest revision following this article (we are not going to use trunk right now so you don’t need to do this now).
For each version of ChibiOS integrated in ChibiStudio there is a related Workspace. So, in ChibiStudio Preview 19, there are three different workspaces:
- Workspace 176 (located at C:\ChibiStudio\workspace176), which is configured with all the available demos for ChibiOS 176 already pre-imported;
- Workspace 161 (located at C:\ChibiStudio\workspace161), which is configured with all the available demos for ChibiOS 161 already pre-imported;
- Workspace Trunk (located at C:\ChibiStudio\workspace_trunk), which could be to try trunk new features.
Additionally there is an other workspace:
- Workspace User (located at C:\ChibiStudio\workspace_user, which is an empty workspace dedicated to user.
In Eclipse, Workspace and workbench are different terms for different concepts: The workbench is practically the Eclipse main window, The workspace is a directory that holds information about workbench like the projects you work on, as well as the Eclipse preferences (from layout to behaviour). For more information you could refer to Eclipse documentation.
It is possible to switch workspace in use through the menu File->Switch Workspace and choosing a workspace from the history or selecting “Other…” to browse a new workspace like is shown in the next figure.
Taking a look to this menu you can also figure out which is the workspace in use because it would not be in the list. Refers to previous figure, we are currently using Workspace User which is not in the history list.
Choosing another workspace Eclipse will restart loading a new Workbench.
The organisation of your workbench could be saved to be quickly recalled at proper moment: these presets take the name of perspectives.
Perspectives could be switched using the proper button in the top right corner of you Workbench. It also possible to add other perspectives, save or reset the current one to default through the drop-down menu “Window” located in the menu bar.
Note that switching perspective is matter of views organisation, this will not impact your code or you files. You can switch perspective as you want without any concern.
ChibiStudio comes with two separate perspectives: C/C++ and Debug. If the on first run your do not have C/C++ and Debug perspectives on the top right corner most likely you haven’t uninstalled the antivirus or you haven’t updated 7zip: the extraction has been affected by this.
The two perspectives reflect the way is splitted the code development process. Code editing is only a phase of the whole development process: having a compiling code it does not mean it is working as expected. We are talking about functional behaviour here. So, the whole development process could be splitted in two specific parts there are two specific moment in the development process:
- The software development, in other words that process related to new project creation, code editing, compiling and resolution of errors and warnings. The perspective C/C++ is oriented to this part and you can figure out this because the largest amount of workbench area is dedicated to text editor area.
- The debugging, in other word that moment related to test functionality of our code, detection of unexpected behaviour or evaluation of software performances and consistency. The perspective Debug is oriented to this phase and it offers a lot of additional windows to explore code, memory and variables or to evaluate expression, connect terminal and so on.
At first launch ChibiStudio usually shows a welcome window: just close it. You should be now in C/C++ perspective. The editor window is the largest windows in the middle of the workbench and should be empty. On the right there is the Project Explorer which usually contains all the imported projects.
If you have downloaded ChibiStudio Preview 19, you will start in the User Workspace and the project explore should contain only two dummy projects representing the documentation and the tools of our toolchain as shown in Fig. 5.
The best way to proceed at this point is to import a ready to use demo. The demos we need to import are under the folder C:\ChibiStudio\chibios176\demos\STM32. This is true because we are going to use ChibiOS 176 but there are similar folders also under ChibiOS 161 and ChibiOS Trunk directories.
In the demos\STM32 directory there are a lot of folders each of which represent a standalone project. Each project is named following the same pattern KERNEL-MCU-BOARD so, as example, RT-STM32F207ZG-NUCLEO144 is a demo based on ChibiOS/RT for STM32 Nucleo F207ZG, a Nucleo-144 equipped with STM32F207ZG and it works on this specific development kit.
Note that if there are big differences between two revision of the same board there will be more than a project. As example STM32F3 Discovery originally was equipped with ST-Link V2. Starting from Revision C this board has been equipped with ST-Link V2-1 which requires additional connection between debugger and MCU. This required the creation of two separate demos: RT-STM32F303-DISCOVERY and RT-STM32F303-DISCOVERY-REVC. Take this in account if you are using this development board.
Importing an existing project
The next step is to import a demo for the development board you are going to use. Almost every official STM32 Discovery and STM32 Nucleo board is supported and the related demo is in the already mentioned demos\STM32 directory. Since I will use both STM32 Nucleo F401RE and STM32F3 Discovery kit, I will import both RT-STM32F401RE-NUCLEO64 and RT-STM32F303-DISCOVERY-REVC.
The steps required to import an existing demo are:
- Select File->Import from menu;
- In the newly prompted window select Existing project into workspace and press Next;
- Select Root directory: “C:\ChibiStudio\chibios176\demos\STM32″;
- Check all the project you want import and press Finish.
Let see how to perform these steps in the next short video
Handle imported projects
At this point, the Project Explorer should contain one ore more additional projects according to how many projects you have imported.
In Eclipse, a project is a blue folder containing files, links and sub folders and it actually is mirrored to a real folder. As example, the project RT-STM32F401RE-NUCLEO64 is mirrored to the directory “C:\ChibiStudio\chibios176\demos\STM32\RT-STM32F401RE-NUCLEO64\”. To be able to explore a project in Eclipse it should be open. You can open a project right clicking on it and selecting Open Project.
In Eclipse a project could be open or closed right clicking on it and choosing the proper entry from the menu. A project shows its resources only when is open. To avoid confusion, it is a good idea to work keeping all the projects closed except the one you are working with. It is possible to close all the project except one right clicking on the one you want keep open and choosing Close Unrelated Projects.
Build and clean
The projects we are going to use are based on makefile: the makefile is a script file which contains a series of directives used by make to build our code. All the projects in ChibiOS comes with a complete and ready to use makefile.
It could happen that the makefile have to be edited to customise the build process or include new sources and we will face this problem if necessary. Right now we do not have to edit makefile. Anyway, is interesting to know that if build procedure ends successfully the makefile is designed to create a subfolder named build under the project main folder.
As shown in figure, the build folder contains the compiled firmware as binary (ch.bin) and as hexadecimal (ch.hex) but also the Executable and Linkable Format file (ch.elf). The ELF contains the executable but also information about how code is organised in memory and the list of all symbols: this file is required by debugging activities.
To build a project right click on it and select Build Project. Another way is to click on it and press the hammer button in the tool bar. If the procedure ends successfully a new folder into the project will appear: it is named build and contains the output of make process as bin, hex, elf and other formats.
Note that a project could be also cleaned, the clean procedure removes the build folder which contains also some object files. The object files are a kind of partial output of make process. These files are not rebuilt if Eclipse “thinks” that related sources have not been modified. This reduce the built time in case of small edits. Rarely could happen that this mechanism fails: in this case there could be some misalignment between code and binary. In such particular condition a clean and rebuild will solve any issue. A good idea is to clean and rebuild the project when we do major edits to our code, especially when dealing with makefile or preprocessor directives.
There could be mutiple causes of failure during build of default demos and most common are: your antivirus, an error occured during extraction of ChibiStudio or a misplacement of ChibiStudio main folder.
Flash and run
An important part of software development is the flash and run. This procedure copies the binary into the microcontroller flash memory and starts its execution. The flash and run is automatised in ChibiStudio and involves OpenOCD on the PC side and ST-Link on the Development board side as shown in Fig.1.
OpenOCD is an open source GDB server which offer a programming interface to an hardware debugger. The debugger allows common operation like write/erase flash memories, write/clear RAM memories, set register values, set breakpoints or watchpoints, set program counter, execute the code step by step and so on. From our point of view we can say that:
The debugger is composed by an hardware part (in this case ST-Link Embed Debugger) and a software part (in this case OpenOCD). The debugger could be considered like a bridge between our IDE and the MCU. To perform any debugging operation the first step is to “create this bridge”
There are two buttons which we will use to execute the flash and run: these two button are shown in figure and are the External Tools Menu (orange) and the Debug Menu (Azure). Actually, we should not press on the button but on the small black arrow beside them: this will open a drop down menu.
To execute the flash and run we have to launch OpenOCD: this could be done from the External Tool Menu. In this menu there are different options but we have to choose “OpenOCD on ST-Link <our-version> (prompts for .cfg target configuration)“. The version of our ST-Link depends on our development board and this information could be found on the development board blister and is reported in the User Manual. As example, older version of STM32F3 Discovery had ST-Link V2 but, starting from REVC, STM32F3 Discovery has been equipped with ST-Link V2-1. Older Discovery boards have been equipped with ST-Link V2 or ST-Link V1, newer Discovery and all the STM32 Nucleo boards comes with ST-Link V2-1.
After selecting a voice from that menu a windows will prompt: in this windows we have to provide a configuration script related to OpenOCD which indicates which board we are using. To do this, we have to point to folder C:\ChibiStudio\tools\openocd\scripts\board and choose the right script. As example for STM32F3 Discovery there are two different scripts (stm32f3discovery.cfg and stm32f3discoveryRevC.cfg). Each STM32 Nucleo has is own script grouped for sub-family so has example st_nucleo_f4.cfg is suitable for STM32 Nucleo F401RE, STM32 Nucleo F410RB, STM32 Nucleo F446RE and so on.
Now OpenOCD should have been started. If this operation has been succesfull, OpenOCD will recognize the target and, in the Console window, we will find see the MCU voltage, the number of breakpoints and watchpoints as shown in Fig.9.
From the Debug Menu, we can now launch the flash and run selecting the proper Launch Configuration. Each project has is own Launch Configuration and we will be able to recognise it because they have the same name. Once we have selected it, Eclipse will build the project (if this has not been already done) and will start the procedure switching automatically to Debug: in this perspective we can press the Resume button to run the code execution as shown in Fig.9.
- Launch OpenOCD from the External Tool Menu choosing the proper interface;
- In the newly open window, select the proper configuration script related to the board in use;
- Check that OpenOCD has been started properly looking to the console windows: there should be information about the MCU voltage, the number of breakpoints and watchpoints.
- From the Debug Menu, launch the flash and run selecting the proper Launch Configuration;
- In the Debug perspective press the Resume button to run the code execution.
Again, lets take a look to this short video which shows how to flash and run the STM32F3 Discovery default demo:
The same procedure has been repeated also for STM32 Nucleo F401RE just to make you able to spot differences:
The first flash and run procedure is very important to check if the you have set up the toolchain correctly. As example, if you are not able to launch OpenOCD maybe there is a problem with ST-Link drivers: in this case check that drivers have been installed correctly and check also that the USB cable has been connected properly using to the proper port: certain Discovery kits has more than a USB port so you have to check that you are using the port marked as ST-Link USB.
If you receive an error while switching on Debug perspective it could be that OpenOCD has not been started properly or that it has lost connection with target so you have to relaunch it (in debug context the MCU targeted by debugger is usually called target).
If OpenOCD starts properly, you will be able to read the target voltage, the number of breakpoints and watchpoints in the console windows and this will looks like Fig.9. While OpenOCD is running, in the Debug perspective, in the you will see a related entry as shown in Fig.10. Note that, you cannot launch OpenOCD twice and you cannot launch the flash and run procedure if OpenOCD is not running.
Resuming the code execution, one or more on-board LEDs on will start to blink. On STM32 Nucleo-64 there is a green LED, in case of STM32 Nucleo-144 there are three coloured LEDs which executes a nice light game, in case of STM32F3 Discovery it is even more showy since this board has 8 LEDs.
If LEDs blinks you have successfully completed this tutorial and you can jump to next article. In case of problem just comment this article or subscribe our forum.
In this article we focused more on the IDE and the basic procedures required by software development. In the next article we will take a deeper look to default demos focusing more on programming.
- The ChibiOS project
- Setup of ChibiStudio
- Exploring ChibiStudio