ml-trainer

Train a machine learning model on movement data from the micro:bit's accelerometer. Run it on your BBC micro:bit, building your own progam that uses the machine learning model in Microsoft MakeCode.

Try it at https://createai.microbit.org

History

This repository is derived from ML-Machine (GitHub), a free and open-source interactive machine-learning platform from the Center for Computational Thinking and Design at Aarhus University.

Significant changes have been made to align with the tech stack of other Micro:bit Educational Foundation applications, add and remove features, and revise the user experience for some features also in ML-Machine. We encourage you to review both projects and see which best fits your needs.

Related projects

• pxt-microbit-ml — the MakeCode extension this app adds to the projects it generates (the version is pinned in src/makecode/utils.ts). It provides the ML blocks and on-device inference runtime, plus the simulator extension shown alongside the micro:bit simulator in MakeCode. The ml.event.* blocks for the user's trained actions don't live in the extension itself: this app generates them into each project's autogenerated.ts from the trained model.
• pxt-microbit-ml-help-stubs — a stub extension used only by pxt-microbit-ml's MakeCode help pages. Since the ml.event.* action constants are generated per-project (see above), the documentation's example snippets wouldn't compile against the bare extension; the stubs supply an example action so the snippets render as blocks in the docs.

Building and running the app

Getting up and running:

1. Ensure you have a working Node.js environment. We recommend using the LTS version of Node.
2. Checkout this repository with Git. GitHub have some learning resources for Git that you may find useful.
3. Install the dependencies by running npm install on the command line in the checkout folder.
4. Choose from the NPM scripts documented below. Try npm start if you're not sure.

npm run dev

Runs the app in the development mode.

Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.

This does not show TypeScript or lint errors. Use the eslint plugin for your editor and consider also running npm run typecheck:watch to see full type checking errors.

npm test

Launches the test runner in interactive mode (unless the CI environment variable is defined). See the section about running tests for more information.

npm run build

Builds the app for production to the dist folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

iOS/Android development

Local development

To get a proper dev server for iOS/Android development run:

npm run cap:sync:dev

Then run

npm run dev:apps

Use e.g. npx cap open ios to open the IDE and run from there.

The vite dev server run by dev:apps will be running inside the app.

Signing for your own iOS device

The repo defaults to bundle id org.microbit.mltrainer and an empty Apple development team — fine for the iOS Simulator, but to install on a real iPhone or iPad you need to sign with your own Apple Developer account. The default bundle id is reserved for the Micro:bit Educational Foundation's developer account, so unless you're a member of that team you'll need to use one of your own.

Drop a gitignored override at ios/App/App/Brand.local.xcconfig:

BRAND_BUNDLE_ID = com.yourname.mltrainer
BRAND_DEVELOPMENT_TEAM = ABC1234567

Your team id is in Xcode → Settings → Accounts → your Apple ID, or under Apple Developer → Membership.

This file is loaded after Brand.xcconfig and after the optional private theme overlay, so it wins. It's gitignored and not touched by npm run apply-brand, so it survives npm install.

If you also need to override the Android applicationId (rare for local debug builds — only matters if you plan to publish), drop android/app/brand.local.gradle:

ext.brandAppId = "com.yourname.mltrainer"
ext.brandDisplayName = "ml-trainer (yourname)"

To keep the Capacitor-level appId consistent (only relevant if you hit a plugin that keys off it), also drop brand.local.json at the repo root:

{
  "appId": "com.yourname.mltrainer",
  "appName": "ml-trainer"
}

Signed builds

CI builds signed artifacts using Fastlane. iOS certificates and provisioning profiles are managed via Fastlane Match with encrypted credentials stored in a private repository. Android signing uses a keystore stored in CI secrets.

To run Fastlane locally:

bundle install
bundle exec fastlane ios build    # Build signed IPA (macOS only)
bundle exec fastlane android build # Build signed APK/AAB

Or you can use Homebrew via brew install fastlane and drop the bundle exec (this can sidestep Ruby version issues).

Android builds require the signing keystore and passwords via environment variables. iOS builds require Match credentials to fetch certificates.

Releases and apps/web versioning

Web and app releases are both made from main by creating a GitHub release (the workflows trigger on release creation, not tag pushes). The tag determines what CI does:

• vX.Y.Z — web release. The build workflow deploys to production; the app workflows skip it.
• vX.Y.Z-apps — apps release. The iOS and Android workflows build and upload to TestFlight and Google Play; the web deploy skips it. Promotion through the testing tracks to production is managed in the store consoles.

Web and apps share a single version sequence. Take the next unused version for whichever release you're making — a version number must never refer to two different commits.

For apps, the marketing version is the tag with the -apps suffix stripped (store limitation) and the build number is the CI run number.

Scenarios:

• Web-only release: create a release tagged with the next version, e.g. v1.5.3.
• Apps-only release: as above with the -apps suffix, e.g. v1.5.4-apps.
• Both from the same commit: create two releases with the same version, e.g. v1.6.0 and v1.6.0-apps.

Use GitHub's generated release notes as a starting point, but set the "Previous tag" to the last release of the same channel (web or apps) — the default is the most recent release of either channel, which would omit changes that have only shipped to the other channel's users. For web releases, move apps-only changes under their own heading — they're not relevant to web users but worth listing in case they cause a regression.

Deployments

Most users should use the supported Foundation deployment at https://createai.microbit.org/

The editor is deployed by GitHub actions.

License

This software is under the MIT open source license.

SPDX-License-Identifier: MIT

Significant code is derived from ML-Machine (also MIT licensed) and is (c) Center for Computational Thinking and Design at Aarhus University and contributors. See individual file copyright notices for more details.

Conceptually this project draws heavily on the work done by the Center for Computational Thinking and Design at Aarhus University (see CCTD.dk) and we're hugely grateful for their ongoing support and collaboration.

We use dependencies via the NPM registry as specified by the package.json file under common Open Source licenses.

Full details of each package can be found by running license-checker:

$ npx license-checker --direct --summary --production

Omit the flags as desired to obtain more detail.

The repository includes forks of Lancaster's micro:bit-samples repositories for micro:bit V1 and V2. They are MIT licensed.

Code of Conduct

Trust, partnership, simplicity and passion are our core values we live and breathe in our daily work life and within our projects. Our open-source projects are no exception. We have an active community which spans the globe and we welcome and encourage participation and contributions to our projects by everyone. We work to foster a positive, open, inclusive and supportive environment and trust that our community respects the micro:bit code of conduct. Please see our code of conduct which outlines our expectations for all those that participate in our community and details on how to report any concerns and what would happen should breaches occur.