2. Getting started on hardware (Arduino)

emlearn works on any hardware that has C99 support. One very easy way to start testing it out is using the Arduino platform.

2.1. Prerequisites

Ensure that you have emlearn setup as per the Getting started on PC (Linux/MacOS/Windows).

You will also need to have the Arduino IDE installed, and some Arduino-compatible hardware.

Any Arduino compatible board should work, as the code only uses basic I/O functions such as digitalRead() / analogRead() and digitalWrite().

2.2. Create Arduino project

To run our model we use a simple Arduino sketch. It reads data from digital/analog inputs, and shows the output of the model on a LED.

Open the Arduino IDE, and create a new sketch. Save the sketch to a folder, for example emlearn_helloworld_xor.

Replace the sketch code in the Arduino IDE with the contents of the following.

#include "xor_model.h"

const int ledPin = LED_BUILTIN;
const int digitalPinA = 9;
const int digitalPinB = 8;
const int analogPinA = A1;
const int analogPinB = A2;


void setup() {
  pinMode(ledPin, OUTPUT); 
  pinMode(digitalPinA, INPUT_PULLUP); 
  pinMode(digitalPinB, INPUT_PULLUP); 
}

// Read values into range 0-255
uint8_t readAnalog(const int pin) {
    return analogRead(pin) / (1023/255);
}
uint8_t readDigital(const int pin) {
    return digitalRead(pin) ? 255 : 0;
}


void loop() {

#if 1
  // use digital pins
  const uint8_t a = readDigital(digitalPinA);
  const uint8_t b = readDigital(digitalPinB);
#else
  // use analog pins
  const uint8_t a = readAnalog(analogPinA);
  const uint8_t b = readAnalog(analogPinB);
#endif
  const int16_t features[] = { a, b };

  const int32_t out = xor_model_predict(features, 2);

  if (out < 0) {
    Serial.println("ERROR");
  } else {
    Serial.print("Output class:");
    Serial.println(out);
  }
  digitalWrite(ledPin, out == 1 ? HIGH : LOW);
  delay(100);
}

Wait with compiling, as we will need the generated C code from the next step.

2.3. Create model in Python

We will train a simple model to learn the XOR function. Copy and save this as file xor_train.py.

import emlearn
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)
    # convert to int16 with a 8 bit range. [0.0-1.0] -> [0-255]
    X = (X * 255).astype(numpy.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
path = 'xor_model.h'
cmodel = emlearn.convert(estimator, method='inline')
cmodel.save(file=path, name='xor_model')
print('Wrote model to', path)

Run the script

python xor_train.py

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

2.4. Copy model files into Arduino

Copy the xor_model.h file into your sketch folder.

2.5. Install emlearn as Arduino library

Run the following code to install the emlearn library into the Arduino library folder.

python -m emlearn.arduino.install

It should output something like “Installed emlearn to C:\UsersmeDocumentsArduinolibrariesemlearn”. Note that the exact path will vary based on your username and operating system.

2.6. Build and upload the code

Now that the sketch code and the included files are in place, you can do Upload in the Arduino IDE.

2.7. Test it out

The XOR function, if one and only one input is true, should get class 1 as output - else class 0. In our XOR training data input values above 0.5 is considered “true”. For an analog pin that means above halfway in its voltage range. For a digital pin there are only two possible states. High is true, and low is false.

The following should output 1 (LED on)

A     B
high  low
low   high

The following should output 0 (LED off)

A     B
high  high
low   low

2.8. Next

Now that you have tested emlearn on some real hardware, you are ready to develop your application for your particular hardware.