Windows Quick Start

Installing the required software

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, you can find the link to download it here. At the end of the installation you will need to reboot your computer (sorry, it's Windows...)

Git

To download the Miosix kernel and keep it up to date, you need the git version control system.

It is recommended to install it from git-scm.com. Please do not uncheck the Windows Explorer integration feature during the installation, as you will need it to install the kernel sources.

Perl

The Perl programming language is used by the Miosix build system. Unlike on GNU/Linux computers where Perl is pre-installed, for Windows you'll need to install it separately.

Strawberry perl is the recomended Perl version for Miosix on Windows.

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, and on Windows you'll usually want to install the flashing tool provided by your chip vendor.

For STM32 chips, you can use the STLink utility available here.

Text editor or IDE

It is recommended to download a better text editor than Notepad, as you will need it to edit the Miosix configuration files. Notepad++ is a good option, but many other options exist. Just don't use Notepad, because it does not recognize Unix line-endings and will show you Miosix source files as if they were composed of a single line of text.

As an alternative to Notepad++, you may want to use an IDE.

Serial port viewer

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. PuTTY is an option, although old fashioned. TODO: There are likely better options for Windows too.

Downloading and configuring the Miosix kernel

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.

Using the Windows explorer, create a hello directory, double click on it. Then right-click on the empty directory. Select Git bash to open a git shell. This opens a shell where you can type the commands to download the kernel.

Note that it is possible to paste commands in the shell (so as to avoid typing them, which can be tedious and lead to typos), but you have to do it one line of text at a time, and to paste you need to use the Shift+Ins shortcut, not the usual Ctrl+V one. The last command, exit, will close the shell.

git clone https://github.com/fedetft/miosix-kernel.git
exit

Note that there is also a Git GUI in the right click menu, but git is best used from a command line interface, you're on your own if you choose to use git from the GUI.

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

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:

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

Blink a LED

Open the main.cpp file in the top-level directory using Notepad++, 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 DOS shell in the Miosix top-level directory (you can 'Shift+Right click' in the top-level directory and choose 'Open command window here' in modern versions of Windows), otherwise you will have to cd your way into that directory.

To compile the kernel type make in the DOS prompt. If all goes well, the result should look like this.

Otherwise, compiler errors will appear in the DOS prompt. 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

There are two ways to program the stm32f4discovery board. One is to use QSTLink2 directly from the DOS prompt you already have open by typing 'make program' (connect the USB cable first!), the other is through QSTLink2's GUI. You can find QSTLink2 in the start menu

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 DOS prompt or the GUI, there is a bug that in some circumstances blocks the microcontroller until the next powercycle. Therefore, after having programmed the microcontroller, it is recomended to unplug and reconnect the USB cable to powercycle the stm32f4discovery board. At that point, you shuold see the red LED blinking.

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 Miosix Toolchain

To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under Miosix Toolchain. Note that Git, Perl and the STLink drivers have their own uninstallers. Also, the miosix-kernel in the Documents directory will not be removed.