Windows)

emlearn-micropython runs on most platforms that MicroPython does. This includes common desktop platforms such as Linux, Mac OS, Windows, et.c. Since you need such a host platform to develop the Python machine-learning, it is convenient also to do the first tests of the model on the host.

1.1. Prerequisites

You need to have installed Python (version 3.10+), and a C99 compiler for your platform (GCC/Clang/MSVC).

On Windows, the Windows Subsystem for Linux (WSL) is recommended.

1.2. Install scikit-learn

In this example, scikit-learn is used to train the models.

pip install scikit-learn

1.3. Install emlearn

The emlearn Python package will be used to convert the scikit-learn models to something that can be loaded with emlearn-micropython.

pip install emlearn

1.4. Install MicroPython Unix port

We need to have the micropython interpreter installed.

Install the Unix port of MicroPython by following the unix port documentation

1.5. Install emlearn-micropython modules

emlearn-micropython is distributed as a set of MicroPython native modules. These are .mpy file with native code, that can be installed at runtime using mip. This example uses the emlearn_trees module, so that is what we will install.

micropython -m mip install https://emlearn.github.io/emlearn-micropython/builds/latest/x64_6.3/emlearn_trees.mpy

1.6. Create model in Python

We will train a simple model to learn the XOR function. The same steps will be used for model of any complexity. Copy and save this as file xor_train.py.

# python/host code

import emlearn
from emlearn.preprocessing import Quantizer
import numpy
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import get_scorer

# Generate simple dataset
def make_xor(lower=0.0, upper=1.0, threshold=0.5, samples=100, seed=42):
    rng = numpy.random.RandomState(seed)
    X = rng.uniform(lower, upper, size=(samples, 2))
    y = numpy.logical_xor(X[:, 0] > threshold, X[:, 1] > threshold)
    X = Quantizer(max_value=1.0).fit_transform(X) # convert to int16
    return X, y

X, y = make_xor()

# Train a model
estimator = RandomForestClassifier(n_estimators=3, max_depth=3, max_features=2, random_state=1)
estimator.fit(X, y)
score = get_scorer('f1')(estimator, X, y)
assert score > 0.90, score # verify that we learned the function

# Convert model using emlearn
cmodel = emlearn.convert(estimator, method='inline')

# Save as loadable .csv file
path = 'xor_model.csv'
cmodel.save(file=path, name='xor', format='csv')
print('Wrote model to', path)

Run the script

python xor_train.py

It will generate a file xor_model.csv containing the C code for our model.

1.7. Use in MicroPython code

To run our model we use a simple MicroPython program.

Copy and save this as file xor_run.py.

# device/micropython code

import emlearn_trees
import array

model = emlearn_trees.new(5, 30, 2)

# Load a CSV file with the model
with open('xor_model.csv', 'r') as f:
    emlearn_trees.load_model(model, f)

# run it
max_val = (2**15-1) # 1.0 as int16
examples = [
    array.array('h', [0, 0]),
    array.array('h', [max_val, max_val]),
    array.array('h', [0, max_val]),
    array.array('h', [max_val, 0]),
]

out = array.array('f', range(model.outputs()))
for ex in examples:
    model.predict(ex, out)
    result = out[1] > 0.5
    print(list(ex), '->', list(out), ':', result)

1.8. Try it out

In our training data input values above 2**14 is considered “true”. So for the XOR function, if one and only one of the values is above this limit, should get class 1 as output - else class 0.

Run the program using micropython:

micropython xor_host.py

The output should be something like:

[0, 0] -> [1.0, 0.0] : False
[32767, 32767] -> [0.666, 0.333] : False
[0, 32767] -> [0.0, 1.0] : True
[32767, 0] -> [0.0, 1.0] : True

1.9. Next

Now you have the emlearn-micropython running on your PC. You may be interested in trying it out on a hardware device. See for example Getting started on device (ESP32/RP2/STM32/etc).