Skip to content

Installation

This is the required software for generating, compiling and programming projects with modm:

Note that the modm examples use the SCons build system by default, however, you are not required to use it. See the reference manual for additional build system documentation.

Use GCC 12 or newer

modm uses C++23, so you need at least GCC 12, we recommend GCC 13.

Beware of AVRs

We strongly discourage using AVRs for new designs, due to a significant lack of commitment from Atmel on keeping their AVR toolchain up-to-date.

Check your Locale

If you get a UnicodeEncodeError when calling lbuild, you may need to add export LC_ALL=C.UTF-8 to your .bashrc. Consult the internet until python3 -c "import sys; print(sys.stdout.encoding)" returns UTF-8.

Please help us keep these instructions up-to-date!

Linux

For Ubuntu 24.04LTS, these commands install the minimal build system:

sudo apt install python3 python3-pip scons git libncursesw6
pip3 install modm

We recommend using a graphical frontend for GDB called gdbgui:

pip3 install gdbgui

Python Packages in PATH

The pip3 command installs executables into ~/.local/bin, which must be added to PATH if it is not already the case. Add the following line to the end of your ~/.bashrc file:

export PATH="$HOME/.local/bin:$PATH"

We use Doxypress to generate the API documentation:

sudo mkdir /opt/doxypress
wget -O- https://github.com/copperspice/doxypress/releases/download/dp-1.7.0/doxypress-1.7.0-ubuntu24.04-x64.tar.bz2 | sudo tar xj -C /opt/doxypress

Add the directory to your PATH variable in ~/.bashrc:

export PATH="/opt/doxypress:$PATH"

ARM Cortex-M

Install the GNU toolchain for arm-none-eabi target in version 12 (or higher). If your Linux distribution provides up-to-date packages, we recommend using them. Otherwise, including Ubuntu 24.04, we recommend using the xPack GNU Arm Embedded GCC binary distribution:

wget -O- https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases/download/v13.3.1-1.1/xpack-arm-none-eabi-gcc-13.3.1-1.1-linux-x64.tar.gz | sudo tar xz -C /opt/

Add it to your PATH variable in ~/.bashrc:

export PATH="/opt/xpack-arm-none-eabi-gcc-13.3.1-1.1/bin:$PATH"

Install the OpenOCD tool:

sudo apt install openocd

OpenOCD < v0.12

Make sure to get at least OpenOCD release v0.12, since v0.11 is too old for some targets (STM32L5, STM32U5). You can manually install an up-to-date version of OpenOCD by following the instructions here.

Microchip AVR

Download and extract the pre-built AVR toolchain:

wget -O- https://github.com/modm-io/avr-gcc/releases/download/v13.2.0/modm-avr-gcc.tar.bz2 | sudo tar xj -C /opt

AVR toolchain install directory

It is unfortunately not possible to install the AVR toolchain into a directory other than directly into /opt.

Add the bin directory to your PATH variable in ~/.bashrc:

export PATH="/opt/avr-gcc/bin:$PATH"

Install the AvrDude tool:

sudo apt install avrdude

Hosted

To compile modm for host system targets (x86_64/arm64):

sudo apt install gcc build-essential libboost-all-dev

macOS

Install the minimal build system via Homebrew:

brew update
brew install python3 scons git doxygen
pip3 install modm

Missing pyelftools

If you get errors about missing pyelftools when calling scons, you may be using the system Python, rather than the Homebrew Python. In that case, you can add this line to your .bashrc or .zshrc:

alias scons="/usr/bin/env python3 $(which scons)"

We recommend using a graphical frontend for GDB called gdbgui:

pip3 install gdbgui

We use Doxypress to generate the API documentation:

brew tap modm-ext/modm
brew install doxypress

ARM Cortex-M

Install the pre-built ARM toolchain:

brew tap osx-cross/arm
brew install arm-gcc-bin@13 openocd
brew link --force arm-gcc-bin@13

To program Microchip SAM devices via the bootloader, install the bossac tool:

brew cask install bossa

Microchip AVR

Install the AVR toolchain from source:

brew tap osx-cross/avr
brew install avr-gcc@13
brew link --force avr-gcc@13

Hosted

To compile modm for x86_64 macOS you need to install these tools too:

brew install boost gcc

Windows

In general, Windows is not a great fit for the command line tools that modm is built on. Consider using the Windows subsystem for Linux 2 (WSL2) instead. Alternatively consider using a better terminal emulator than command prompt (cmd) or PowerShell, perhaps use the official Windows Terminal.

Debugging with arm-none-eabi-gdb

We could not get arm-none-eabi-gdb to work on Windows, it seems not to support TUI mode and the web-based GDBGUI does not support Windows either. If you find a solution, please open a PR so we can fix this.

These instructions assume a vanilla Windows 10 installation.

Install Git via the official installer. Make sure to unselect vim as the default Git editor and instead choose at least the Wordpad editor or better.

Install Python3 via the full installer. Make sure to select Add Python to PATH during installation!

Test the installation by opening the command prompt (cmd):

python -c "print('Hello World')"

Then install the necessary Python packages:

pip install modm scons

Test that you have access to the lbuild and scons tools inside the command prompt:

lbuild --version
scons --version

We use Doxypress to generate the API documentation. Download and run the Installer.

Please use the free and open-source 7-Zip file archiver to extract the files in the next steps.

ARM Cortex-M

Install the pre-built ARM toolchain via the 64-bit installer and make sure you select Add path to environment variable at the end! Open a new command prompt to test the compiler:

arm-none-eabi-gcc --version

Install the and then download the latest pre-built OpenOCD tool:

Unpack the .7z file using 7-Zip > Extract to "OpenOCD-20240916...".

Then rename and move the extracted folder to C:\Program Files (x86)\openocd. Open PowerShell to add the \bin folder to the Path:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files (x86)\openocd\bin", "User")

Close the PowerShell and open a new command prompt to test openocd:

openocd --version

Microchip AVR

Download the pre-built AVR toolchain and unpack the .zip file using the context menu 7-Zip > Extract to "avr-gcc-13.2.0-..." Then rename and move the extracted folder to C:\Program Files\avr-gcc. Open PowerShell to add the \bin folder to the Path:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\avr-gcc\bin", "User")

Close the PowerShell and open a new command prompt to test avr-gcc and avrdude:

avr-gcc --version
avrdude --version

For non-English speakers

For now project and build paths containing non-ASCII characters are not parsed correctly. Please open an issue if this is a problem.

Windows paths

Windows created several compatibility issues with its \ path separator. Even though we try hard to not hardcode the path separator, there may still be issues related to this. Please open an issue in that case.

Dear Windows users

We don't regularly use Windows with modm, so please give us some feedback about the quality of these instructions.

Windows with WSL2

The Windows Subsystem for Linux 2 allows you to run a Linux distribution in parallel to Windows. For a pure Windows installation see above.

Install Ubuntu-22.04 LTS as WSL2 distribution: See the general WSL doc, but as of this writing wsl --list --online will not list Ubuntu 22.04.1 LTS, but it is available in the Microsoft Store. Install it from there via mouse clicks. Make sure the WSL2 instance is running by opening a terminal via start menu.

Physically attach your microcontroller development board or your debugger to a USB port and bridge the USB hub to which the device is attached. Also bridge the USB device to Linux using usbipd:

PS C:\Windows\system32> usbipd wsl list
BUSID  VID:PID    DEVICE                                STATE
3-2    1bcf:0005  USB-Eingabegerät                      Not attached
3-3    0483:374b  ST-Link Debug, USB-...                Attached - Ubuntu-22.04
4-1    138a:003d  Synaptics FP Sensors (WBF) (PID=003d) Not attached
4-3    04f2:b370  HP HD Webcam [Fixed]                  Not attached

Check the BUSID parameter and use the one that corresponds to your device in further commands. In this example it is the 3-3.

PS C:\Windows\system32> usbipd wsl attach --busid 3-3
usbipd: info: Using default distribution 'Ubuntu-22.04'.

Unreliable connection

If the connection is not reliable, it might be necessary to detach/attach several times until the connection is established:

PS C:\Windows\system32> usbipd wsl detach --busid 3-3
PS C:\Windows\system32> usbipd wsl attach --busid 3-3
usbipd: info: Using default distribution 'Ubuntu-22.04'.

Either reboot the machine or be lucky that a combination of the following commands is sufficient:

sudo udevadm trigger
sudo udevadm control --reload

Remove the USB connector, reattach it, then issue the command usbipd wsl attach --busid 3-3.

On WSL2 Linux follow the Linux installation instructions and additionally install a terminal emulator such as picocom:

sudo apt install picocom

Explore the examples and compile and upload a suitable one with scons program. Try to debug it with GDB using scons debug and listen on the serial output:

picocom --baud 115200 --imap lfcrlf --echo /dev/ttyACM0

VSCode support

You can also install the remote extensions for WSL and use the VSCode integrated terminal to access WSL2.