Skip to content

Explore the Examples

To get a quick feel about modm's APIs you can look at and experiment with our examples, especially if you have a development board that modm supports out-of-box.

Make sure you've installed all tools required for building modm and you've cloned the modm repository recursively:

git clone --recurse-submodules --jobs 8 https://github.com/modm-io/modm.git

TL;DR

Change directory into any of the examples and compile it:

# cd into any example you like
cd modm/examples/gpio/blinky
# generate modm library (call only once)
lbuild build
# compile the example
scons -j8
# Connect your development board and upload the firmware
scons program

To debug with GDB in TUI mode. Make sure to change to the debug profile:

# compile and upload debug profile
scons program profile=debug
# launch OpenOCD and GDB for debugging
scons debug profile=debug

To generate your target specific Doxygen documentation:

(cd modm/docs && doxygen doxyfile.cfg)
# open modm/docs/html/index.html

To remove it all:

# Remove build artifacts
scons -c
# Remove generated files
lbuild clean

Have a look at the build system documentation and the online documentation.

Structure

The examples are sorted by what they show, not by the board they run on:

Folder Examples for
core Fibers, assertions, fault handling, allocators, internal flash, DMA, watchdogs, debug channels.
gpio Blinking LEDs, buttons, ports, external interrupts.
analog Internal ADCs, DACs and comparators.
timer Timers and PWM.
logging Logging and printing via UART.
can CAN and FDCAN peripherals.
driver External devices, sorted like modm:driver: sensors, displays, radios, LEDs and more.
ui Graphics, GUI and animations on the displays of the boards.
communication Protocols: AMNB, SAB, XPCC, Ethernet.
ext External libraries: FreeRTOS, TinyUSB, LVGL, ETL, nanopb and more.

The driver folder has the same categories as the modm:driver modules in src/modm/driver, for example driver/inertial/bmi270 or driver/display/ssd1306.

An example that runs on several boards lists all of them in its project.xml. The suffix of an example like analog/dac_dma_g4 names the device family or platform that this example is specific to.

Examples that do not depend on a specific peripheral compile for one board of every CPU core: AVR, Cortex-M0, M0+, M3, M4F, M7, M33 and hosted. Each example uses different boards for this, so that all boards are compiled by some example.

Choosing Your Board

Most examples run on several boards. Their project.xml lists all of them and you choose yours by moving the comment:

<library>
  <extends>modm:nucleo-l476rg</extends>
  <!-- <extends>modm:blue-pill-f103</extends> -->
  <!-- <extends>modm:hosted</extends> -->
  <options>
    <!-- Required for modm:blue-pill-f103 -->
    <!-- <option name="modm:build:openocd.cfg">interface/stlink.cfg</option> -->
  </options>
  <modules>
    <!-- Required for modm:nucleo-l476rg -->
    <module>modm:platform:adc:1</module>
    <!-- Required for modm:blue-pill-f103 -->
    <!-- <module>modm:platform:adc:2</module> -->
    <module>modm:build:scons</module>
  </modules>
</library>
  • Every <extends> is one board that this example supports.
  • modm:hosted compiles the example for your computer.
  • A comment that names boards applies to the lines directly below it: these options, collectors and modules are only for these boards. If you switch boards, also switch which of these lines are commented out.
  • All other lines apply to every board.

Our CI reads the same comments to compile every example for all of its boards:

# compile one example for all of its boards
python3 tools/scripts/examples_compile.py examples/gpio/blinky
# compile all examples, but only for AVR targets
python3 tools/scripts/examples_compile.py examples --target '^at'

Projects that test or benchmark modm rather than show how to use it are located in test/integration.

Noteworthy Examples

We have hundreds of examples, here are some of our favorite ones:

Copy Carefully

When copying from our examples make sure to set the repository path correctly! All example modm/examples/**/project.xml files are missing this path, since we set it in the inherited base modm/examples/lbuild.xml configuration. You must also add the modm:docs module manually if you want it.

The modm/examples/lbuild.xml file:

<library>
  <!-- This is the default lbuild configuration file for every
       example in this folder. It only defaults the common settings,
       so that this isn't duplicated in every single example.
       When you write your own application, you must set this
       path yourself! -->
  <repositories>
    <repository><path>../repo.lb</path></repository>
  </repositories>
  <modules>
    <module>modm:docs</module>
  </modules>
</library>