Micropython integration for the emlearn Machine Learning library for microcontrollers.

The goal is to enable applications to run ML inference on the microcontroller, without having to touch any C code.

Minimally useful

• Can perform classification with RandomForest/DecisionTree models
• Installable as a MicroPython native module. No rebuild/flashing needed
• Models can be loaded at runtime from a .CSV file in disk/flash
• Pre-built modules are available for the most common architectures/devices
• Has been tested on armv6m (RP2040) and x64 (Unix port)

Minimally you will need

• Python 3.10+ on host
• MicroPython running onto your device

Download the repository with examples etc

git clone https://github.com/emlearn/emlearn-micropython

Identify which CPU architecture your device uses. You need to specify ARCH to install the correct module version.

Download from releases.

Copy the .mpy file for the correct ARCH to your device.

mpremote cp emltrees-$ARCH.mpy :emltrees.mpy

NOTE: If there is no ready-made build for your device/architecture, then you will need to build the .mpy module yourself.

NOTE: Make sure to install the module first.

Train a model with scikit-learn

pip install emlearn scikit-learn
python examples/xor_train.py

Copy model file to device

mpremote cp xor_model.csv :xor_model.csv

Run program that uses the model

mpremote run examples/xor_run.py

UCI ML hand-written digits datasets dataset from sklearn.datasets.load_digits. 8x8 image, 64 features. Values are 4-bit integers (16 levels). 10 classes.

Running with a very simple RandomForest, 7 trees. Reaches approx 86% accuracy. Tested on Raspberry PI Pico, with RP2040 microcontroller (ARM Cortex M0 @ 133 MHz).

NOTE: over half of the time for emlearn case, is spent on converting the Python lists of integers into a float array. Removing that bottleneck would speed up things considerably.

These come in addition to the prequisites described above.

Make sure you have the dependencies needed to build for your platform. See MicroPython: Building native modules.

We assume that micropython is installed in the same place as this repository. If using another location, adjust MPY_DIR accordingly.

Build the .mpy native module

make -C eml_trees/ ARCH=x64 MPY_DIR=../../micropython

Install it on device

mpremote cp emltrees/emltrees.mpy :emltrees.mpy

TODO: implement and document

If you use emlearn-micropython in an academic work, please reference it using:

@misc{emlearn_micropython,
  author       = {Jon Nordby},
  title        = {{emlearn-micropython: Efficient Machine Learning engine for MicroPython}},
  month        = aug,
  year         = 2023,
  doi          = {10.5281/zenodo.8212731},
  url          = {https://doi.org/10.5281/zenodo.8212731}
}