Linux Quick Start
Installing the required software
Install the Miosix Toolchain
To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called Miosix Toolchain. This page explains how to install the precompiled Miosix Toolchain. If you prefer compiling GCC from sources, see Building GCC from sources. The commands to run are as follows, where you'll need to replace <version> with the (usually latest) version found in the Miosix Toolchain page.
wget https://miosix.org/toolchain/MiosixToolchainInstaller<version>.run
sh MiosixToolchainInstaller<version>.run
The installer will ask for your root password to copy the compiler to the /opt directory, and put symlinks to /usr/bin. If you later want to uninstall the compiler, as part of the installation process an uninstall.sh script is placed together with the compiler in /opt/arm-miosix-eabi. Uninstalling the previous compiler is done automatically when upgrading to a newer version.
If you do not trust the installer and want to verify its content, or you want to install it locally (in your home folder instead of system-wide), it is possible to extract the content of the installer with the following command. This operation also extracts, without running it, the installer.sh installation script.
sh MiosixToolchainInstaller<version>.run --noexec --keep
For a local install you will need to set the PATH environment variable to include the extracted arm-miosix-eabi/bin directory.
Install a flashing tool
With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, so pick whatever your GNU/Linux distro of choice provides. Here is a list of suggestions for the most common microcontrollers used with Miosix: Linux flashing tools.
Serial port setup
Miosix redirects stdin/stdout to a serial port by default on most boards, so to see the boot log and the output of printf() in your application you need a program to interact with the serial port. A common one is GNU screen, but there are alternatives such as minicom or tio.
sudo apt install screen # For Ubuntu/Debian
sudo pacman -S screen # For Arch Linux
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 to avoid the need to use sudo every time you run screen 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.
Downloading and configuring the Miosix kernel
To download the Miosix kernel you need git. If you do not already have it installed you can install it now
sudo apt install git # For Ubuntu/Debian
sudo pacman -S git # For Arch Linux
This is a stripped down guide with the bare minimum to get you started, we also have a full guide about Miosix and git workflow. Following the tutorial in this page, your project directory will not be under version control (git). The Miosix and git workflow page shows how to create a git repository for your project and add the Miosix kernel as a submodule.
Before downloading the kernel, however, you first have to create a directory for your project (in this case, the hello world), and then clone the kernel as a subdirectory.
mkdir hello
cd hello
git clone https://github.com/fedetft/miosix-kernel.git
Initializing a Miosix project
For reasons explained in depth in the Miosix and git workflow page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code. This can be automated with a [Perl] script called init_project_out_of_git_tree.pl.
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
You should run the script from the directory where you want to initialize your empty project, such as the hello directory in this tutorial. A successful run of the script produces the following output:
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
Although Perl is pre-installed in almost all GNU/Linux distros, this script depends on the File::Copy::Recursive Perl module which often is not. If you get errors running the script, install the missing module as follows and try again:
sudo apt install libfile-copy-recursive-perl # For Ubuntu/Debian
Your project directory should look like this, with the miosix-kernel directory containing the kernel sources, the config directory with the kernel configuration, the empty main.cpp and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:
For this tutorial, we'll use the Makefile build system, have a look at the CMake to learn how to use CMake instead.
Configuring the kernel
The minimum configuration required to compile the kernel is to select a board.
The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here. The kernel is configured by editing files in the config directory, the two most important ones are [Makefile.inc] and [miosix_settings.h].
To select a board, open the first one, config/Makefile.inc. Look for the OPT_BOARD section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the # sign is a comment in Makefile syntax), so you need to uncomment the line of your board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, here's a basic guide: currently most chips supported by Miosix are STM32. Nucleo boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost. Third party boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging. Venturing outside of STM32, the RP2040 is a good choice. Also in this case, you'll need a separate USB to serial adapter, though.
Writing your first Miosix program
Hello world
Open the main.cpp file, and replace its content with the following program:
#include <cstdio>
#include <miosix.h>
using namespace miosix;
int main()
{
for(;;)
{
iprintf("Hello world\n");
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.