Custom CatBoost ML block examples for Edge Impulse

This repository is an example on how to add a custom learning block to Edge Impulse. This repository contains a CatBoost classifier and a CatBoost regression model.

As a primer, read the Custom learning blocks page in the Edge Impulse docs.

Running the pipeline

You run this pipeline via Docker. This encapsulates all dependencies and packages for you.

Running via Docker

1. Install Docker Desktop.

2. Install the Edge Impulse CLI v1.16.0 or higher.

3. We need an Edge Impulse project with some data. Preferably create a new one and upload your own data, or alternatively:

   Classifier

   Clone a classification project, e.g. Tutorial: continuous motion recognition

   Regression

   Clone a regression project, e.g. Tutorial: temperature regression

4. If you've created a new project, then under Create impulse add a processing block, and either a Classification or Regression block (depending on your data).

5. Open a command prompt or terminal window.

6. Initialize the block:

   Classifier

   cd classifier
   $ edge-impulse-blocks init
   # Answer the questions:
   # ? Choose a type of block: "Machine learning block"
   # ? Choose an option: "Create a new block"
   # ? Enter the name of your block: "CatBoost classifier"
   # ? What type of data does this model operate on? "Classification"
   # ? Where can your model train? "Both CPU or GPU (default)"
   

   Regression

   cd regression
   $ edge-impulse-blocks init
   # Answer the questions:
   # ? Choose a type of block: "Machine learning block"
   # ? Choose an option: "Create a new block"
   # ? Enter the name of your block: "CatBoost regression"
   # ? What type of data does this model operate on? "Regression"
   # ? Where can your model train? "Both CPU or GPU (default)"
   

7. Fetch new data via:

   $ edge-impulse-blocks runner --download-data data/
   

8. Build the container:

   Classifier

   $ cd classifier
   $ docker build -t catboost-classifier .
   

   Regression

   $ cd regression
   $ docker build -t catboost-regression .
   

9. Run the container to test the script (you don't need to rebuild the container if you make changes):

   Classifier

   $ docker run --rm -v $PWD:/app catboost-classifier --data-directory /app/data --out-directory /app/out
   

   Regression

   $ docker run --rm -v $PWD:/app catboost-regression --data-directory /app/data --out-directory /app/out
   

10. This creates a model.json and a model.cpp file in the out directory.

C++ deployment

CatBoost can export a trained model as standalone C++ source, which is useful for on-device deployment (e.g. alongside the Edge Impulse SDK). The training scripts write this to model.cpp in the out directory via:

clf.save_model('model.cpp', format='cpp')

The generated file is self-contained (the model weights are baked in as static arrays) and exposes a single function — no CatBoost runtime is required at inference time:

double ApplyCatboostModel(const std::vector<float>& floatFeatures);
// multiclass exposes an overload returning std::vector<double>

Pass your feature vector in the same order and length used during training. The returned value is the raw prediction (the leaf-sum / margin), not a probability. Post-process depending on the mode:

• Regression: the returned double is the prediction directly.
• Binary classifier: apply a sigmoid to get a probability — 1.0 / (1.0 + exp(-raw)).
• Multiclass classifier: use the vector-returning overload, then apply softmax over the returned scores and take the argmax for the predicted class.

Note: ONNX export (format='onnx') is not used here because the Edge Impulse SDK does not implement the TreeEnsembleRegressor operator required to run the exported graph.

Adding extra dependencies

If you have extra packages that you want to install within the container, add them to requirements.txt and rebuild the container.

Adding new arguments

To add new arguments, see Custom learning blocks > Arguments to your script.

Fetching new data

To get up-to-date data from your project:

1. Install the Edge Impulse CLI v1.16 or higher.

2. Open a command prompt or terminal window.

3. Fetch new data via:

   $ edge-impulse-blocks runner --download-data data/
   

Pushing the block back to Edge Impulse

You can also push this block back to Edge Impulse, that makes it available like any other ML block so you can retrain your model when new data comes in, or deploy the model to device. See Docs > Adding custom learning blocks for more information.

1. Push the block:

   $ edge-impulse-blocks push
   

2. The block is now available under any of your projects via Create impulse > Add new learning block.