{"id":13800781,"url":"https://github.com/emlearn/emlearn-micropython","last_synced_at":"2025-04-05T21:06:41.674Z","repository":{"id":184894812,"uuid":"670384512","full_name":"emlearn/emlearn-micropython","owner":"emlearn","description":"Efficient Machine Learning engine for MicroPython","archived":false,"fork":false,"pushed_at":"2025-03-28T23:12:19.000Z","size":3267,"stargazers_count":116,"open_issues_count":10,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T23:22:06.136Z","etag":null,"topics":["embedded-systems","machine-learning","micropython","python","tinyml"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emlearn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["jonnor"]}},"created_at":"2023-07-25T00:06:42.000Z","updated_at":"2025-03-28T23:05:56.000Z","dependencies_parsed_at":"2023-07-30T20:46:36.092Z","dependency_job_id":"dc52b0f1-ea35-45ad-838c-83c5ed7096fe","html_url":"https://github.com/emlearn/emlearn-micropython","commit_stats":null,"previous_names":["emlearn/emlearn-micropython"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emlearn%2Femlearn-micropython","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emlearn%2Femlearn-micropython/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emlearn%2Femlearn-micropython/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emlearn%2Femlearn-micropython/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emlearn","download_url":"https://codeload.github.com/emlearn/emlearn-micropython/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247399873,"owners_count":20932876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded-systems","machine-learning","micropython","python","tinyml"],"created_at":"2024-08-04T00:01:16.204Z","updated_at":"2025-04-05T21:06:41.653Z","avatar_url":"https://github.com/emlearn.png","language":"Jupyter Notebook","readme":"[![DOI](https://zenodo.org/badge/670384512.svg)](https://zenodo.org/badge/latestdoi/670384512)\n\n# emlearn-micropython\n\nMachine Learning and Digital Signal Processing for [MicroPython](https://micropython.org).\nProvides convenient and efficient MicroPython modules, and enables MicroPython application developers\nto run efficient Machine Learning models on microcontroller, without having to touch any C code.\n\nThis is a [TinyML](https://www.tinyml.org/) library,\nparticularly well suited for low-compexity and low-power classification tasks.\nIt can be combined with feature preprocessing, including neural networks to address more complex tasks.\n\nBuilds on [emlearn](https://emlearn.org), a C99 library for Machine Learning on microcontrollers and embedded system.\n\n\u003e scikit-learn for Microcontrollers\n\n## Status\n**Minimally useful**\n\n- Tested *working* on `x64` (Unix port) and `xtensawin` (ESP32).\n- Currently *broken* on ARM `armv6m` (Cortex M0 / RP2040). [Issue](https://github.com/emlearn/emlearn-micropython/issues/19)\n\n## Features\n\n- Classification with [RandomForest](https://en.wikipedia.org/wiki/Random_forest)/DecisionTree models\n- Classification and on-device learning with [K-Nearest Neighbors (KNN)](https://en.wikipedia.org/wiki/K-nearest_neighbors_algorithm)\n- Classification with Convolutional Neural Network (CNN), using [TinyMaix](https://github.com/sipeed/TinyMaix/) library.\n- [Fast Fourier Transform (FFT)](https://en.wikipedia.org/wiki/Fast_Fourier_transform) for feature preprocessing, or general DSP\n- Infinite Impulse Response (IIR) filters for feature preprocessing, or general DSP\n- Clustering using K-means\n- Scaling and data type transformations for `array`, using `emlearn_arrayutils`.\n- Load/save Numpy .npy files using [micropython-npyfile](https://github.com/jonnor/micropython-npyfile/)\n- Installable as a MicroPython native module. No rebuild/flashing needed\n- Operates on standard `array.array` data structures\n- Models can be loaded at runtime from a file in disk/flash\n- Highly efficient. Inference times down to 100 microseconds, RAM usage \u003c2 kB, FLASH usage \u003c2 kB\n- Pre-built binaries available for most architectures.\n\n## Examples\n\n- [xor_trees](./examples/xor_trees/). A \"Hello World\", using RandomForest.\n- [mnist_cnn](./examples/mnist_cnn/). Basic image classification, using Convolutional Neural Network.\n- [har_trees](./examples/har_trees/). Accelerometer-based Human Activity Recognition, using Random Forest\n- [soundlevel_iir](./examples/soundlevel_iir/). Sound Level Meter, using Infinite Impulse Response (IIR) filters.\n\n## Documentation\n\nComplete [documentation on ReadTheDocs](https://emlearn-micropython.readthedocs.io/en/latest/user_guide.htmls).\n\n## Prerequisites\n\nMinimally you will need\n\n- Python 3.10+ on host\n- MicroPython 1.24+ running onto your device\n\n#### Download repository\n\nDownload the repository with examples etc\n```\ngit clone https://github.com/emlearn/emlearn-micropython\n```\n\n## Usage\n\nStart with the instructions in [XOR example](./examples/xor_trees/).\n\n\n## Supported versions\n\nAt any given point in time, emlearn-micropython only provides pre-built binaries for one MicroPython version.\nIn general we strongly encourage people to use the latest version.\nThere are no long-term-support or bugfix versions, at this point.\nIf you build from source, the current version of emlearn-micropython might also work on a couple of MicroPython versions around the time, but this is not guaranteed.\n\n| MicroPython      | emlearn-micropython  |\n|------------------| ------------------   |\n| 1.24.x           | master               |\n| 1.24.x           | 0.7.0                |\n| 1.23.x           | 0.6.0                |\n\n#### Find architecture and .mpy version\n\nThe correct .mpy files to use depend on the CPU architecture of your microcontroller,\nas well as the MicroPython version.\n\n| MicroPython version | .mpy version  |\n|---------------------| ------------- |\n| 1.23.x              | 6.3           |\n| 1.24.x              | 6.3           |\n\n\nIdentify which CPU architecture your device uses.\nYou need to specify `ARCH` to install the correct module version.\n\n| ARCH          | Description                       | Examples              |\n|---------------|-----------------------------------|---------------------- |\n| x64           | x86 64 bit                        | PC                    |\n| x86           | x86 32 bit                        |                       |\n| armv6m        | ARM Thumb (1)                     | Cortex-M0             |\n| armv7m        | ARM Thumb 2                       | Cortex-M3             |\n| armv7emsp     | ARM Thumb 2, single float         | Cortex-M4F, Cortex-M7 |\n| armv7emdp     | ARM Thumb 2, double floats        | Cortex-M7             |\n| xtensa        | non-windowed                      | ESP8266               |\n| xtensawin     | windowed with window size 8       | ESP32                 |\n\nInformation is also available in the official documentation:\n[MicroPython: .mpy files](https://docs.micropython.org/en/latest/reference/mpyfiles.html#versioning-and-compatibility-of-mpy-files)\n\n\n## More learning resources\n\nemlearn-micropython and emlearn has been covered in the following presentations.\n\n- Microcontrollers + Machine Learning in 1-2-3 (PyData Global 2024).\n[Slides etc](https://github.com/jonnor/embeddedml/tree/master/presentations/PyDataGlobal2024)\n- Sensor data processing on microcontrollers with MicroPython and emlearn (PyConZA 2024).\n[Slides etc](https://github.com/jonnor/embeddedml/tree/master/presentations/PyConZA2024)\n- 6 years of open source TinyML with emlearn - a scikit-learn for microcontrollers (TinyML EMEA 2024)\n[YouTube video](https://www.youtube.com/watch?v=oG7PjPMA3Is) |\n[Slides etc](https://github.com/jonnor/embeddedml/tree/master/presentations/TinymlEMEA2024)\n- emlearn - Machine Learning for Tiny Embedded Systems (Embedded Online Conference 2024).\n[Youtube video](https://www.youtube.com/watch?v=qamVWmcBdmI) |\n[Slides etc](https://github.com/jonnor/embeddedml/tree/master/presentations/EmbeddedOnlineConference2024)\n- Machine Learning on microcontrollers using MicroPython and emlearn (PyCon DE \u0026 PyData Berlin 2024).\n[Slides etc](https://github.com/jonnor/embeddedml/tree/master/presentations/PyDataBerlin2024) |\n[YouTube video](https://www.youtube.com/watch?v=_MGm8sctqjg\u0026t=1311s\u0026pp=ygUSZW1sZWFybiBtaWNyb3B5dGhv).\n\nHere is an overview of resources for [TinyML in general](https://tinyml.seas.harvard.edu/courses/).\n\n## Benchmarks\n\n#### UCI handwriting digits\n\nUCI ML hand-written digits datasets dataset from\n[sklearn.datasets.load_digits](https://scikit-learn.org/stable/modules/generated/sklearn.datasets.load_digits.html).\n8x8 image, 64 features. Values are 4-bit integers (16 levels). 10 classes.\n\nRunning with a very simple RandomForest, 7 trees.\nReaches approx 86% accuracy.\nTested on Raspberry PI Pico, with RP2040 microcontroller (ARM Cortex M0 @ 133 MHz).\n\n![Inferences per second](./benchmarks/digits_bench.png)\n\nNOTE: over half of the time for emlearn case,\nis spent on converting the Python lists of integers into a float array.\nRemoving that bottleneck would speed up things considerably.\n\n\n## Developing locally\n\n#### Prerequisites\nThese come in addition to the prequisites described above.\n\nMake sure you have the dependencies needed to build for your platform.\nSee [MicroPython: Building native modules](https://docs.micropython.org/en/latest/develop/natmod.html).\n\nWe assume that micropython is installed in the same place as this repository.\nIf using another location, adjust `MPY_DIR` accordingly.\n\nYou should be using MicroPython 1.24 (or newer).\n\n#### Build\n\nBuild the .mpy native module\n```\nmake dist ARCH=armv6m MPY_DIR=../micropython\n```\n\nInstall it on device\n```\nmpremote cp dist/armv6m*/emlearn_trees.mpy :emlearn_trees.mpy\n```\n\n#### Run tests\n\nTo build and run tests on host\n```\nmake check\n```\n\n## Citations\n\nIf you use `emlearn-micropython` in an academic work, please reference it using:\n\n```tex\n@misc{emlearn_micropython,\n  author       = {Jon Nordby},\n  title        = {{emlearn-micropython: Efficient Machine Learning engine for MicroPython}},\n  month        = aug,\n  year         = 2023,\n  doi          = {10.5281/zenodo.8212731},\n  url          = {https://doi.org/10.5281/zenodo.8212731}\n}\n```\n\n","funding_links":["https://github.com/sponsors/jonnor"],"categories":["Libraries"],"sub_categories":["AI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femlearn%2Femlearn-micropython","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femlearn%2Femlearn-micropython","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femlearn%2Femlearn-micropython/lists"}