Skip to content

Commit a925d15

Browse files
Update outdated README info.
1 parent f34b52a commit a925d15

File tree

1 file changed

+22
-27
lines changed

1 file changed

+22
-27
lines changed

README.md

Lines changed: 22 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,53 @@
11
# MakeCode extension to run ML4F models
22

3-
This extension is a work in progress. It supports unreleased work on the micro:bit machine learning tool.
4-
5-
[![MakeCode Project](https://github.com/microbit-foundation/pxt-ml-runner-poc/actions/workflows/makecode.yml/badge.svg)](https://github.com/microbit-foundation/pxt-ml-runner-poc/actions/workflows/makecode.yml)
6-
[![Header Generator Tests](https://github.com/microbit-foundation/pxt-ml-runner-poc/actions/workflows/header-gen.yml/badge.svg)](https://github.com/microbit-foundation/pxt-ml-runner-poc/actions/workflows/header-gen.yml)
3+
[![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)
4+
[![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)
75

86
This project includes [ML4F](https://github.com/microsoft/ml4f) and a wrapper
97
to invoke a known type of model. It is left slim to be able to be import it
108
in other MakeCode extensions and a MicroPython module.
119

12-
## How to use your ML4F model with this extension
13-
14-
This extension expects the classes to be present as a global `MlRunnerLabels`
15-
enum, and the ML4F + custom header to be provided by a `getModelBlob()`
16-
function (no namespaces) as as a hex template literal.
1710

18-
An example for this can be seen in the [`autogenerated.ts`](autogenerated.ts)
19-
file.
11+
## How to use your ML4F model with this extension
2012

21-
## Developer considerations
13+
The ML4F wrapper library can be found in the `mlrunner` folder.
14+
This repository also includes a pre-compiled model (inclusion can be controlled
15+
via compilation flags configured in the `pxt.json` file) and MakeCode files
16+
to be able to build it and test it as a MakeCode project.
2217

23-
- Almost nothing implemented yet
24-
- Currently it embeds a model in a C file as an array with blob data
25-
- Due to the model size, BLE had to be disabled
26-
- This currently doesn't work on live MakeCode, only beta
27-
- Actually it doesn't look like it works in beta either, just locally
28-
- Adding other BLE extensions might fail
29-
- This repository [issue tracker](https://github.com/microbit-foundation/pxt-ml-runner-poc/issues/)
30-
contains issues that could be encountered and workarounds
31-
- Only built and tested on micro:bit V2
18+
The files listed in the `pxt.json` as `testFiles` are only used when
19+
this repository is compiled as a MakeCode project. When used as an extension
20+
a similar implementation needs to be provided externally.
3221

3322

34-
## Use as Extension
23+
## Use as a MakeCode Extension
3524

3625
This repository can be added as an **extension** in MakeCode.
3726

3827
* Open [MakeCode beta](https://makecode.microbit.org/beta)
3928
* Click on **New Project**
4029
* Click on **Extensions** under the gearwheel menu
41-
* Search for **https://github.com/microbit-foundation/pxt-ml-runner-poc** and import
30+
* Search for **https://github.com/microbit-foundation/pxt-microbit-ml-runner** and import
4231

4332

44-
## Edit this project
33+
## Edit as a MakeCode project
4534

4635
### In MakeCode online editor
4736

4837
To edit this repository in MakeCode.
4938

5039
* Open [MakeCode](https://makecode.microbit.org)
5140
* Click on **Import** then click on **Import URL**
52-
* Paste **https://github.com/microbit-foundation/pxt-ml-runner-poc** and click import
41+
* Paste **https://github.com/microbit-foundation/pxt-microbit-ml-runner** and click import
5342

5443
### Building locally
5544

5645
Ensure you have the required toolchain to build for V1 and V2
5746
(arm-none-eabi-gcc, python, yotta, cmake, ninja, srec_cat) or docker.
5847

5948
```bash
60-
git clone https://github.com/microbit-foundation/pxt-ml-runner-poc
61-
cd pxt-ml-runner-poc
49+
git clone https://github.com/microbit-foundation/pxt-microbit-ml-runner
50+
cd pxt-microbit-ml-runner
6251
npm install pxt --no-save
6352
npx pxt target microbit --no-save
6453
npx pxt install
@@ -81,6 +70,8 @@ PXT_FORCE_LOCAL=1 PXT_NODOCKER=1 PXT_COMPILE_SWITCHES=csv---mbcodal npx pxt
8170
> These are autogenerated by MakeCode to contain the enums and function shims
8271
> from the C++ code to be accessible by TypeScript. However, these are only
8372
> needed for the test code, and should **not** be shipped.
73+
>
74+
> So, it's recommended to use: `git update-index --skip-worktree <file>`
8475
>
8576
> Unfortunately, adding `enums.d.ts` and `shims.d.ts` to the `testFiles` entry
8677
> in `pxt.json` does not work, and they need to be added to `files` (so they
@@ -121,6 +112,10 @@ example model included in this extension.
121112
This flag name is expanded to `DEVICE_MLRUNNER_USE_EXAMPLE_MODEL` in the
122113
source code.
123114

115+
### Serial debug data
116+
117+
By default, the MakeCode project prints debug data via serial.
118+
To disable this feature, set the `ML_DEBUG_PRINT` flag to `0`.
124119

125120
## License
126121

0 commit comments

Comments
 (0)