From 1f1d40db4aa116ccf9ac75b558e9dbc43381ddc7 Mon Sep 17 00:00:00 2001 From: Carlos Pereira Atencio Date: Wed, 26 Nov 2025 19:44:31 +0100 Subject: [PATCH] Revise micro:bit runtime documentation Updated the description and clarified the micro:bit runtime sections. --- software/runtime.md | 87 +++++++++++++++++++++++++-------------------- 1 file changed, 49 insertions(+), 38 deletions(-) diff --git a/software/runtime.md b/software/runtime.md index 7360965..ca59dee 100644 --- a/software/runtime.md +++ b/software/runtime.md @@ -3,7 +3,7 @@ layout: page order: title: The micro:bit runtime DAL/CODAL heading: The micro:bit runtime DAL/CODAL -description: Information on developing with the micro:bit runtime, the low level C/C++ tool on which much of the software ecosystem for the micro:bit is built. +description: Developing with the micro:bit runtime, the low level C/C++ tool on which much of the software ecosystem for the micro:bit is built. permalink: /software/runtime/ ref: software lang: en @@ -15,7 +15,7 @@ lang: en * TOC {:toc} -The micro:bit runtime, also known as the DAL/CODAL is software that runs on a micro:bit to support the majority of the micro:bit programming languages. It can help you understand how the micro:bit works, and also will help you understand where to start if you want to dive deeper into the micro:bit, write support software for your own micro:bit hardware extensions, and tailor or improve something on the micro:bit. +The micro:bit runtime, also known as the DAL/CODAL, is software that runs on a micro:bit to support the majority of the micro:bit programming languages. It can help you understand how the micro:bit works, and also will help you understand where to start if you want to dive deeper into the micro:bit, write support software for your own micro:bit hardware extensions, and tailor or improve something on the micro:bit. | V2 | V1 | ---- | ---- @@ -23,67 +23,78 @@ The micro:bit runtime, also known as the DAL/CODAL is software that runs on a mi There are a number of important software layers that run on the micro:bit to enable easy to use languages such as Javascript to be used. Some of these, like Arm Mbed and MicroPython existed before the BBC micro:bit project started, and others, such as the micro:bit runtime were written specifically for the micro:bit. -Arm Mbed provides a Hardware Abstraction Layer (HAL) for chips using Arm Cortex processors. This abstraction layer presents a uniform layer that developers can use to write software for any Arm based processor - including the Nordic chip used on the micro:bit. It provides easy access to peripheral interfaces such as SPI, I2C and serial for use by higher level environments. +## The micro:bit Runtime -When writing C/C++ code for the micro:bit, use of the micro:bit runtime is highly recommended. It provides an easy to use API for C/C++ programs, and is written in a componentised manner so that you can use only the parts you need (for example, just the MicroBitDisplay). +The micro:bit runtime, created by Lancaster University, is a Hardware Abstraction Layer (HAL) providing a useful set of functions for higher level languages to consume, and to make programming the micro:bit in C or C++ easier. -### The micro:bit runtime Device Abstraction Layer (DAL) - V1 +Many of the MakeCode 'blocks' or MicroPython functions are directly calling functions provided by the micro:bit runtime. -The micro:bit runtime provides a [Device Abstraction Layer (DAL)](https://lancaster-university.github.io/microbit-docs/), that is built using Arm Mbed. Lancaster University has written this runtime for the micro:bit V1 as part of its ongoing efforts to support the adoption of Computer Science in schools. It provides a useful set of functions for higher level languages to consume, and make programming the micro:bit in C or C++ easier. Many of the 'blocks' you use in MakeCode are directly calling functions provided by the DAL. The micro:bit runtime DAL is written in C/C++ and builds on the Arm Mbed HAL. +Key components of the micro:bit runtime are: -Key components of the micro:bit DAL are: +- A fiber scheduler, that lets your micro:bit do more than one task at a time. +- An eventing system called the message bus, that lets you write reactive code. It can inform your program when things happen on your micro:bit - everything from a button click to a message being received on the radio. +- Device drivers representing the major hardware blocks on the micro:bit, including the LED display, sensors, radio and bluetooth profile. +- Managed types that help keep your programs safe from the complexities of memory management. Originally implemented for higher level languages to exploit, they have also proven very useful for C/C++ programmers too. -- a scheduler, that lets your micro:bit do more than one task at a time. -- an eventing system called the message bus, that lets you write reactive code. It can inform your program when things happen on your micro:bit - everything from a button click to a message being received on the radio. -- device drivers representing the major hardware blocks on the micro:bit, including the LED display, sensors, file system, radio and bluetooth profile. -- managed types that help keep your programs safe from the complexities of memory management. Originally implemented for higher level languages to exploit, they have also proven very useful for C/C++ programmers too. +The initial version of the micro:bit runtime developed for micro:bit V1 was called DAL (Device Abstraction Layer), which evolved into CODAL (Component Oriented Device Abstraction Layer) for micro:bit V2. -The micro:bit V1 can also be programmed using the Mbed HAL directly, for those developers seeking more low level access to the hardware. -### Component Oriented Device Abstraction Layer (CODAL)- V2 -The [Component Oriented Device Abstraction Layer (CODAL)](https://lancaster-university.github.io/codal/) is an evolution of the DAL runtime that abstracts each hardware component of the micro:bit as a software component. CODAL supports a range of devices and processors, including the micro:bit V2 device. A specific CODAL target has been written for the latest micro:bit: +### micro:bit V2 - Component Oriented Device Abstraction Layer (CODAL) + +The Component Oriented Device Abstraction Layer (CODAL) is an evolution of the micro:bit V1 DAL runtime that abstracts each hardware component of the micro:bit as a software component. +CODAL was created to generalise and evolve the original DAL, so it could better meet scalability, performance, and cross‑device requirements beyond the first micro:bit board. +CODAL supports a range of devices and processors, including the micro:bit V2 device: [CODAL target for micro:bit V2](https://github.com/lancaster-university/codal-microbit-v2) -Key components of micro:bit CODAL are: +More information can be found in this paper: [MakeCode and CODAL - intuitive and efficient embedded systems programming for education](https://tech.microbit.org/projects/MakeCode-and-CODAL/)) -- A unified eventing subsystem (common to all components) that provides a mechanism to map asynchronous hardware and software events to event handlers; -- A non-pre-emptive fiber scheduler that enables concurrency while minimizing the need for resource locking primitives. -- A simple memory management system based on reference counting to provide a basis for managed types. -- A set of drivers, that abstract microcontroller hardware components into higher level software components,each represented by a C++ class. -- A parameterized object model composed from these components that represents a physical device. +#### Building CODAL -(Source: [MakeCode and CODAL - intuitive and efficient embedded systems programming for education](https://tech.microbit.org/projects/MakeCode-and-CODAL/)) +The [instructions for building CODAL](https://github.com/lancaster-university/microbit-v2-samples) are currently located in the micro:bit V2 samples repository. You can clone this repository and build examples from the source folder. -### Building CODAL +#### CODAL Source Code -The [instructions for building CODAL](https://github.com/lancaster-university/microbit-v2-samples) are currently located in the micro:bit samples repository. You can clone this repository and build examples from the source folder. The final link is TBC and may change. +- [Sample C/C++ programs](https://github.com/lancaster-university/microbit-v2-samples) +- [CODAL target for micro:bit V2](https://github.com/lancaster-university/codal-microbit-v2) + - CODAL micro:bit V2 target dependencies: + - [CODAL core](https://github.com/lancaster-university/codal-core/) + - [CODAL nRF52](https://github.com/lancaster-university/codal-nrf52/) + - [CODAL Nordic SDK](https://github.com/microbit-foundation/codal-microbit-nrf5sdk) -### Contributing to the micro:bit Runtime +### micro:bit V1 - Device Abstraction Layer (DAL) -The micro:bit runtime is an open source project, distributed under the MIT license, and contributions and collaborations are very much welcomed from the micro:bit community. There are still many things that could be merged into the micro:bit runtime, and with MakeCode moving forward and adding new features, things that go into the runtime can also be exposed to the higher level languages if they work well and prove useful for coding in education. +The original micro:bit runtime provides a [Device Abstraction Layer (DAL)](https://lancaster-university.github.io/microbit-docs/), that is built on top of Arm Mbed. -Firstly, you should get yourself into a situation where you can build the micro:bit runtime DAL. You can choose either an online build environment inside your web browser through Mbed.org, or an downloadable compiler. The [getting started docs](https://lancaster-university.github.io/microbit-docs/#getting-started) guide you through this process. +Arm Mbed provides a Hardware Abstraction Layer (HAL) for chips using Arm Cortex processors. This abstraction layer presents a uniform layer that developers can use to write software for any Arm based processor - including the Nordic chip used on the micro:bit V1. It provides easy access to peripheral interfaces such as SPI, I2C and serial for use by higher level environments. -### Asking for features and reporting bugs +The micro:bit V1 can also be programmed using the Mbed HAL directly, for those developers seeking more low level access to the hardware. -If you would have a feature request, or would like to get involved in the micro:bit runtime development, visit the [list of open issues](https://github.com/lancaster-university/microbit-dal/issues) and raise a new issue if it isn't already in there. +#### Building DAL -You can also join the [microbit developer community on Slack]({{ "/community" | relative_url }}) if you'd like to discuss the micro:bit runtime and its components. +The [instructions for building DAL](https://lancaster-university.github.io/microbit-docs/offline-toolchains/) are located in the official documentation. -If you think you've found a bug in the DAL, please [log a new issue in the GitHub DAL repository](https://github.com/lancaster-university/microbit-dal/issues/new) +Some of the Arm Mbed tooling, specifically [Yotta, has been deprecated](https://support.microbit.org/support/solutions/articles/19000123284-arm-yotta-registry-deprecation) and installing it in moderm development environments can be difficult. This [Docker image with the micro:bit C++ toolchain](https://github.com/carlosperate/docker-microbit-toolchain) provides a pre-configure build environment that can simplify the process to build DAL. -### DAL Source Code +#### DAL Source Code -[Device Abstraction Layer, source code](https://github.com/lancaster-university/microbit-dal) +- [Device Abstraction Layer, source code](https://github.com/lancaster-university/microbit-dal) +- [Sample C/C++ programs, source code](https://github.com/lancaster-university/microbit-samples) +- [Device Abstraction Layer, documentation sources](https://github.com/lancaster-university/microbit-docs) + +## Contributing, asking for features and reporting bugs + +The micro:bit runtime is an open source project, distributed under the MIT license, and contributions and collaborations are very much welcomed from the micro:bit community. There are still many things that could be merged into the micro:bit runtime, and with MakeCode moving forward and adding new features, things that go into the runtime can also be exposed to the higher level languages if they work well and prove useful for coding in education. -[Sample C/C++ programs, source code](https://github.com/lancaster-university/microbit-samples) +The micro:bit runtime work is managed via GitHub issue trackers. This is the best place to contribute, send a feature request, or report an bug. +- [CODAL issue tracker](https://github.com/lancaster-university/codal-microbit-v2/issues) for micro:bit V2 +- [DAL issue tracker](https://github.com/lancaster-university/microbit-dal/issues) for micro:bit V1 -[Device Abstraction Layer, documentation sources](https://github.com/lancaster-university/microbit-docs) +If you are unfamiliar with GitHub, you can also send a [micro:bit support ticket](https://support.microbit.org/support/tickets/new). ## Arm Mbed (v1 only) -The information on Arm Mbed applies to V1 only. +The information on Arm Mbed applies to micro:bit V1 only. ### Hardware and Low Level Software @@ -93,7 +104,7 @@ Of particular interest are the Mbed BLE projects, many of which were developed o ### Online IDE -Mbed also provides an online C/C++ IDE with which you can program the micro:bit. To get started with this, please see the [micro:bit Platform Page](hhttps://os.mbed.com/platforms/Microbit/) on the Mbed site, where there's a getting started video. +Mbed useddd to provide an online C/C++ IDE which could be usedd to program the micro:bit. Unfortunately the [Mbed Online IDE has been retired](https://os.mbed.com/blog/entry/keil-studio-cloud-mbed-online-compiler/). ### Mbed Source Code and Versions Used @@ -103,10 +114,10 @@ micro:bit was based on the well-established Mbed 2.0 SDK, with which Mbed 5 is c ## Nordic nRF5 SDK -The Mbed abstraction for the Nordic chip is built on top of the Nordic nRF5 SDK https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF5-SDK +The micro:bit V1 Mbed abstraction for the Nordic chip and micro:bit V2 CODAL abstraction are built on top of the [Nordic nRF5 SDK](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF5-SDK). Crucially, this includes Nordic's [Soft Device 110](https://www.nordicsemi.com/Software-and-Tools/Software/S110) V1 / [Soft Device 113](https://www.nordicsemi.com/Software-and-tools/Software/S113) V2, a binary object that gets included into any hex file for the micro:bit that manages control of the radio to allow the micro:bit to use the industry standard Bluetooth Low Energy protocols. -The SoftDevice runs on the same MCU as the user's code, and when using the Mbed BLE APIs (that the micro:bit runtime also uses), calls are made into SoftDevice. SoftDevice also occupies the highest priority interrupts, so that user code can be pre-empted by SoftDevice when this is required for the radio to function properly. +The SoftDevice runs on the same MCU as the user's code, and when using the BLE APIs that the micro:bit runtime uses, calls are made into SoftDevice. SoftDevice also occupies the highest priority interrupts, so that user code can be pre-empted by SoftDevice when this is required for the radio to function properly. V1 only. Micro:bit programs use SoftDevice S110 by default, which only allows the device to be a [GAP Peripheral](http://bluetooth-developer.blogspot.co.uk/2016/07/microbit-and-bluetooth-roles.html). It is possible to use [Soft Device S130](https://www.nordicsemi.com/Software-and-tools/Software/S130) with the micro:bit by compiling offline with Mbed, though that is beyond the scope of this documentation.