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 GNU/Linux distros serial ports and USB to serial adapters like /dev/ttyUSB0 and /dev/ttyACM0 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 section 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 git 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 now look like the following picture, 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 page to learn how to use CMake instead.

Configuring the kernel

The minimum configuration required to compile the kernel is to select a board, as the kernel needs to build the appropriate board support package for it.

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 corrsponding to your board. Porting the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported 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, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:

• Nucleo STM32 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.
• Discovery STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
• Third party STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to solder the pin header yourself, and 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 and some soldering skills, though.

Writing your first Miosix program

Hello world

Open the main.cpp file with your IDE or text editor of choice, and replace its content with the following program:

#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
    for(;;)
    {
        iprintf("Hello world\n");
        ledOn();
        this_thread::sleep_for(500ms);
        ledOff();
        this_thread::sleep_for(500ms);
    }
}

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a Fluid kernel architecture: in a nutshell it's a kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the main() function you just wrote in kernelspace. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second. The printing is done with the iprintf() function. If you expected just printf() without the i, the reason is that Miosix uses the Newlib C standard library that provides both printf() and iprintf(), an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use printf() if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the sleep_for() function from the C++ standard library. Miosix supports other sleeping APIs, such as nanosleep() from POSIX, or Thread::sleep(), a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shares the CPU with other threads.

Many (but not all!) board support packages define the ledOn() and ledOff() functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the stm32f746zg_nucleo board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ledOn() and ledOff(). You can comment out those two lines in this case, your hello world will only print to the serial port.

Compiling

To compile the kernel, open a terminal in the hello project directory and type:

make -j`nproc`

The -j`nproc` is optional, it will compile faster by using the multicore CPU in your computer. If you know how many cores you have, you can also specify the number explicitly, such as make -j8. 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. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to reduce the code size.

Flashing

To flash the board, you can use the make program Makefile rule to automatically download the kernel to the board. Connect the USB cable first, and then run:

make program

If the operation completed successfully, then the output should be similar to this one, and the LED should blink on the board:

If the operation did not succeed, here are some common problems:

• You get a command not found error. You probably did not install the right flashing tool on your computer, read here Linux flashing tools.
• The flashing tool starts, but throws an error such as Couldn't find any ST-Link devices. You probably do not have the right permissions to access the board. Try sudo make program. If that one works, you'll have to install udev rules to make the USB device of your board's programming interface accessible from your user. Unfortunately the details to installing (or writing from scratch) the correct udev rules file depend on the combination of the flashing tool and board. None of these are specific to Miosix, so look online in the documentation of your flashing tool.

Another issue in some STM32 boards is that the flashing tool leaves the board in a state where the mcirocontroller blocks either after flashing or if you press the reset button on the board. This issue is again specific to the board and flashing tool and unrelated to Miosix. If you encounter this problem after having programmed the microcontroller, it is recommended to unplug and reconnect the USB cable to powercycle the board. At that point, you should see the LED blinking.

Accessing the serial port

Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s. If you're using a Nucleo board from ST, the USB to serial port adapter will appear on your computer as /dev/ttyACM0, so use the screen program with the following parameters:

screen /dev/ttyACM0 115200

Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

Exiting the screen program is cumbersome at first, but you'll get used to it quickly. You have to type Ctrl-A, then k and y. Typing Ctrl-C won't stop the program, it will just send a Ctrl-C to the microcontroller.

If you are using a board that does not have an integrated USB to serial adapter, you'll need to figure out to which pins is the default serial connected. To do so, you'll have to look for the kernel configuration file for your board. For example, for the stm32f411ce_blackpill the file is: config/board/stm32f411ce_blackpill/board_settings.h, where you'll find that the serial port TX pin is PA9, and the RX pin is PA10. Remember to cross the TX and RX pin, the TX pin of the microcontroller goes to the RX pin of the serial adapter! For reliable communication you'll also have to connect a wire between the board GND and the serial adapter GND.

Another example would be for the RP2040. In this case the configuration file is config/board/rp2040_raspberry_pi_pico/board_settings.h and the serial TX pin is P0.0, while RX is P0.1.

The most common standalone USB to serial adapters are based on the FTDI's FT232 chip, which appears on GNU/Linux as /dev/ttyUSB0, so the command to access the serial port would be:

screen /dev/ttyUSB0 115200