Using ChibiStudio
This documentation will cover everything from downloading and installing ChibiStudio to getting your project run on actual hardware. In this tutorial we'll use a MikroMedia STM32-M4 board but this guide can be used for just any platform as there will only be slight variations.
Please note that ChibiStudio is part of the ChibiOS/RT project and is in no way owned by the uGFX project.
Installation
ChibiStudio is currently only available for Windows. There are however some ways to get ChibiStudio working on both Linux and Mac OS X. Please refer to the ChibiOS/RT documentation to learn how to do so. This guide will only cover using ChibiOS/RT on Windows.
The following prerequisites need to be downloaded and installed before ChibiStudio can be used:
- Java runtime
- Programmer / Debugger drivers (ST-Link in case of STM32)
- ChibiStudio
- uGFX
The following part of the documentation will cover downloading and installing each of those components.
Java
ChibiStudio is an Eclipse based IDE and needs a Java runtime to run. Important: ChibiStudio is currently only available in a 32-Bit version and will require a 32-Bit Java runtime.
The Java runtime can be downloaded from the official Java website. It runs well with the Java 8 runtime. In case of you haven't already a 32-Bit Java runtime installed please download and install the Java 8 JRE for Windows. You want to download the Windows x86 Offline version. Note that you have to accept the licensing terms on the top of that list before you can download the installation file.
ST-Link V2
You will need a driver to communicate with your programmer/debugger (the thing that hooks up to your computer via USB). In case of STM32 this is called the ST-Link. You will to download and install the ST-Link Utility to use your programmer/debugger. This can be downloaded from the official ST website: ST-Link Utility website.
After you have clicked the Part Number link you will be forwarded to a new site. There you can click the Download button to download the file.
Extract the archive and install the program like any regular Windows software.
At the end of the installation, a wizard will ask you to install the drivers. It is important to install the drivers as you won't be able to communicate with the device otherwise.
At this point it is a good idea (and might be even required) to reboot your computer. After reboot, connect your ST-LinkV2 to the computer using the USB cable. Windows will present a notification in the task bar when the installation of the new driver was successful.
ChibiStudio
The latest version of the ChibiStudio can be downloaded here: ChibiStudio.In this tutorial we used ChibiStudio Preview 11. However, you're encouraged to download the latest available version.
ChibiStudio comes in a 7z archive that can just be extracted and requires no installation at all. In case of you don't have appropriate software to extract a 7z archive you may install the official freeware 7-zip. Once extracted you need to move the directory to C:\ so that you get the resulting path C:\ChibiStudio. This is critical as this path is hardcoded into the ChibiStudio startup file and it won't be able to compile anything when it's in a different location.
uGFX
As described in this guide uGFX can either be downloaded as a stable release or as the git repository. Please note that it's strongly recommended to use the git repository in order to get the latest bug fixes, features and improvements.
Stable release
uGFX can be downloaded as a stable release ZIP archive from the official download website. After extracting the archive place the uGFX directory in C:\ChibiStudio so you'll end up with the path C:\ChibiStudio\ugfx.
Git repository
Using the git repository allows to always retrieve the latest bug fixes, features and performance improvements. The uGFX git repository is located at BitBucket.
Place the repository under C:\ChibiStudio so you'll end up with the path C:\ChibiStudio\ugfx.
Congratulations, you have finished installing everything needed to start developing your first project using ChibiOS/RT and uGFX!
Creating a project
First start of Chibistudio
ChibiStudio needs to be started by clicking the ChibiStudio shortcut under C:\ChibiStudio. Note that it is important to use this shortcut as it sets up some important environment settings.
You can copy the shorcut to your desktop or add it to your start menu. When double clicking the shortcut to start the ChibiStudio you might be presented with a warning:
Uncheck Always ask before opening this file as we know that this program comes from a confidential source and click the Run button.
if you haven't installed a proper 32-Bit Java runtime you will be presented with the following error:
Please refer to the installation section to learn how to install Java to run ChibiStudio.
create the first demo project
Close the welcome screen. ChibiStudio is provided with two workspace. One for the chibios 3 unstable and one for chibios 2. As the version 3 is not stable you need to switch to version 2. To do it, go the the file menu, switch workspace and select c:\chibistudio\workspace26.
To start a new project the faster way, you can copy one of the demo you will find in the project explorer. You can selection any project, but to be sure, please use STM32F4xx-GPT. Double click on it to open it. Then right click on the folder icon of this project and select copy. To copy it, right click on the icon and select past. A new window appear name the new project MikroMedia-base and click ok. Be careful, the name of the project need to not have space.
New we need to copy some files from the ugfx folder. Open Windows explorer and go to C:\ChibiStudio\ugfx\boards\base\Mikromedia-STM32-M4-ILI9341\example_chibios_2.x. You need to copy all files and folder form this to your new project.
Copy C:\ChibiStudio\ugfx\boards\base\Mikromedia-STM32-M4-ILI9341\example_chibios_2.x\*.* to C:\ChibiStudio\workspace26\MikroMedia-demo.
Replace all files. For this tutorial, you will use demo software of ugfx. All demo program has already a main function. To sucessfully compile, you must delete the main.c from the new project folder.
Content of project folder after delete main.c
On ChibiStudio, open you new project and edit the Makefile. You need to change the path of chibios and ugfx like :
GFXLIB = ../../uGFX CHIBIOS = ../../ChibiOS
That the end. You can try to compile a demo. This will compile the gdisp basics demo as the line says :
GFXDEMO = modules/gdisp/basics
If you want to try another demo, just change the line like (for running tetris)
GFXDEMO = applications/tetris
If you want to try tetris, you need to compile your program with math algorithm. Fopr this change on the Makefile the line :
LDFLAGS = -lm
To compile, click on the hammer icon.
If you have the error below, then you haven't save you Makefile. save it and try again.
If you want to try different demo, please do a clean (Project menu clean.. option) or your project will never compile.
Final configuration of your project
Before downloading the new software on the board, you need to do two action. First change the board folder to the correct one.
To do it, right click on the board folder in your project and select properties.
On the board properties window, click on edit next to Location field.
Select the path like : C:\ChibiStudio\ugfx\boards\base\Mikromedia-STM32-M4-ILI9341
Secondly, you need to add ugfx folder to your project. To do it, right click on the project folder. On the sub-menu, select new and folder.
On the new folder window, click advanced option button. Select ugfx folder and click ok.
Configuration of OpenOCD
Open Openocd external configuration tools.
Copy the OpenOCD on ST-Link V2 (prompts for .cfg target configuration)
Change the name like : OpenOCD form Mikromedia STM32. Modifiy the argument option like : -c "telnet_port 4444" -f "interface/stlink-v2.cfg" -f "board/stm32f4discovery.cfg"
Click apply and close.
Connect the st-linkv2 to the board and the computer. run the last openocd config.
Configuring debuger
The last by not the least you need to configure your project with gdb. Start the debug configuration window.
Copy a existing debug project.
rename the project MikroMedia-demo debug and change the project to MikroMedia-demo.
Click apply and debug.
If you have fellow this tutorial correctly, a error window need to appear telling you that ChibiStudio can't fing the efl file.
Open again the Debug configuration window. Edit the MikroMedia-demo debug and change c/c++ application with : C:\ChibiStudio\workspace26\MikroMedia-demo\.build\MikroMedia-demo.elf like :
Click apply and debug.
Normally, this time gdb start and change the view of ChibiStudio in debug mode.
Now, gdb stop to program in the beginning of the main function. To run the software, click on the Resume button.
Advanced tipps & tricks
The following section contains a few tipps and tricks to further simplify working with uGFX and the ChibiStudio in general.
Automatically save files before building
With the default settings of ChibiStudio is is required so manually save files after modification. However, eclipse provides the option to automatically save all modified files when building the project. This feature can be enabled under Window -> Preferences -> General -> Workspace -> Save automatically before build.
Using the uGFX repository with symlinks
In case of you're using the uGFX git repository instead of the stable release archive you might want to place the repository in a different location other than C:\ChibiStudio\ugfx. However, you'd have to modify the path pointing to the uGFX root directory in the Makefile which might sometimes be inappropriate to do. This can be fixed by creating a shortcut from the actual location of the uGFX repository to C:\ChibiStudio. However, sadly the shortcuts that you can create in the Windows file explorer are not becoming part of the file system and are therefore not visible to make. This issue can be fixed by creating a real hardlink in the file system. The process to do so has been described here.
