{"id":21070701,"url":"https://github.com/microbit-foundation/pxt-microbit-ml-runner","last_synced_at":"2026-01-24T04:04:14.909Z","repository":{"id":240107918,"uuid":"801694549","full_name":"microbit-foundation/pxt-microbit-ml-runner","owner":"microbit-foundation","description":"MakeCode extension to run ML4F models","archived":false,"fork":false,"pushed_at":"2024-10-31T16:59:49.000Z","size":396,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-30T15:31:12.023Z","etag":null,"topics":["ai","makecode","ml"],"latest_commit_sha":null,"homepage":"","language":"C","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/microbit-foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-16T18:23:57.000Z","updated_at":"2025-04-09T15:32:55.000Z","dependencies_parsed_at":"2024-05-21T20:30:33.270Z","dependency_job_id":"70445b2f-48ee-4b6a-ae06-518f6aaa8328","html_url":"https://github.com/microbit-foundation/pxt-microbit-ml-runner","commit_stats":null,"previous_names":["microbit-foundation/pxt-ml-runner-poc","microbit-foundation/pxt-microbit-ml-runner"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/microbit-foundation/pxt-microbit-ml-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fpxt-microbit-ml-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fpxt-microbit-ml-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fpxt-microbit-ml-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fpxt-microbit-ml-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microbit-foundation","download_url":"https://codeload.github.com/microbit-foundation/pxt-microbit-ml-runner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fpxt-microbit-ml-runner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28711453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T23:51:44.727Z","status":"online","status_checked_at":"2026-01-24T02:00:06.909Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ai","makecode","ml"],"created_at":"2024-11-19T18:47:53.149Z","updated_at":"2026-01-24T04:04:14.894Z","avatar_url":"https://github.com/microbit-foundation.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MakeCode extension to run ML4F models\n\n[![MakeCode Project](https://github.com/microbit-foundation/pxt-microbit-ml-runner/actions/workflows/makecode.yml/badge.svg)](https://github.com/microbit-foundation/pxt-microbit-ml-runner/actions/workflows/makecode.yml)\n[![Header Generator Tests](https://github.com/microbit-foundation/pxt-microbit-ml-runner/actions/workflows/header-gen.yml/badge.svg)](https://github.com/microbit-foundation/pxt-microbit-ml-runner/actions/workflows/header-gen.yml)\n\nThis project wraps [ML4F](https://github.com/microsoft/ml4f) to invoke a known\ntype of model that requires some data pre-processing.\nThe wrapper is provided as a slim library to be able to be import it\ninto other MakeCode extensions and as a MicroPython module.\n\n\n## How to use external ML4F model with this extension\n\nThe ML4F wrapper library can be found in the `mlrunner` folder.\nThis repository also includes a pre-compiled model (inclusion can be controlled\nvia compilation flags configured in the `pxt.json` file) and MakeCode files\nto be able to build it and test it as a MakeCode project.\n\nThe files listed in the `pxt.json` as `testFiles` are only used when\nthis repository is compiled as a MakeCode project. When used as an extension\na similar implementation needs to be provided externally.\n\n\n## Use as a MakeCode Extension\n\nThis repository can be added as an **extension** in MakeCode.\n\n* Open [MakeCode beta](https://makecode.microbit.org/beta)\n* Click on **New Project**\n* Click on **Extensions** under the gearwheel menu\n* Search for **https://github.com/microbit-foundation/pxt-microbit-ml-runner** and import\n\n\n## Edit as a MakeCode project\n\n### In MakeCode online editor\n\nTo edit this repository in MakeCode.\n\n* Open [MakeCode](https://makecode.microbit.org)\n* Click on **Import** then click on **Import URL**\n* Paste **https://github.com/microbit-foundation/pxt-microbit-ml-runner** and click import\n\n### Building locally\n\nEnsure you have the required toolchain to build for V1 and V2\n(arm-none-eabi-gcc, python, yotta, cmake, ninja, srec_cat) or docker.\n\n```bash\ngit clone https://github.com/microbit-foundation/pxt-microbit-ml-runner\ncd pxt-microbit-ml-runner\nnpm install pxt --no-save\nnpx pxt target microbit --no-save\nnpx pxt install\nPXT_FORCE_LOCAL=1 npx pxt\n```\n\nFor the V1 build Yotta can hit the GitHub rate limits quite easily if the\nproject is built from a clean state more than once.\nA V2-only build can be triggered with the `PXT_COMPILE_SWITCHES=csv---mbcodal`\nenvironmental variable.\n\n```\nPXT_FORCE_LOCAL=1 PXT_NODOCKER=1 PXT_COMPILE_SWITCHES=csv---mbcodal npx pxt\n```\n\n\u003e [!CAUTION]\n\u003e **When updating this repository, do NOT push changes to the `enums.d.ts`\n\u003e or `shims.d.ts` files.**\n\u003e\n\u003e These are autogenerated by MakeCode to contain the enums and function shims\n\u003e from the C++ code to be accessible via TypeScript. However, these are only\n\u003e needed for the test code, and should **not** be shipped as it will affect\n\u003e its usage as a MakeCode extension.\n\u003e \n\u003e It's recommended to run locally: `git update-index --skip-worktree \u003cfile\u003e`\n\u003e\n\u003e Unfortunately, adding `enums.d.ts` and `shims.d.ts` to the `testFiles` entry\n\u003e in `pxt.json` does not work, and they need to be added to `files` (so they\n\u003e end up included with the extension) and so, they should be kept empty.\n\u003e Building the project locally compiles all the test files, will add code\n\u003e to these `.d.ts` files, which should not be pushed.\n\n\n## Build flags\n\nThese flags can be added to a project including this extension, to modify\nthe default behaviour of the extension code.\n\n### Built-in ML model\n\n\u003e [!NOTE]\n\u003e This flag is only applicable when building this repository as a MakeCode\n\u003e project. When used as a MakeCode extension, the files with the built-in\n\u003e model will not be included and the build will fail.\n\nThe `MLRUNNER_USE_EXAMPLE_MODEL` flag can be used to add into a project an\nexample model included in this extension.\n\n- 0: This is the default behaviour, no built-in module is build at all by\n  this extension.\n- 1: Includes a ML-Trainer model converted with ML4F. Trained with 3 classes,\n  shake, circle and still.\n- 2: This will include the Keras ADL model converted with ML4F.\n  This model is too large and might not fit in normal builds without excluding\n  the BLE SoftDevice, so its usage is discouraged.\n  Classes: Jumping, Running, Standing, Walking\n\n```json\n{\n    \"yotta\": {\n        \"config\": {\n            \"MLRUNNER_USE_EXAMPLE_MODEL\": 1\n        }\n    }\n}\n```\n\nThis flag name is expanded to `DEVICE_MLRUNNER_USE_EXAMPLE_MODEL` in the\nsource code.\n\n### Serial debug data\n\nBy default, the MakeCode project prints debug data via serial.\nTo disable this feature, set the `ML_DEBUG_PRINT` flag to `0`.\n\n## Testing the model with known data\n\nA special mode has been included to test the filters and model output.\nThis mode can be triggered by changing a define flag in the source code and\nincluding a couple of test files with accelerometer samples, expected filter\nand model results, and a model blob to test.\n\nThe results are printed to serial and nothing else runs on the device. So, it\nis designed for one-off tests for validation and debugging.\n\nTo run the tests:\n- Obtain the `autogenerate.ts` and `modeltest/testdata.h` files under test and\n  replace the versions already present in this reporistory.\n  - You can copy the files from within the `modeltest/testdatax/` folders\n  - Or create new ones using the `ml4f-output` npm script within the\n    [CreateAI](https://github.com/microbit-foundation/ml-trainer) project\n- If you have a `main.ts` file using the model under test, add it as well\n  - Otherwise you might need to manually update the `main.ts` file for the\n    actions configured in the model under test\n- Set the [`ML_TEST_MODEL` macro define](https://github.com/microbit-foundation/pxt-microbit-ml-runner/blob/a79fdaf51ebf221843a7be4c948f586643471991/testextension.cpp#L11)\n  value to `1`\n- Build the MakeCode project locally (`npx pxt`) and flash the micro:bit\n- Connect a serial terminal and review the printed data\n\n\n## License\n\nThis software is under the MIT open source license.\n\n[SPDX-License-Identifier: MIT](LICENSE)\n\n\n## Code of Conduct\n\nTrust, partnership, simplicity and passion are our core values we live and\nbreathe in our daily work life and within our projects. Our open-source\nprojects are no exception. We have an active community which spans the globe\nand we welcome and encourage participation and contributions to our projects\nby everyone. We work to foster a positive, open, inclusive and supportive\nenvironment and trust that our community respects the micro:bit code of\nconduct. Please see our [code of conduct](https://microbit.org/safeguarding/)\nwhich outlines our expectations for all those that participate in our\ncommunity and details on how to report any concerns and what would happen\nshould breaches occur.\n\n\n#### Metadata (used for search)\n\n* for PXT/microbit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobit-foundation%2Fpxt-microbit-ml-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrobit-foundation%2Fpxt-microbit-ml-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobit-foundation%2Fpxt-microbit-ml-runner/lists"}