Custom micro:bit runtime with bundled file?

[tmontes]

Hi all,

I'm getting ready to deliver a beginners workshop where we will be using Mu, the micro:bit, and the this funky cutebot, to be controlled by the micro:bit.

Interfacing with the cutebot requires, unsurprinsingly, low level code that sets/reads/writes micro:bit I/O pins -- this is something I'd like to avoid with these beginners, at least at this stage.

There's this module that abstracts away those details and supports interfacing with the cutebot with higher level abstractions.

Here's my trouble:

• If I flash the micro:bit, only the "active editor" code is pushed.
• Thusly, if it imports cutebot, running is bound to fail.
• ...unless, of course, in a second step, I copy the cutebot.py into the micro:bit.

What I'd like:

• Buidling a custom micro:bit runtime image with, say, a bundled cutebot.py in the micro-python filesystem that could be imported.
• With that, we could all configure Mu to use that image in the workshop, and beginners could focus on playing/learning while avoiding low-level detais.

In a way, much like the micro:bit runtime includes other modules like display, audio, etc.

I tried uflash but it does not seem to help me: it only embeds a single .py file, and it seems to fail at handling the newer v1/v2 universal micro:bit runtime images.

I'm likely missing something obvious to some... I'd appreciate any input/ideas to simplify the workshop workflow and allow beginners to focus on the real cutebot actions like set_motor_speed(x), instead of i2c.write(bla bla bla gibberish for beginners).

Thanks in advance.

PS: Tagging @carlosperate, hoping his experience with the micro:bit can help? :)

[carlosperate]

Hi Tiago

uFlash only has the simplest possible implementation of the micro:bit MicroPython filesystem, which only adds a single python script as a main.py file, as uFlash itself didn't really support adding multiple python files anyway.

Apart from that, the option to use a "custom hex file" with uFlash was removed, as it would require us to implement the filesystem fully (instead of the cut-down version currently implemented). This would be needed to be able to detect the fs location in memory, specially for custom MicroPython builds, and to be able to detect present files in the hex file already, to be able to add a main.py without overwritting anything else (right now, things like the filesystem location and size are hardcoded, as we know those values for the shipped hex file). Dont' get me wrong, this is all doable and not that complex, it's just a matter of having the bandwidth to implement it.

I believe that in Mu, when adding a path to a custom hex file, then the hex file is flashed to the micro:bit and then the user code is transferred via serial as main.py. As you have already described, you could create a custom MicroPython hex file with the cutebot.py file already inside, and then use Mu to flash that custom hex. The only thing that might be a bit annoying is that i think maybe Mu has to flash the hex file every time, as it might not have a way to determine if the MicroPython running on the micro:bit is the custom Hex or something different.

To create the custom hex file, the simplest way might be to use the micro:bit Python Editor to add your cuteboy.py file to the project (and no text at all in the code editor, so hopefully it doesn't add an empty main.py) and download the hex file using the "save" button:
https://python.microbit.org

This downloaded hex file from the micro:bit Python Editor will be a "Universal Hex file", and I can't remeber if Mu works with Universal hex files? have you tried that already unsuccessfully?
If that's the case, you should be able to separte a Universal Hex into two hex files using this tool:
https://microbit-foundation.github.io/microbit-universal-hex/examples/separate.html
The 9900.hex file will be for micro:bit V1 and 9903 for micro:bit V2.

[tmontes]

Hey Carlos,

Thanks a lot for your detailed feedback. I successfully used the online editor you linked to to create a custom Hex file with a bundled cutebot.py which Mu happily flashes onto the micro:bit on top of which main.py (extracted from the editor window) is added -- this is the workflow I was looking for. Lovely!

I'm not sure whether Mu is flashing then transferring main.py via serial, or what its doing under the hood, but it just works -- and that's how we like it. :-)

Improving uflash to either help create such custom Hex files and/or support flashing an arbitrary number of files without clashing with any that could be present in its embedded filesystem could be a nice project... (to build something that could be run locally, with no internet access/dependency on an online service that might go away at any time, that is). But other than the Wikipedia docs on the Intel Hex format and the micro:bit micropython Hex docs, I could not quickly find a way to determine how to "understand" a micro:bit Hex file to "change it" in such a way... I wonder if the bundled filesystem is littlefs for which this package could be useful. Also, this intelhex package also feels it could be useful.

Are there any more detailed docs on the layout of the Hex file for the micro:bit? (or is it some kind of "generic" thing that applies to many different microcontrollers? I suppose not, but I really don't know about these things... just following intuition)

Again, thanks a lot! :-)

[carlosperate]

Due to the low resources of micro:bit V1, the filesystem created in MicroPython is very simple. You can think of it as a double linked list with some metadata on the first block. No documentation per se, but the C source code has some comments to explain how it works and the code is not hard to follow:
https://github.com/bbcmicrobit/micropython/blob/master/source/microbit/filesystem.c

And there is also the TS implementation for the browser: https://github.com/microbit-foundation/microbit-fs/

[tmontes]

...would I be correct in guessing that the embedded file system for micro:bit V2 is different due to fewer physical constraints?

[carlosperate]

No, the micro:bit V2 filesystem has been kept the same for compatibility reasons.

[tmontes]

Oh, I'm happy with that choice! (wondering if this is an itch I want to scratch...) 😅