search

tum-ei-eda / mlonmcu

Tool for the deployment and analysis of TinyML applications on TFLM and MicroTVM backends
Apache License 2.0
29 stars 13 forks source link

readme

ML on MCU

pypi package readthedocs coverage GitHub license

cicd workflow lint workflow demo workflow bench workflow

This project contains research code related to the deployment of inference or learning applications on tiny micro-controllers.

Features

Getting started

Prerequisites

Ubuntu/Debian

First, a set of APT packages needs to be installed:

# Python related
sudo apt install python3-pip python3-venv

# MLonMCU related
sudo apt install libboost-all-dev graphviz doxygen libtinfo-dev zlib1g-dev texinfo unzip device-tree-compiler tree g++

# Optional (depending on configuration)
sudo apt install ninja-build flex lsb-release libelf-dev

Also make sure that your default Python is at least v3.7. If the python command is not available in your shell or points Python v2.7 check out python-is-python3.

Warning: It seems like the ETISS tool fails to compile if if find a version of LLVM 11 on your system which does not include Clang 11. The best workaround for now is to (if possible) remove those tools from your system: sudo apt remove llvm-11* clang-11* (See issue #1)

Make sure to use a fresh virtual Python environment in the following steps.

Install Release from PyPI

Warning: As the PyPI package is not always up to date, it is currently recommented to use a self-build version of the package (as explained in the next section)

To use the PIP package, run the following: pip install mlonmcu (Add --user if you are not using a virtual environment)

Build Package manually

First, install all relevant dependencies:

python -m venv .venv  # Feel free to choose a different directory or use a conda environment

# Run this whenever your have updated the repository
source .venv/bin/activate

# Environment-specific dependencies are installed later

**Warning:** It is recommended to have at least version 3.20 of CMake installed for full compatibility!

# Install ptional dependecies (only for development)
pip install -r requirements_dev.txt
pip install -r docs/requirements.txt

# Only if you want to use the provided python notebooks, as explained in  ./ipynb/README.md
pip install -r ipynb/requirements.txt

Then you should be able to install the mlonmcu python package like this

# Optionally remove an older version first: pip uninstall mlonmcu

make install  # Alternative: python setup.py install

Docker (Any other OS)

See ./docker/README.md for more details.

This repository ships three different types of docker images based on Debian:

Usage

Is is recommended to checkout the provided Demo Jupyter Notebook as it contains a end-to-end example which should help to understand the main concepts and methodology of the tool. The following paragraphs can be seen as a TL;DL version of the information in that Demo notebook.

While some tools and features of this project work out of the box, some of them require setting up an environment where additional dependencies are installed. This can be achived by creating a MLonMCU environment as follows:

mlonmcu init

Make sure to point the MLONMCU_HOME environment variable to the location of the previously initialied environment. (Alternative: use the default environment or --home argument on the command line)

Next, generate a requirements_addition.txt file inside the environment directory using mlonmcu setup -g which now be installed by running pip install -r $MLONMCU_HOME/requirements_addition.txt inside the virtual Python environment.

To use the created environment in a python program, a MlonMcuContext needs to be created as follows:

import mlonmcu.context

with mlonmcu.context.MlonMcuContext() as context:
    pass

List of interesting MLonMCU forks

List of existing MLonMCU extensions/plugins

Development

Make sure to first install the additonal set of development Python packages into your virtual environment:

pip install -r requirements_all.txt  # Install packages for every component (instead of using mlonmcu setup -g)
pip install -r requirements_dev.txt  # Building distributions and running tests
pip install -r docs/requirements.txt  # For working with the documentation

Unit test and integration test are defined in the tests/ directory and can be triggered using make test or pytest tests/

Coverage can be determined by running make coverage. The latest coverage report (HTML) for the default branch can also be found as an artifact of the CI/CD workflow.

Documentation is mainly generated automatically from doctrings (triggered via make html). It is also possible to include markdown files from the repo into the .rst files found in the docs/ directory. There is a GitHub workflow which publishes the documentation for the default branch to our GitHub Pages.

Regarding coding style, it is recommended to run black before every commit. The default line length should be given in the setup.cfg file.

Developers

Publications

Other

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template. However most of the templates was manually changed to be in Markdown instead of reStructuredText.

Acknowledgment

drawing

This research is partially funded by the German Federal Ministry of Education and Research (BMBF) within the projects Scale4Edge (grant number 16ME0127) and MANNHEIM-FlexKI (grant number 01IS22086L).