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/generic/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 Doxypress documentation:

(cd modm/docs && doxypress doxypress.json)
# 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.

Interesting Examples

We have hundreds of examples but here are some of our favorite ones for our supported development boards:

• Arduino Uno: Blinky, Button & Serial, Analog & Serial.
• NUCLEO-F031K6: Blinky & Serial.
• NUCLEO-F103RB: Blinky & Serial, Undefined IRQ Handler, Logging via ITM.
• NUCLEO-F429ZI: CMSIS DSP.
• NUCLEO-F446RE: Internal Flash Programming.
• STM32F072 Discovery: Blinky, CAN, Gyroscope.
• STM32F3 Discovery: Blinky, CAN, Accelerometer, Gyroscope, TinyUSB DFU, Logging via RTT.
• STM32F4 Discovery: Blinky, CAN, Accelerometer, Timer & LED Animations.
• STM32F469 Discovery: Blinky, Drawing on display, Touchscreen inputs, Multi-heap with external 16MB memory, Game of Life in Color with Multitouch, Hard Fault with CrashCatcher
• STM32F769 Discovery: FPU with double precision

Here are some additional examples of displays and sensors we like:

• SSD1306 OLED display: Draws text and graphics onto I2C display.
• BMP085/BMP180 barometer: Reads atmospheric pressure and temperature from I2C sensor.
• BMP180/BME280 barometer: Reads atmospheric pressure and temperature from multiple I2C sensors.
• VL6180 time-of-flight distance sensor: Reads distance and ambient light from I2C sensor.
• VL53L0 time-of-flight distance sensor: Much improved version of the VL6180 sensor.
• ADNS9800 motion sensor: Reads 2D motion from SPI sensor used in gaming mice.
• TCS3414 color sensor: Reads RGB color from I2C sensor.
• HD44780 over I2C-GPIO expander: Draws text via native GPIO port or I2C-GPIO expander port onto character display.

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>