DOCSEARCHbyAlgolia
Submit Docs

emlearn MicroPython

repository·master·Indexed 41 days ago

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

A TinyML library providing Machine Learning and Digital Signal Processing modules for MicroPython. It enables efficient model inference on microcontrollers without C programming, featuring support for tree-based models, CNNs (via TinyMaix), and IIR filters for applications such as Human Activity Recognition (HAR), MNIST digit classification, and sound level metering.

Tokens
18.8K
Snippets
65
Records
101
Agent score
51%

What's inside emlearn-micropython

  1. Overview of emlearn-micropython

    master

    emlearn-micropython is a TinyML library designed for Machine Learning and Digital Signal Processing (DSP) on MicroPython. It allows developers to run efficient models on microcontrollers without writing C code. It is built on top of the emlearn C99 library and is optimized for low-complexity, low-power classification tasks.

    Key Capabilities:

    • Classification: RandomForest, DecisionTree, K-Nearest Neighbors (KNN), and Convolutional Neural Networks (CNN) via TinyMaix.
    • Regression: Linear Regression and Partial Least Squares Regression (PLSR).
    • DSP & Preprocessing: Fast Fourier Transform (FFT), Infinite Impulse Response (IIR) filters, and scaling/transformations via emlearn_arrayutils.
    • Clustering: K-means.
    • On-device Learning: Supported for KNN, Linear Regression, and Extremely Randomized Trees (extratrees).

    Performance Characteristics:

    • Inference times as low as 100 microseconds.
    • RAM usage < 2 kB.
    • FLASH usage < 2 kB.
    • Operates on standard array.array data structures.

  2. Overview of the Sound Level Meter implementation

    master

    The Sound Level Meter is a MicroPython implementation using emlearn-micropython designed for basic sound measurements and noise monitoring.

    Key Features

    The soundlevels.py module provides:

    • Decibel SPL calculation using a digital microphone.
    • Frequency Weighting: Supports A weighting or no weighting ("Z").
    • Time Integration: Supports Fast (125ms), Slow (1s), or no integration.
    • Instantaneous & Summarized Measurements: Includes short Leq, equivalent sound pressure level (Leq), minimum (Lmin), maximum (Lmax), and percentile-based summarizations (L10, L50, L80, etc.).
    • Sample Rate: Optimized for 16 kHz.

    Implementation Details

    • Uses emlearn_iir for A-weighting filters.
    • Uses emlearn_arrayutils.linear_map() to convert between float and int16 arrays.

    Accuracy Notes

    • Microphone Sensitivity: Must be correctly specified for reasonable output.
    • Hardware Limitations: There is no compensation for non-linear frequency responses in the microphone. Processing is done largely in int16, which limits dynamic range.
    • Use Case: Best for tracking relative changes rather than absolute regulatory thresholds.

  3. Construct the URL for prebuilt native modules

    master

    Prebuilt modules are hosted over HTTPS. You can construct the download URL using the following pattern:

    https://emlearn.github.io/emlearn-micropython/builds/$VERSION/$ARCH_$ABI/$MODULE.mpy

    Where:

    • $VERSION: latest or a specific version like 0.10.0
    • $ARCH: The architecture identifier (e.g., xtensawin)
    • $ABI: The MicroPython ABI version (e.g., 6.3)
    • $MODULE: The module name (e.g., emlearn_trees)

    Example URL for emlearn_trees on xtensawin with ABI 6.3 using the latest version:
    https://emlearn.github.io/emlearn-micropython/builds/latest/xtensawin_6.3/emlearn_trees.mpy

    https://emlearn.github.io/emlearn-micropython/builds/$VERSION/$ARCH_$ABI/$MODULE.mpy

  4. Understand the mdarray concept for multi-dimensional data

    master

    The mdarray (multi-dimensional array) is a proposed data representation designed to enable interoperability between different MicroPython modules (like image processing, signal processing, and machine learning) without unnecessary data copying.

    Unlike ulab.ndarray, which is a specific library implementation, mdarray is envisioned as a standard way to represent multi-dimensional data structures. It focuses strictly on data representation rather than high-level operations.

    Key Characteristics:

    • Data Layout: Always uses C-order (row-major) layout.
    • Dimensions: Designed to support at least 4 dimensions.
    • Scope: It does not provide high-level convenience features like iterators, operator overloads, slicing, broadcasting, or universal functions. These are expected to be provided by external libraries or specific modules.
    • Memory Efficiency: Aims to allow modifying values and passing arrays between functions without copying the underlying buffer.

  5. Understand hardware support models

    master

    Hardware support in emlearn-micropython depends on how you integrate the modules, due to limitations in MicroPython's support for C modules:

    1. Native Modules (Recommended): The standard way to use emlearn-micropython. This approach provides the best hardware compatibility.
    2. External Modules (Advanced): An alternative integration method for advanced users, which may have different hardware support constraints.

  6. Combine emlearn-micropython with other external modules

    master
    If you need to include additional C modules or a different frozen manifest alongside emlearn-micropython, you cannot use the provided files directly. Instead, you must create your own custom manifest.py and micropython.cmake files. It is recommended to use the files located in emlearn-micropython/src/ as templates for your custom implementation.

  7. Optimize MicroPython code with native decorators

    master

    To improve performance for data-intensive TinyML tasks, MicroPython provides specialized code emitters:

    • @micropython.native: Compiles Python code to native machine code. Note that this does not optimize floating-point code.
    • @micropython.viper: Provides even higher performance, particularly for integer-only code and direct memory manipulation.

    Using these decorators is critical when processing large arrays or performing real-time signal processing.

    @micropython.native
def fast_function(data):
    # Optimized native code
    pass

@micropython.viper
def ultra_fast_function(data):
    # High-performance integer/pointer manipulation
    pass

  8. Handle multi-dimensional arrays and data formats

    master

    When working with sensor data or ML inputs in MicroPython, consider these data handling options:

    • Multi-dimensional Arrays: For storing multi-dimensional arrays, use micropython-npyfile to handle .npy files (supports basic ZIP compression).
    • Fixed Buffers: Use array.array for efficient fixed-size buffers.
      • Warning: Slicing an array.array creates a copy.
      • Tip: For high-performance integer-only code, use the @micropython.native or @micropython.viper decorators.
    • Binary Serialization: Use the core base64 library for encoding binary data into strings for textual protocols (e.g., JSON or USART).

  9. Show soundlevels on an SSD1306 screen

    master

    This example displays real-time sound levels on an SSD1306 display using the micropython-nano-gui framework.

    1. Install emlearn modules (for xtensawin architecture):
    mpremote mip install https://emlearn.github.io/emlearn-micropython/builds/latest/xtensawin_6.3/emlearn_arrayutils.mpy
mpremote mip install https://emlearn.github.io/emlearn-micropython/builds/latest/xtensawin_6.3/emlearn_iir.mpy
    1. Install UI framework and drivers:
    mpremote mip install "github:peterhinch/micropython-nano-gui/drivers/ssd1306"
mpremote mip install "github:peterhinch/micropython-nano-gui"
    1. Copy files and run:
    mpremote cp color_setup.py soundlevel.py :
mpremote run soundlevel_screen.py
    mpremote mip install "github:peterhinch/micropython-nano-gui/drivers/ssd1306"
mpremote mip install "github:peterhinch/micropython-nano-gui"
mpremote cp color_setup.py soundlevel.py :
mpremote run soundlevel_screen.py

  10. Install emlearn-micropython modules on a device

    master

    emlearn-micropython is distributed as native .mpy modules. You can install them at runtime on your MicroPython device using mpremote mip install.

    Choose the URL corresponding to your device's architecture:

    • ESP32 (xtensawin architecture): Use the xtensawin build.
    • ARM Cortex M4F/M33/M7 (armv7emsp architecture): Use the armv7emsp build.

    Ensure you have mpremote installed on your host machine first.

    # For ESP32
mpremote mip install https://emlearn.github.io/emlearn-micropython/builds/latest/xtensawin_6.3/emlearn_trees.mpy

# For ARM Cortex M4F/M33/M7
mpremote mip install https://emlearn.github.io/emlearn-micropython/builds/latest/armv7emsp_6.3/emlearn_trees.mpy

  11. Access emlearn core machine learning documentation

    master

    While emlearn-micropython is the MicroPython implementation, many core machine learning concepts and workflows are documented in the main emlearn documentation. Key topics available include:

    • Feature Extraction: How to transform raw data into features for models.
    • Classification: Techniques for categorizing data.
    • Regression: Techniques for predicting continuous values.
    • Anomaly Detection: Identifying outliers in data.
    • Model Optimization: Strategies to make models efficient for embedded use.
    • Tree-based Models: Information on using decision trees and ensembles.

  12. Set up the emlearn-micropython development environment

    master

    To develop on emlearn-micropython, you need Python 3.10+ and a MicroPython git repository (version 1.28 or newer) located in dependencies/micropython relative to the project root. If your MicroPython directory is elsewhere, adjust the MPY_DIR make variable.

    Prerequisites

    • Python 3.10+
    • MicroPython Unix port: Build and install this to run/test on your PC.
    • Hardware Toolchain: Required if building for specific devices like esp32, stm32, or rp2.

    Installation Steps

    1. Clone the repository:
    git clone https://github.com/emlearn/emlearn-micropython
    1. Fetch submodules:
    git submodule update --init
    1. Install Python dependencies (recommended to use a virtual environment):
    pip install -r requirements.txt
    git clone https://github.com/emlearn/emlearn-micropython
git submodule update --init
pip install -r requirements.txt