microbit Rust Board Support Crate

The micro:bit has different hardware versions that require different Rust crates and compilation targets. Use the following mapping to select the correct crate for your board:

• micro:bit V1: Use the microbit crate. Target: thumbv6m-none-eabi.
• micro:bit V2: Use the microbit-v2 crate. Target: thumbv7em-none-eabihf.

To run examples and flash firmware, you need to install probe-rs-tools and flip-link. These tools facilitate debugging and safe stack overflow protection.

Run the following command to install them via cargo:

cargo install probe-rs-tools flip-link

To flash and run an example from this repository, plug in your micro:bit and use cargo run with the appropriate features and target for your hardware version.

For micro:bit V1

Use the --features v1 flag and the thumbv6m-none-eabi target.

For micro:bit V2

Use the --features v2 flag and the thumbv7em-none-eabihf target.

# For micro:bit V1
cargo run --release --manifest-path ./examples/display-blocking/Cargo.toml --features v1 --target thumbv6m-none-eabi

# For micro:bit V2
cargo run --release --manifest-path ./examples/display-blocking/Cargo.toml --features v2 --target thumbv7em-none-eabihf

The Board struct organizes the micro:bit V2 hardware into logical groups. Key components include:

• buttons: Access to button_a and button_b.
• display_pins: Pins used to drive the 5x5 LED matrix.
• microphone_pins: Includes mic_in and mic_run.
• speaker_pin: The pin connected to the onboard speaker.
• edge: Unused GPIO pins on the edge connector (e.g., e00, e01, e02, e08, e09, e12, e16).
• pins: Other unused GPIO pins on P0 and P1.
• i2c_internal: Internal I2C bus pins (scl, sda).
• i2c_external: External I2C bus pins (scl, sda).
• uart: UART pins for the debugger (tx, rx).

Additionally, the Board struct exposes all nRF52 peripherals (like RADIO, TIMER, TWIM, UARTE, ADC, etc.) and Core peripherals (like NVIC, SYST, SCB) directly as public fields.

The Board struct organizes hardware into logical groups. You can convert these groups directly into HAL-compatible pin sets using the From trait:

• Buttons: Access button_a and button_b via board.buttons.
• I2C: Convert board.i2c into twi::Pins using .into().
• UART: Convert board.uart into uart::Pins using .into() (configured for the debugger pins).

// I2C Example
let i2c_pins: twi::Pins = board.i2c.into();

// UART Example
let uart_pins: uart::Pins = board.uart.into();

Before using this crate, verify your hardware version. This microbit crate is specifically for the original micro:bit (V1).

If your hardware is the newer version (V2), do not use this crate; instead, use the microbit-v2 crate.

The microbit crate supports both micro:bit v1 and v2 hardware, but they cannot be enabled simultaneously. You must select exactly one version using Cargo features in your Cargo.toml:

• For micro:bit v1: Enable the v1 feature (uses nrf51_hal).
• For micro:bit v2: Enable the v2 feature (uses nrf52833_hal).

Attempting to build with both features enabled will result in a compilation error.

# Example for micro:bit v2
[dependencies]
microbit = { version = "0.16.0", features = ["v2"] }

The display_pins! macro simplifies the construction of the DisplayPins struct by automatically configuring the necessary row and column pins for the micro:bit V1 LED matrix. It takes the P0 GPIO parts as input and initializes all pins as Output<PushPull> with an initial Level::Low.

# use microbit_common as microbit;
use microbit::{
    display_pins,
    pac,
    hal::gpio::p0::Parts as P0Parts,
};

// take the peripherals
let p = pac::Peripherals::take().unwrap();
// split off the P0 GPIO port
let p0parts = P0Parts::new(p.GPIO);

// Initialize the display pins
let pins = display_pins!(p0parts);

If you have already taken the pac::Peripherals and pac::CorePeripherals (for example, in an RTIC application), you can use Board::new(p, cp) to wrap them into a Board instance. This is a fallback method used when the standard take() pattern is not applicable.

// Assuming p and cp are already obtained via pac::Peripherals::take() and pac::CorePeripherals::take()
let board = Board::new(p, cp);

The Board struct provides a high-level abstraction for all peripherals on a micro:bit V1. To access the board safely, use the take() method. This method returns Some(Board) the first time it is called, but will return None on subsequent calls or if the underlying peripherals have already been taken elsewhere. This ensures singleton access to the hardware.

let board = Board::take().expect("Failed to take board peripherals");
// Use board.buttons, board.display_pins, etc.