Forem: Cyril Marpaud

Impl Snake For Micro:bit - Embedded async Rust on BBC Micro:bit with Embassy

Cyril Marpaud — Mon, 28 Oct 2024 13:00:00 +0000

In this article, I will guide you through creating a Snake game in embedded Rust on the BBC Micro:bit using the asynchronous framework Embassy.

The BBC Micro:bit is a small educational board. It is equipped with an ARM Cortex-M4F nRF52833 microcontroller, a 5⨉5 LED matrix, 3 buttons (one of which is touch-sensitive), a microphone, a speaker, Bluetooth capabilities, and much more.

The complete source code of the project is available on GitLab.

Although I tried to make this article accessible to as many people as possible, some prior knowledge of Rust is recommended to understand the technical details.

The Stack

Here’s an overview of the software stack we will be using:

I will briefly explain the function of each layer in the sections below. Note that for our implementation, we only need to focus on the application layer, as the others are provided by the Rust ecosystem thanks to the incredible efforts of the community.

Architecture Support

The lowest layer (i.e., the closest to the hardware) concerns architecture support. Our microcontroller is an ARM Cortex-M4F, so we will use the cortex-m and cortex-m-rt crates, but there are others, such as riscv or x86_64. In general, these crates provide the code necessary to boot a microcontroller and interact with it (interrupts, specific instructions, etc.).

Peripheral Access Crate

The next layer is called the PAC. These are crates that provide structures and functions for reading/writing to the registers of a microcontroller in a standardized way, enabling the configuration and access to all peripherals (GPIO, SPI, I²C, etc.) without risking memory corruption or hardware errors.

PACs are generated using the svd2rust tool, which converts an SVD file describing a microcontroller's hardware into a comprehensive API.

This layer is inherently unsafe (as it reads/writes values to arbitrary addresses), but it serves the purpose of providing a safe API for embedded developers.

Hardware Abstraction Layer

In the embedded ecosystem, the embedded-hal and embedded-hal-async crates play a central role. They define traits that allow for interacting with peripherals in a generic way, which facilitates code reuse and portability across different targets.

Microcontroller manufacturers often provide specific HALs, but these are typically tailored to individual hardware and lack cross-platform compatibility. The embedded-hal and embedded-hal-async crates address this issue by offering a common high-level interface, allowing for the development of reusable, generic drivers across multiple targets.

The HAL we will use is an implementation of those traits called embassy-nrf, which provides drivers for the peripherals of the nRF52833 microcontroller.

Operating System: Embassy

Although an operating system is not strictly necessary, it is often much more convenient to delegate task and interrupt management to a third-party library. This is the role of Embassy, which provides an asynchronous runtime for microcontrollers.

It allows multiple tasks to run concurrently (either in parallel or not) in a non-blocking, asynchronous manner. This enables quick responses to events while improving performance compared to a traditional preemptive kernel and keeping the code clean and organized, without the complexity of interrupt-based programming.

The Application

Our application sits atop all these software layers. Thanks to them, we have all the tools needed to schedule tasks and access the microcontroller’s peripherals through high-level abstractions. This allows us to focus on developing our Snake game without worrying about the technical details.

Flashing with Probe-rs

To flash our application onto the board, we will use probe-rs, a powerful and flexible open-source debugging and flashing tool for embedded systems. It allows developers to program and debug a wide variety of microcontroller targets, such as ARM Cortex-M, RISC-V, and STM32 families, among many others. Probe-rs abstracts away the intricacies of different debug probes and programming interfaces, making it easier to work with a wide range of hardware.

The tool supports a wide range of targets, including our nRF52833_xxAA, which we'll be using for this project. Installation instructions are available on the tool's documentation page.

We can verify the installation with the following command:

probe-rs --help

To run software on a target, you can use the command probe-rs run, specifying the target chip with the --chip argument. For example:

probe-rs run --chip nRF52833_xxAA

This command automatically flashes and starts the program on the specified microcontroller.

Software

Project Setup

Using cargo-embassy

It is possible to create a project manually by following the instructions in Embassy's documentation. However, it is much easier and quicker to use a template that will take care of creating all the necessary configuration for us.

This is exactly what cargo-embassy was created for. Let's start by installing it:

cargo install cargo-embassy
cargo embassy --help

Next, let's generate a preconfigured project in the snake directory:

cargo embassy init --chip nrf52833_xxAA snake

Project Structure

Here's a screenshot of the filetree structure of the project:

`.cargo/config.toml`

It contains the configuration for the runner, which allows probe-rs to flash the target automatically when we use the cargo run command, and the compilation target that has been set to thumbv7em-none-eabihf:

[target.thumbv7em-none-eabihf]
runner = 'probe-rs run --chip nRF52833_xxAA'

[build]
target = "thumbv7em-none-eabihf"

`Cargo.toml`

It declares all our project's dependencies, including:

cortex-m and cortex-m-rt for supporting the microcontroller's architecture
defmt and defmt-rtt for execution logs
embassy-* for our application's functionality
panic-halt and panic-probe for panic handling

The `src` folder

It contains both main.rs, which I will describe in the next section, and fmt.rs, which provides the components necessary for displaying execution or crash logs:

assertions (assert, assert_eq, assert_ne, and debug versions)
panic (panic, unwrap, unreachable, todo...)
logs (trace, debug, info, warn, error)

`memory.x`

It is a prerequisite for using the cortex-m-rt crate. It describes the memory layout of the microcontroller.

`build.rs`

The build script is preconfigured to ensure that memory.x is available in the appropriate folder during compilation. We also need two specific linker scripts: link.x (provided by the cortex-m-rt crate) and defmt.x (for logs), which build.rs also takes care of.

`Embed.toml`

It specifies the target for the cargo embed command.

Testing the Project

Let's start with the main.rs file, which for now consists of the minimal code to blink an LED.

We are in no_std mode:

#![no_std]
#![no_main]

The main function is asynchronous, and the entry point is declared via the embassy_executor::main macro:

#[embassy_executor::main]
async fn main(_spawner: Spawner)

We will later see how to use this Spawner to start tasks.

We begin by initializing the board and retrieving the peripheral we are interested in (here, a simple output pin):

let p = embassy_nrf::init(Default::default());
let mut led = Output::new(p.P0_13, Level::Low, OutputDrive::Standard);

Then we loop, toggling its state on and off:

loop {
  led.set_high();
  Timer::after_millis(500).await;
  led.set_low();
  Timer::after_millis(500).await;
}

The pin used by the template (P0_13) does not correspond to an LED on our board. By examining the schematic of the board, we can see that each LED is at the intersection of a row and a column of the matrix. To turn one on, we need to manipulate two LEDs (ROW1 and COL1, for example).

The pin mapping gives the correspondence between the name and number of a pin. ROW1 corresponds to P0_21, while P0_28 corresponds to COL1.

According to the schematic, for the LED to light up, its row must be high and its column must be low. We will initialize these two pins to low, then toggle one regularly to see it blink:

let mut row1 = Output::new(p.P0_21, Level::Low, OutputDrive::Standard);
let mut col1 = Output::new(p.P0_28, Level::Low, OutputDrive::Standard);

loop {
  row1.set_high();
  Timer::after_millis(500).await;
  row1.set_low();
  Timer::after_millis(500).await;
}

If the LED blinks, congratulations, your project is now set up! We can move on to more advanced tasks.

Architecture

We will create three tasks:

The first will control the display through the LED matrix rows and columns.
The second will manage the controller through the button pins.
The last will handle the game logic (using the RNG to generate the snake's food).

A task is nothing more than a simple function that runs continuously. It can communicate with other tasks via primitives like Channel or Signal.

We annotate the function with the task macro and start the task with Spawner::spawn:

#[embassy_executor::task]
async fn mytask() {
  loop {
    info!("Hello, World!");
    Timer::after_millis(500).await;
  }
}

spawner.spawn(mytask());

This task now runs concurrently with other tasks and uses asynchronous programming to yield control whenever it encounters an await point. This is the principle of a cooperative system, as opposed to preemptive.

The Screen

Our first task involves display, so let's start by creating a structure representing the screen and a mechanism to receive the images to display:

mod image {
  pub const ROWS: usize = 5;
  pub const COLS: usize = 5;

  pub type Image = [[u8; COLS]; ROWS];

  pub static IMG_SIG: Signal<CriticalSectionRawMutex, Image> = Signal::new();
}

A Signal is a synchronization primitive that allows tasks to send data to each other. It is declared static to be shared and is protected from concurrent access by a CriticalSectionRawMutex.

Next, let's pass the pins corresponding to the LED matrix rows and columns to our task via two arrays:

use embassy_nrf::gpio::Pin;

let rows = [
  p.P0_21.degrade(),
  p.P0_22.degrade(),
  p.P0_15.degrade(),
  p.P0_24.degrade(),
  p.P0_19.degrade(),
];
let cols = [
  p.P0_28.degrade(),
  p.P0_11.degrade(),
  p.P0_31.degrade(),
  p.P1_05.degrade(),
  p.P0_30.degrade(),
];

Since each pin has a different type, we need to convert them to a unique type to insert them into an array. The degrade() method of the Pin trait allows us to do this by transforming them into AnyPin.

We can now modify the task prototype:

#[embassy_executor::task]
async fn display_task(r_pins: [AnyPin; image::ROWS], c_pins: [AnyPin; image::COLS]) { ... }

Let's move on to implementing the task itself: we'll start by initializing the pins in output mode:

let mut r_pins = r_pins.map(|r| Output::new(r, Level::Low, OutputDrive::Standard));
let mut c_pins = c_pins.map(|c| Output::new(c, Level::High, OutputDrive::Standard));

Then, we need to wait for the first image to be signaled for display:

let mut img = image::IMG_SIG.wait().await;

The wait function returns a Future that will resolve when the signal is emitted (i.e., when the main task sends its first image). We can thus await it.

Considering the electrical schematic, it's not possible to manage the image all at once because lighting two diagonal LEDs also lights the other two LEDs on the same row and column. We will therefore display the image line by line very quickly, relying on persistence of vision.

To do this, we need a Ticker with the appropriate frequency. 60Hz is enough for the human eye not to notice. Knowing that we have 5 lines, we can initialize it as follows:

let mut ticker = Ticker::every(Duration::from_hz(60 * img.len() as u64));

From here, we can start the display loop, which will:

Display a row of the image
Wait for a tick
Turn off the row
If a new image is signaled, update it

loop {
  for (r_pin, r_img) in r_pins.iter_mut().zip(img) {
    c_pins
      .iter_mut()
      .zip(r_img)
      .filter(|(_, c_img)| *c_img != 0)
      .for_each(|(pin, _)| pin.set_low());
    r_pin.set_high();

    ticker.next().await;

    r_pin.set_low();
    c_pins.iter_mut().for_each(|pin| pin.set_high());

    if let Some(new_img) = IMG_SIG.try_take() {
      img = new_img;
      break;
    }
  }
}

We can test this mechanism by sending it a fixed image:

const HAPPY: Image = [
  [0, 1, 0, 1, 0],
  [0, 1, 0, 1, 0],
  [0, 0, 0, 0, 0],
  [1, 0, 0, 0, 1],
  [0, 1, 1, 1, 0],
];

image::IMG_SIG.signal(HAPPY);

We now have a functional screen; all that remains is to send actual images to display.

The Controller

The control task is a bit simpler: the touch button will be used to start a game, and buttons A and B will direct the snake. We will pass them separately to the main task via a Channel and a Signal, respectively:

pub static BTN_CHAN: Channel<CriticalSectionRawMutex, Button, 10> = Channel::new();
pub static TOUCH_SIG: Signal<CriticalSectionRawMutex, ()> = Signal::new();

pub enum Button {
  A,
  B,
}

The type transmitted by the signal is (), meaning it transmits no data, only the "start signal" matters.

As with the screen, pass the pins corresponding to the buttons to the task:

let (btn_a, btn_b, touch) = (p.P0_14.degrade(), p.P0_23.degrade(), p.P1_04.degrade());
spawner.spawn(control_task(btn_a, btn_b, touch));

Modify the task prototype accordingly:

#[embassy_executor::task]
async fn control_task(btn_a: AnyPin, btn_b: AnyPin, touch: AnyPin) { ... }

Convert these pins to Inputs, allowing us to retrieve their respective states. We can see from the electrical schematic that A and B have pull-up resistors, while the touch button does not:

let mut btn_a = Input::new(btn_a, Pull::Up);
let mut btn_b = Input::new(btn_b, Pull::Up);
let mut touch = Input::new(touch, Pull::None);

Electrically, a button is a switch that closes when pressed. We will wait for a button state change from high to low, then transmit it to the main task using the Input::wait_for_falling_edge function.

This function is asynchronous and returns a future. We have three events to monitor, and we can use the select3 macro from the embassy-futures crate to handle this:

match select3(
  btn_a.wait_for_falling_edge(),
  btn_b.wait_for_falling_edge(),
  touch.wait_for_falling_edge(),
).await { ... }

When a button is pressed, one of the match arms is executed, allowing us to determine which button it is via Either3:

match { ... } {
  Either3::First(_) => BTN_CHAN.send(Button::A).await,
  Either3::Second(_) => BTN_CHAN.send(Button::B).await,
  Either3::Third(_) => TOUCH_SIG.signal(()),
}

Since switches are mechanical components, they can be subject to bouncing. To prevent triggering the same event multiple times, we can add a debounce delay:

Timer::after_millis(200).await;

Finally, place this match in an infinite loop to continuously listen for commands:

loop {
  match select3(
    btn_a.wait_for_falling_edge(),
    btn_b.wait_for_falling_edge(),
    touch.wait_for_falling_edge(),
  )
  .await
  {
    Either3::First(_) => BTN_CHAN.send(Button::A).await,
    Either3::Second(_) => BTN_CHAN.send(Button::B).await,
    Either3::Third(_) => TOUCH_SIG.signal(()),
  }

  Timer::after_millis(200).await;
}

Our controller is ready; we will retrieve commands in the main task when appropriate.

Handling the Game

This section is not intended to describe the operation of the Snake game in detail, but to focus on the interesting aspects related to embedded systems. For reference, the complete source code of the project is available on GitLab.

Broadly speaking, the main task will loop over the play function, which itself consists of the game’s three stages:

struct Game {
  state: State,
  snake: Snake,
  food: Food,
}

#[embassy_executor::task]
pub async fn main_task(rng: RNG) {
  let mut game = Game::new(rng);

  loop {
    game.play().await;
  }
}

pub async fn play(&mut self) {
  self.waiting_state().await;
  self.ongoing_state().await;
  self.over_state().await;
}

Generating the Food: Random Numbers

Start this task by passing it the RNG (Random Number Generator):

let rng = p.RNG;
spawner.spawn(main_task(rng));

As the name suggests, it allows us to generate random numbers, which is useful for placing the snake's food randomly on the screen.

As with the LEDs and buttons, the first step is to transform this peripheral into a usable programmatic object. This is what the new method does when initializing the game's state:

pub fn new(rng: RNG) -> Game {
  Game {
    state: Default::default(),
    snake: Default::default(),
    food: Food::new(Rng::new(rng, Irqs)),
  }
}

The Rng object returned by the Rng::new method implements the RngCore trait. This is very interesting because the rand crate defines the Rng trait as a subtrait of RngCore.

This means that we can use the Rng trait with our peripheral to generate random numbers more sophisticatedly than using the low-level API of the embassy_nrf crate.

For example, to generate a random number between 0 and 25:

// Import the trait into the local scope
use rand::Rng;

// ...

let rng = Rng::new(rng, Irqs);
let rand = rng.gen_range(0..25)

Binding Interrupts

The more curious among you might be wondering what the Irqs structure passed to Rng::new is and what it is for. It is a structure generated by the bind_interrupts macro, which ensures at compile-time that the RNG interrupts are bound to ISRs (Interrupt Service Routines).

Indeed, most peripherals in a microcontroller can generate interrupts to inform the core of an event. For example:

An I²C or SPI peripheral generates an interrupt to signal that a message is available on the bus.
An RNG generates an interrupt to indicate that it has finished generating a random number.
etc.

When one of these interrupts occurs, the core is interrupted and executes the corresponding ISR, which is a specific function that handles the interrupt. It is important to bind the interrupts we are interested in to ISRs to ensure they are executed when the events of interest occur.

In main.rs, we just need to bind the RNG interrupt to its ISR for everything to work correctly:

bind_interrupts!(struct Irqs {
  RNG => embassy_nrf::rng::InterruptHandler<RNG>;
});

Storing Data on no_std

Finally, I want to mention the heapless crate, which allows us to define static data structures. This means that the size of these structures is known at compile-time, and they do not require dynamic allocation. This is very useful for embedded systems where memory is limited and dynamic allocation is undesirable.

The Snake structure in my source code is a Vec with a capacity of 25 elements, the size of the screen. This means that the snake can never exceed this size, and the memory needed to store it is allocated at compile-time:

use heapless::Vec;

struct Coords {
  x: usize,
  y: usize,
}

enum Direction {
  Up,
  Right,
  Down,
  Left,
}

struct Snake(Vec<Coords, { ROWS * COLS }>, Direction);

Other structures like Deque, IndexMap, or String are also available.

Bonus: Adding Sound

The example project contains an additional task that uses the board's speaker to play simple sounds. To do this, it uses the PWM (Pulse Width Modulation) peripheral, which generates signals of variable frequency.

We can see from the pin mapping that the speaker is assigned to pin P0_00. We need to send the PWM signal to this pin. A simple technique is to use the SimplePwm driver.

For the rest, feel free to explore this path ;)

Conclusion

This project demonstrates Rust’s strengths for embedded development, especially with async programming. Rust’s memory safety and zero-cost abstractions translate directly into reliability and performance, making it well-suited for production-ready embedded and IoT.

The async model in Embassy introduces a concurrency approach where tasks are efficiently woken by wakers, similar to the way microcontrollers respond to hardware interrupts. This approach allows tasks to react quickly to events while maintaining a clean and organized code structure, without the complexity of traditional interrupt-driven programming. The PAC+HAL stack further showcases Rust's flexibility, combining low-level control with high-level abstractions to balance precision and ease of use.

Rust’s rich ecosystem, including tools like probe-rs and built-in cross-compiling support, streamlines the development process compared to more traditional languages. Setting up projects, flashing, debugging, and leveraging crates like heapless for memory-efficient data handling become more intuitive, enabling scalable and reliable embedded solutions.

As embedded systems demand modern practices, Rust’s approach to safety, async programming, and hardware flexibility, empowered by a rich ecosystem, establishes it as a mature, production-ready option for modern embedded and IoT projects.

Resources

BBC Micro:bit

The Rust Language

Embassy

Probe-rs

Dependencies

Whoami

My name is Cyril Marpaud, I'm an embedded systems freelance engineer and a Rust enthusiast 🦀 I have 10 years experience and am currently living in Lyon (France).

[![LinkedIn][linkedin-shield]][linkedin-url]

Embedded Rust on BBC Micro Bit: unlocking Vec and HashMap

Cyril Marpaud — Fri, 24 Mar 2023 09:41:55 +0000

As an engineer having spent most of 2022 learning the Rust language, I was a little worried about the no_std side of embedded systems programming.

Embedded systems, like the BBC Micro Bit (a small ARM Cortex-M4F-based computer designed for educational purposes featuring a 5×5 LED matrix, multiple sensors, Bluetooth Low Energy capabilities and a lot more), are usually programmed as bare_metal devices in a no_std environment, meaning we can't use the std crate where Vec and HashMap, among others, reside.

While very understandable when considering older devices, the growing specs and capabilities of modern devices make it increasingly tempting to use higher-level abstractions. The purpose of this tutorial is thus to demonstrate how to enable the use of Vec and HashMap on a BBC Micro Bit.

The original article and associated examples are available in my Micro Bit Vec and HashMap GitLab repository. Let us now initiate this endeavor.

Requirements

This tutorial does not require much:

A computer with internet access
A BBC Micro Bit
A USB cable
Less than an hour of your time

Setting up the OS

It is assumed that you have a fully functional 22.10 Ubuntu Linux distribution up and running. If you don't, detailed instructions to set one up can be found in my previous tutorial.

Setting up the development environment

First of all, we are going to install a few required dependencies. Open a terminal (the default shortcut is Ctrl+Alt+T) and run the following command:

sudo apt install --yes curl gcc libudev-dev=251.4-1ubuntu7 pkg-config

(installing version 251.4-1ubuntu7.1 of libudev-dev induces a crash on my machine so I'm using version 251.4-1ubuntu7 instead)

We also need to install Rust and Cargo. Rustup can take care of that for us:

curl --proto '=https' --tlsv1.2 --fail --show-error --silent https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

As we will be compiling for an ARM Cortex-M4F microcontroller, we have to install the adequate target:

rustup target add thumbv7em-none-eabihf

After compilation comes flashing. cargo embed is the solution we will be using for that purpose. Install it like so:

cargo install cargo-embed

Finally, a udev rule will take care of granting USB access to the Micro Bit:

echo "SUBSYSTEMS==\"usb\", ATTRS{idVendor}==\"0d28\", ATTRS{idProduct}==\"0204\", MODE=\"0660\", GROUP=\"plugdev\"" | sudo tee /etc/udev/rules.d/99-microbit.rules > /dev/null
sudo udevadm control --reload-rules && sudo udevadm trigger

Setting up the project

Cargo makes it easy to create a Rust project and add the adequate dependencies:

cargo init microbit
cd microbit
cargo add cortex-m-rt microbit-v2 panic_halt

Now, cargo embed needs to know which device it has to flash. Create a file named Embed.toml at the root of the project with the following content:

[default.general]
chip = "nrf52833_xxAA"

We can either specify a --target flag each time we compile our software or set that up once and for all in a configuration file. Moreover, our device's memory layout needs to be provided to the linker. Create the following .cargo/config file which will do just that for us:

mkdir .cargo
touch .cargo/config

[target.'cfg(all(target_arch = "arm", target_os = "none"))']
rustflags = [
    "-C", "link-arg=-Tlink.x",
]

[build]
target = "thumbv7em-none-eabihf"

Finally, open src/main.rs and copy/paste this LED-blink minimal example inside:

#![no_main]
#![no_std]

use cortex_m_rt::entry;
use microbit::{
    board::Board,
    hal::{prelude::*, timer::Timer},
};
use panic_halt as _;

#[entry]
fn main() -> ! {
    let mut board = Board::take().expect("Failed to take board");
    let mut timer = Timer::new(board.TIMER0);
    let mut row = board.display_pins.row1;
    let delay = 150u16;

    board.display_pins.col1.set_low().expect("Failed to set col1 low");

    loop {
        row.set_high().expect("Failed to set row1 high");
        timer.delay_ms(delay);

        row.set_low().expect("Failed to set row1 low");
        timer.delay_ms(delay);
    }
}

Blinking an LED

Plug the board to your computer then compile the program and flash it single-handedly with this simple command:

cargo embed

When the process ends, you should see the upper-left LED blink. Congratulations!

Unlocking Vec

I have to admit that I shamefully lied when I told you Vec resides in the std crate as it is actually available in the alloc crate. As the name suggests, using it requires an allocator.

Luckily, the embedded-alloc crate provides us with one (there is a complete example in the associated Github repository). We also need the cortex-m crate to handle critical sections. Add them to the project's dependencies like so:

cargo add embedded-alloc
cargo add cortex-m --features critical-section-single-core

Then, in src/main.rs, we need to customize a few things. Import Vec and declare a global allocator:

extern crate alloc;
use alloc::vec::Vec;

use embedded_alloc::Heap;

#[global_allocator]
static HEAP: Heap = Heap::empty();

At the beginning of the main function, initialize the allocator and a size for our heap (the Micro Bit has 128KiB of RAM):

{
    use core::mem::MaybeUninit;
    const HEAP_SIZE: usize = 8192; // 8KiB
    static mut HEAP_MEM: [MaybeUninit<u8>; HEAP_SIZE] = [MaybeUninit::uninit(); HEAP_SIZE];
    unsafe { HEAP.init(HEAP_MEM.as_ptr() as usize, HEAP_SIZE) }
}

Replace the main loop, using Vec:

let mut vec = Vec::new();
vec.push(true);
vec.push(false);
vec.push(true);
vec.push(false);
vec.push(false);
vec.push(false);

vec.iter().cycle().for_each(|v| {
    match v {
        true => row.set_high().expect("Failed to set row high"),
        false => row.set_low().expect("Failed to set row low"),
    }
    timer.delay_ms(delay);
});

loop {}

Finally, compile and flash:

cargo embed

The LED should now be blinking in a heartbeat pattern. You are using Rust's Vec on a Micro Bit, congratulations!

Unlocking HashMap

Unlike Vec, the alloc crate does not suffice for HashMap, full std is required (which in turn requires a nightly toolchain because std is not supported for our platform). To avoid having to type +nightly each time we invoke cargo or rustup, create a file named rust-toolchain.toml with the following content:

[toolchain]
channel = "nightly"

As building the std crate requires its source code, use rustup to fetch that component:

rustup component add rust-src

In .cargo/config, add the following lines (panic_abort is needed here because of a currently unresolved issue):

[unstable]
build-std = ["std", "panic_abort"]

The std crate provides an allocator, we can therefore remove those lines from src/main.rs:

#![no_std]

extern crate alloc;
use alloc::vec::Vec;

std also provides a panic handler, the import and panic-halt dependency can therefore be removed:

use panic_halt as _;

cargo remove panic-halt

Now that we are rid of those useless parts, there are a few things we need to add. As we're building std for an unsupported (thus flagged unstable) platform, we need the restricted_std feature. Add it to src/main.rs:

#![feature(restricted_std)]

Import HashMap:

use std::{
    collections::{hash_map::DefaultHasher, HashMap},
    hash::BuildHasherDefault,
};

And use it instead of Vec:

let mut hm = HashMap::with_hasher(BuildHasherDefault::<DefaultHasher>::default());
hm.insert(0, false);
hm.insert(1, true);
hm.insert(2, false);
hm.insert(3, true);
hm.insert(4, true);
hm.insert(5, true);

hm.values().cycle().for_each(|v| {
    match v {
        true => row.set_high().expect("Failed to set row high"),
        false => row.set_low().expect("Failed to set row low"),
    }
    timer.delay_ms(delay);
});

loop {}

The reason we are providing our own hasher is that the default one relies on the sys crate which is platform dependent. Our platform being unsupported, the associated implementation either does nothing or fails.

Therefore, keep in mind that using anything from said sys crate will either fail or hang (in particular: threads). HashMap is fine though, and the above snippet should make the LED blink in an inverted heartbeat pattern:

cargo embed

Rust's HashMap on a Micro Bit, Hooray !

Actually using HashMap

The alphabet folder of my Gitlab repository demonstrates how to display caracters on the LED matrix using a HashMap. You can flash it by running the following commands:

cd  # We need to move out of the "microbit" folder we created earlier
sudo apt install --yes git
git clone https://gitlab.com/cyril-marpaud/microbit_vec_hashmap.git
cd microbit_vec_hashmap/alphabet
cargo embed

Conclusion

The ability to use Rust collections on a device as humble as the BBC micro:bit represents a remarkable achievement in embedded programming. Thanks to recent hardware advances, even modest embedded devices can now support high-level abstractions that were once the exclusive domain of larger and more expensive systems.

Rust's efficiency and modern design make it an ideal language for taking advantage of these new capabilities and pushing the limits of what is possible on a microcontroller: developers can create complex and sophisticated projects that once seemed impossible on such small devices, from data-driven sensors to interactive games and applications.

Whether you are a seasoned expert or just getting started, the future of embedded programming is brighter than ever, and Rust is leading the way.

Whoami

My name is Cyril Marpaud, I'm an embedded systems freelance engineer and a Rust enthusiast 🦀 I have nearly 10 years experience and am currently living in Lyon (France).

How to set up a Zola website with HayFlow theme in under 15 minutes

Cyril Marpaud — Fri, 10 Mar 2023 21:15:36 +0000

(This article was written by ChatGPT based on HayFlow’s readme)

If you're looking for a clean, modern-looking website theme that's easy to set up, HayFlow is a great option. This theme is designed to work with Zola, a static site generator written in Rust, and it features a dark theme with a particles background, vertical arrows for navigation, and a few card types to choose from. Best of all, it requires only Markdown editing, so you don't need to know HTML or CSS to use it.

Prerequisites

Before you begin, you'll need to make sure you have Zola installed on your system. You'll also need to have Git installed to be able to clone the HayFlow theme repository.

Live demo

See my personal website to get a sense of what can be accomplished in a few minutes with this theme. Its source code is also available as an example in my Gitlab website repository.

1. Initialize a new Zola website

The first step is to initialize a new Zola website. Open your terminal and navigate to the directory where you want to create your new website. Then, enter the following command:

zola init mywebsite

This will create a new directory called mywebsite with the basic files and folders needed to run a Zola website.

2. Download and install the HayFlow theme

Next, you need to download and install the HayFlow theme. To do this, navigate to the mywebsite directory in your terminal and clone the repository:

cd mywebsite
git clone git@gitlab.com:cyril-marpaud/hayflow.git themes/hayflow

This will download the HayFlow theme from the GitLab repository and place it in a new directory called themes/hayflow.

3. Configure your website to use the HayFlow theme

Now that you have the HayFlow theme installed, you need to tell Zola to use it for your website. Open the config.toml file in your text editor and add the following line at the top:

theme = "hayflow"

This tells Zola to use the HayFlow theme for your website. Save the file and close it.

4. Run your website

With your website set up and customized, you're ready to run it. Open your terminal, navigate to the mywebsite directory, and enter the following command:

zola serve

This will start a local web server and open your website in your default web browser. You should see your landing page.

5. Customize your landing page

With the HayFlow theme installed and configured, you're ready to customize your landing page. Open the config.toml file again and scroll down to the [extra] section. This is where you can add variables to customize your landing page.

There are three variables you can use to customize your landing page:

name: This is your name.
roles: This is an array of strings that represent your roles or areas of expertise.
links: This is an array of objects that represent links to your social media profiles or other pages. You can use any free icon from Font Awesome.

To add your own information, simply replace the default values with your own. For example:

[extra]
name = { first = "John", last = "Doe" }

roles = ["Web Developer", "Graphic Designer", "Social Media Manager"]

links = [
   { icon = "fa-brands fa-twitter", url = "https://twitter.com/johndoe" },
   { icon = "fa-brands fa-linkedin", url = "https://www.linkedin.com/in/johndoe" },
   { icon = "fa-solid fa-envelope", url = "mailto:johndoe@example.com" },
]

Once you've made your changes, save the config.toml file and close it.

6. Add additional sections to your landing page

One of the great features of the HayFlow theme is its support for multiple sections on your landing page. You can create new sections by adding new folders inside the content directory and adding Markdown files to those folders.

For example, to create a new section called "Pizza", create a new folder inside the content directory with the name of your section (e.g. pizza) and add an _index.md file inside it with the following front matter:

+++
title = "Pizza"
+++

This will create a new section on your landing page with the title "Pizza". You can add your own content to the section by editing the _index.md file.

7. Customize section cards

HayFlow offers three types of cards for your sections: simple, columns, and list. By default, sections use the simple card type, but you can customize this by adding a card_type variable to the front matter of your _index.md file.

For example, to create a section with a columns card type, create a new folder inside the content directory with the name of your section (e.g. ingredients) and add an _index.md file with the following front matter:

+++
title = "Ingredients"
[extra]
card_type = "columns"
+++

Next, create three additional Markdown files inside the ingredients folder with names like one.md, two.md, and three.md. These files will contain the content for your columns. Here's an example front matter for the one.md file:

+++
title = "Tomatoes"
[extra]
icons = ["fa-solid fa-tomato"]
+++

Tomatoes are a delicious ingredient in many pizza recipes.

This will create a column card with a tomato icon and the title "Tomatoes".

If you want to create a section with a list card type, the process is similar. Just set the card_type variable to list in your _index.md file and create Markdown files for each item in your list. You can optionally set a link variable detailing the corresponding URL if applicable.

Conclusion

With HayFlow, you can have a beautiful and functional landing page up and running in just a few minutes. The modular design and support for multiple sections make it easy to customize your page to fit your needs, and the use of Markdown makes it easy for anyone to create and maintain their own landing page.

Whether you're a freelancer, a small business owner, or just looking to create a personal website, HayFlow is a great choice for your landing page. So why not give it a try and see what you can create?

Whoami

My name is Cyril Marpaud, I’m an embedded systems freelance engineer and a Rust enthusiast 🦀 I have nearly 10 years experience and am currently living in Lyon (France).

Embedded Rust on ESP32C3 Board, a Hands-on Quickstart Guide

Cyril Marpaud — Wed, 22 Feb 2023 19:01:33 +0000

Today, I'll be showing you how to use the Rust programming language on a Rust ESP board, a recent embedded platform packed with Wi-Fi and Bluetooth capabilities.

We won't go through the details of no_std vs std development, just know that the latter allows us to use full Wi-Fi and Bluetooth capabilities along with the actual entire Rust Standard Library with ease which is usually NOT straightforward but hey, this is 2023, enjoy!

The original article and associated examples are available in my Rust ESP Quickstart GitLab repository.

TL;DR

If you are already running Linux and just want to flash your ESP board with a fully configured Rust "Hello, World!" project, see the script/setup.sh script, it should help you get started in no time. Be aware, though, that it has been made for a freshly installed 22.10 Ubuntu distribution and is untested on any other platform yet (i.e. use it at your own risks). On the other hand, please read on if you intend to walk the learning path instead.

Requirements

Here's everything we are going to need during our little adventure:

A computer with internet access
A Rust ESP Board (this is open hardware so you can either buy one or build one yourself!)
A USB cable
An empty USB stick that we are going to erase completely so don't forget to BACKUP YOUR DATA FIRST (A 16GiB one is fine)
Less than an hour of your time

The OS

We'll be using a live 22.10 Ubuntu distribution so that:

anyone with a decent computer can follow this guide
our setups are the exact same, thus greatly reducing the rate of environment-related errors
everything is instantly reversible, meaning that your computer will be left completely untouched
we won't need to go through an actual Linux installation

One drawback of this solution is that each reboot will wipe the environment but feel free to actually install linux if persistence across said reboots is required.

Making a bootable USB stick

Download the 22.10 "Kinetic Kudu" Ubuntu ISO image here
Flash the USB stick using either usb-creator-gtk if running Linux or Win32DiskImager if running Windows

Installing `usb-creator-gtk` on Linux

Open a terminal (the default shortcut is Ctrl+Alt+T on Ubuntu) and run those commands:



sudo apt update
sudo apt install --yes usb-creator-gtk

Installing `Win32DiskImager` on Windows

Download the installer from the project's page and run it.

Flashing the USB stick

In both cases, we will need to select the ISO image we want to flash and the device we want to use then click the Write or Make startup disk button. The process should complete within a few minutes.

Booting Ubuntu

Let's ask ChatGPT how to do that:

![Booting from a USB stick](https://gitlab.com/cyril.marpaud/rust_esp_quickstart/-/raw/main/images/chatgpt_boot_from_usb.png "Booting from a USB stick")

Thank you ChatGPT ! Finally, hit that Try Ubuntu button to be greeted with a GNOME desktop.

The next steps require internet access so connect to a Wi-Fi (see the top-right corner menu) or wired network if you want to go old-school.

The tools

Here, we are going to make heavy use of a terminal. On Ubuntu, you can open one by pressing Ctrl+Alt+T. You might want to copy/paste the following commands to avoid typos but suit yourself!

Build dependencies

We need a few more packages than Ubuntu provides by default. Please bear with the trauma of installing them:



sudo add-apt-repository --yes universe
sudo apt install --yes clang curl git libudev-dev libssl-dev pkg-config python3-pip

Rust and Cargo components

We'll now use Rustup to install both Rust and Cargo (Rust's package manager):



curl --proto '=https' --tlsv1.2 --fail --show-error --silent https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup toolchain install nightly --component rust-src

Moreover, we need a few additional Cargo modules:

espflash to flash the device (see espflash)
ldproxy to forward linker arguments (see ldproxy)
cargo-generate to generate projects according to a template (see cargo-generate)



cargo install espflash ldproxy cargo-generate

Generating a project

The awesome ESP IDF Template will save us the pain of configuring a fully functional project ourselves, use it like so:



cargo generate --git https://github.com/esp-rs/esp-idf-template cargo

During the process, you will be asked a few things:

a Project Name. Go wild and use test-project, for instance
an ESP-IDF native build version. Go with the stable one (it is v4.4 at the moment)
an MCU. Our board is equipped with an ESP32C3
support for dev containers. We don't need that for now so that's a false
STD support. We're building an std app so that's a true

Hello, World!

Getting access to the USB peripheral

You might like "Permission Denied" errors. If not, those commands will create a udev rule to avoid that when accessing our board through USB:



echo "SUBSYSTEMS==\"usb\", ATTRS{idVendor}==\"303a\", ATTRS{idProduct}==\"1001\", MODE=\"0660\", GROUP=\"plugdev\"" | sudo tee /etc/udev/rules.d/99-esp-rust-board.rules > /dev/null
sudo udevadm control --reload-rules && sudo udevadm trigger

Flash, run & monitor

Now make use of that USB cable and connect the board to your computer, then run this simple yet elegant command:



cargo run

If everything goes smoothly, Cargo should build the project, flash it on the MCU and finally run it, meaning that a line reading "Hello, World!" should be displayed in the terminal. Hit Ctrl+R to restart the program (not very useful at that point but it might be later) or Ctrl+C to quit monitoring it.

Congratulations, you are officially programming Rust on your ESP board !

The IDE

We could configure Vim, Emacs or any other terminal-based IDE, but the low-friction solution is to use Visual Studio Code with the appropriate extensions. This way, we are only a few clicks away from syntax highlighting, code completion and much more.

VSCodium

It is the exact same as VSCode but without telemetry/tracking stuff, plus it uses MIT license (see the official website). Install and run it like so:



snap install codium --classic
codium

An Open Folder button should be visible in the explorer tab on the left. Click it to add our project to the workspace. We are now able to edit source code way more handily than in a terminal.

Extensions

Go to the extensions tab and type "rust analyzer" in the search bar, then click the install button ("Rust language support for Visual Studio Code"). That's it! You can find more information about it on the official website. The Even Better TOML and crates extensions might also be of interest to you.

Going further

The examples folder of this repository contains three projects:

blink: makes the LED connected to GPIO7 blink
i2c-sensors: read and display data from the embedded SHTC3 & ICM42670 I2C sensors (temperature, humidity, accelerometer & gyroscope)
Wi-Fi: very basic Wi-Fi connection + ping example, just uncomment and fill WIFI_SSID and WIFI_PWD environment variables at the bottom of .cargo/config.toml

Conclusion

As a kid, I used to boot my sister's laptop from a live 8.04 "Hardy Heron" Ubuntu CD (you could order one for free back then!) to bypass her password protection. This way, no one ever knew what I was doing (meerely looking for cheat codes for the games I used to play at the time 😉️). Today, I still believe this technique is of great value to anyone wishing to try something out without breaking anything.

Growing up, I then had the pleasure to learn how embedded development can sometimes be a pain: messy setup, weird and abstruse error messages... But hopefully, it has been less than an hour since you began reading this article and you are now able to use a modern language with std support on a recent Wi-Fi-enabled microcontroller. Ain't that marvelous ?

I hope you enjoyed it as much as I do, especially when considering the tremendous amount of work that was needed to make this so easy for us.

Cheers!

Whoami

My name is Cyril Marpaud, I'm an embedded systems freelance engineer and a Rust enthusiast 🦀 I have nearly 10 years experience and am currently living in Lyon (France).

Forem: Cyril Marpaud

Impl Snake For Micro:bit - Embedded async Rust on BBC Micro:bit with Embassy

The Stack

Architecture Support

Peripheral Access Crate

Hardware Abstraction Layer

Operating System: Embassy

The Application

Flashing with Probe-rs

Software

Project Setup

Using cargo-embassy

Project Structure

.cargo/config.toml

Cargo.toml

The src folder

memory.x

build.rs

Embed.toml

Testing the Project

Architecture

The Screen

The Controller

Handling the Game

Generating the Food: Random Numbers

Binding Interrupts

Storing Data on no_std

Bonus: Adding Sound

Conclusion

Resources

Further Reading

BBC Micro:bit

The Rust Language

Embassy

Probe-rs

Dependencies

Whoami

Embedded Rust on BBC Micro Bit: unlocking Vec and HashMap

Requirements

Setting up the OS

Setting up the development environment

Setting up the project

Blinking an LED

Unlocking Vec

Unlocking HashMap

Actually using HashMap

Conclusion

See also (aka useful links)

Documentation

Crates

Tutorials

Whoami

How to set up a Zola website with HayFlow theme in under 15 minutes

Prerequisites

Live demo

1. Initialize a new Zola website

2. Download and install the HayFlow theme

3. Configure your website to use the HayFlow theme

4. Run your website

5. Customize your landing page

6. Add additional sections to your landing page

7. Customize section cards

Conclusion

Whoami

Embedded Rust on ESP32C3 Board, a Hands-on Quickstart Guide

TL;DR

Requirements

The OS

Making a bootable USB stick

Installing usb-creator-gtk on Linux

Installing Win32DiskImager on Windows

Flashing the USB stick

Booting Ubuntu

The tools

Build dependencies

Rust and Cargo components

Generating a project

Hello, World!

Getting access to the USB peripheral

Flash, run & monitor

`.cargo/config.toml`

`Cargo.toml`

The `src` folder

`memory.x`

`build.rs`

`Embed.toml`

Installing `usb-creator-gtk` on Linux

Installing `Win32DiskImager` on Windows