microbit-v2-samples

This repository provides the necessary tooling to compile a C/C++ CODAL program for the micro:bit v2 and generate a HEX file that can be downloaded to the device.

Raising Issues

Any issues regarding the micro:bit are gathered on the lancaster-university/codal-microbit-v2 repository. Please raise yours there too.

Installation

You need some open source pre-requisites to build this repo. You can either install these tools yourself, or use the docker image provided below.

• GNU Arm Embedded Toolchain
• Github desktop
• CMake
• Python 3

We use Ubuntu Linux for most of our tests. You can also install these tools easily through the package manager:

    sudo apt install gcc
    sudo apt install git
    sudo apt install cmake
    sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi

Yotta

For backwards compatibility with microbit-samples users, we also provide a yotta target for this repository.

Docker

You can use the Dockerfile provided to build the samples, or your own project sources, without installing additional dependencies.

Run the following command to build the image locally; the .bin and .hex files from a successful compile will be placed in a new out/ directory:

    docker build -t microbit-tools --output out .

To omit the final output stage (for CI, for example) run without the --output arguments:

    docker build -t microbit-tools .

Building

• Clone this repository
• In the root of this repository type python build.py
• The hex file will be built MICROBIT.HEX and placed in the root folder.

Developing

You will find a simple main.cpp in the source folder which you can edit. CODAL will also compile any other C/C++ header files our source files with the extension .h .c .cpp it finds in the source folder.

The samples folder contains a number of simple sample programs that utilise you may find useful.

Developer codal.json

There is an example coda.dev.json file which enables "developer builds" (clones dependencies from the latest commits, instead of the commits locked in the codal-microbit-v2 tag), and adds extra CODAL flags that enable debug data to be printed to serial. To use it, simply copy the additional json entries into your codal.json file, or you can replace the file completely (mv coda.dev.json codal.json).

Debugging

If you are using Visual Studio Code, there is a working debugging environment already set up for you, allowing you to set breakpoints and observe the micro:bit's memory. To get it working, follow these steps:

1. Install either OpenOCD or PyOCD.
2. Install the marus25.cortex-debug VS Code extension.
3. Build your program.
4. Click the Run and Debug option in the toolbar.
5. Two debugging options are provided: one for OpenOCD, and one for PyOCD. Select the correct one depending on the debugger you installed.

This should launch the debugging environment for you. To set breakpoints, you can click to the left of the line number of where you want to stop.

Compatibility

This repository is designed to follow the principles and APIs developed for the first version of the micro:bit. We have also included a compatibility layer so that the vast majority of C/C++ programs built using microbit-dal will operate with few changes.

Documentation

API documentation is embedded in the code using doxygen. We will produce integrated web-based documentation soon.