Linux Quick Start

This page explains how to install the precompiled Miosix Toolchain. If you prefer compiling GCC from sources, see Building GCC from sources.

Before you begin

st-flash

If you want to program STM32 microcontrollers, you will also need a tool to transfer your programs to the microcontroller. A popular choice for boards like the stm32f4discovery that have an embedded STLinkV2 USB programmer/debugger is the st-flash tool. To install it on debian/ubuntu run:

sudo apt install stlink-tools

stm32flash

An alternative tool to program STM32 microcontrollers using the serial port bootloader as opposed to the stlink interface is stm32flash. Finally, for historical reasons, the Miosix Toolchain includes lpc21isp, a tool to program LPC2000 microcontrollers using their serial bootloader.

QSTLink2

An alternative choice to st-flash is QSTLink2. It has a GUI but the precompiled ppa is no longer updated for the latest Ubuntu releases. The installation on Ubuntu/Debian requires to add a ppa and install it via apt-get. Also, it is recomended to install the udev rules, which allow QSTLink2 to connect to the USB port without the need to run it from root.

sudo add-apt-repository ppa:fpoussin/ppa
sudo apt-get update
sudo apt-get install qstlink2
wget https://raw.githubusercontent.com/mobyfab/QStlink2/master/res/49-stlinkv2.rules
sudo mv 49-stlinkv2.rules /etc/udev/rules.d
sudo chown root:root /etc/udev/rules.d/49-stlinkv2.rules

If a PPA of QStlink2 is not available for your platform, you can compile the stable version V1.2.3 in this way

git clone https://github.com/fpoussin/QStlink2.git
cd QStlink2
git checkout v1.2.3
git submodule update --init
qmake -qt=qt5
make
sudo make install

Serial port setup

Miosix redirects stdin/stdout to a serial port by default on most boards, so it is important to set up serial ports correctly on your development machine. On most Linux distros serial ports, both the physical ones like /dev/ttyS0 and the USB to serial adapters like /dev/ttyUSB0 are owned by the dialout group, so you need to add your user to that group before you can access them.

sudo usermod -a -G dialout `id -un` # Add yourself to the dialout group

Note that you may need to reboot your computer before the change takes effect. Also, you need a program to interact with the serial port, like GNU screen.

sudo apt-get install screen # For Ubuntu/Debian
sudo pacman -S screen       # For Arch Linux

Install the Miosix Toolchain

Download the latest version of the Miosix Toolchain and launch it. The installer will ask for your root password to copy the compiler to the /opt/arm-miosix-eabi directory, and put symlinks to /usr/bin.

wget https://miosix.org/toolchain/MiosixToolchainInstaller.run
sh MiosixToolchainInstaller.run

If you do not trust the installer and want to verify its content, or you want to install it locally, it is possible to extract the content of the installer with the following command.

sh MiosixToolchainInstaller.run --noexec --target arm-miosix-eabi

Keep in mind that for a local install you will need to set the PATH environment variable to the arm-miosix-eabi/bin directory.

Get the Miosix kernel sources

The preferred way to download the Miosix kernel is through git. If you do not already have it installed you can install it now

sudo apt-get install git # For Ubuntu/Debian
sudo pacman -S git       # For Arch Linux

The Miosix git repository used to be hosted at gitorious.org, but the service was shut down. For this reason, the kernel is now hosted directly at miosix.org. There is also a github mirror and the two repositories will be always kept in sync. Currently, the master branch contains the stable 2.0 kernel, while the testing branch contains the current development version. Kernel versions prior to 2.0 are deprecated.

git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git fetch origin
## To select the development version of the kernel
#git checkout -b testing origin/testing

Configuring and compiling the kernel

More in-depth information on how th configure the kernel for your board can be found in the Board list, but for now we will assume you have an stm32f4discovery, which is a common board, and briefly show how to get to a blinking LED example.

Top-level directory

First of all the miosix-kernel directory is often referred to as the top-level directory of the kernel. It contains, among other, the main.cpp file which is where you can start writing your application code, the Makefile where you can add additional C++ and C source files to be compiled, and the miosix directory which contains the kernel.

All paths in this wiki, unless they start with a '/' (for Linux) or 'C:\' (For Windows), are intended relative to Miosix's top-level directory, so if we're talking about the 'miosix/config/Makefile.inc' file you can find it within the directory where you have downloaded the kernel from git.

Configuring the kernel

The kernel is configured by editing two files, named miosix/config/Makefile.inc and miosix/config/miosix_settings.h. Open the first one, and select your board. To do so, look for the OPT_BOARD section of the file, which looks like this:

##
## Target board, choose one. This also implicitly select the target
## architecture
##
#OPT_BOARD := lpc2138_miosix_board
OPT_BOARD := stm32f103ze_stm3210e-eval
#OPT_BOARD := stm32f103ve_mp3v2
#OPT_BOARD := stm32f100rb_stm32vldiscovery
#OPT_BOARD := stm32f103ve_strive_mini
#OPT_BOARD := stm32f103ze_redbull_v2
#OPT_BOARD := stm32f407vg_stm32f4discovery
#OPT_BOARD := stm32f207ig_stm3220g-eval
#OPT_BOARD := stm32f207zg_ethboard_v2
#OPT_BOARD := stm32f207ze_als_camboard
#OPT_BOARD := stm32l151_als_mainboard
#OPT_BOARD := stm32f407vg_bitsboard
#OPT_BOARD := stm32f205rg_sony-newman

In Makefile syntax a '#' sign denotes a comment, so to select a board you have to comment out (by prepending a '#') the default board selected, and uncomment (by removing the '#' at the start of the line) your board, in this case, which in this example will assume is the stm32f407vg_stm32f4discovery.

Next, edit the miosix_settings.h file and uncomment (by removing the '//' at the start of the line) the following line

//#define JTAG_DISABLE_SLEEP

(which is towards the end of the file). This is a C++ header file, so the comment syntax is '//'. More information on the meaning of this line can be found in miosix_settings.h, but a short summary is that this line prevents the kernel from putting shutting down the CPU when it has nothing to do, which saves power but interferes with the programming/debugging protocol used to program the board via QSTLink2.

Also, comment out the #error line towards the beginning of the file. This line exists to cause a compilation error if the user forgets to edit the miosix_settings.h file. The result should look like this:

// Before you can compile the kernel you have to configure it by editing this
// file. After that, comment out this line to disable the reminder error.
// The PARSING_FROM_IDE is because Netbeans gets confused by this, it is never
// defined when compiling the code.
#ifndef PARSING_FROM_IDE
//#error This error is a reminder that you have not edited miosix_settings.h yet.
#endif //PARSING_FROM_IDE

Blink a LED

Open the main.cpp file in the top-level directory, and replace its content with the following program:

#include <miosix.h>
using namespace miosix;
int main()
{
    for(;;)
    {
        ledOn();
        Thread::sleep(1000);
        ledOff();
        Thread::sleep(1000);
    }
}

The Miosix board support package defines the ledOn() and ledOff() functions to control a LED on the board for all the boards that have at least one software-accessible LED.

Compiling

To compile the kernel, open a terminal in the Miosix top-level directory and type make. If all goes well, the result should look like this.

Otherwise, compiler errors will appear in the shell. The number that appears under text in the make output is the size in bytes of your application plus the kernel. If you think that 90KBytes is a bit too much for a blinking led, don't worry. The kernel by default includes support for C stdio functions, filesystem code including Unicode support and the C++ exception handling runtime, all of which can be disabled to significantly reduce code size.

Programming

To program the stm32f4discovery board you can use the st-flash tool. Using this tool requires you to know the base address of the FLASH memory that for STM32 microcontrollers is 0x08000000.

st-flash write main.bin 0x08000000

Alternatively, with QSTlink2

Once you start it, you have to click on Connect, and it should find your stm32f4discovery board. After that, click on Send and select the main.bin file in the Miosix top-level directory.

Note that, regardless of using QSTLink2 form the shell or the GUI, there is a bug that in some circumstances blocks the microcontroller until the next powercycle. Therefore, after having programmed the microcontroller, is is recomended to unplug and reconnect the USB cable to powercycle the stm32f4discovery board. At that point, you shuold see the red LED blinking.

Lastly, if you have a brand new board and QSTlink doesn't work you may take a look at this page.

What's next?

You have finished the installation of the Miosix Toolchain. You may want to install and configure an IDE, or the debugger.

Uninstall the compiler

If for some reason you need to uninstall the compiler, there is an uninstall script in the /opt/arm-miosix-eabi directory (Note: if you have built the compiler from sources the uninstall script may not be there). Running the script will uninstall the compiler and the symbolic links in the /usr/bin directory. Just like the install script, the uninstaller will ask for your root password to be able to remove the installed files.

There is no need to uninstall and old compiler to install a new one, the installer will take care of that automatically. However, if you have installed the compiler and now you want to build it from sources, you first need to uninstall the old compiler.

cd /opt/arm-miosix-eabi
./uninstall.sh

If you have chosen to install the compiler locally (i.e: not in the '/opt/arm-miosix-eabi' directory), simply remove the compiler directory.