microbadge/docs/sdd.md

MicroBadge Software Design Document

1. Introduction

1.1 Purpose

MicroBadge is a software application suite for the BBC micro:bit v2, designed as a digital conference badge. It serves both functional and social purposes; displaying the user’s name, hosting small interactive demos, and offering contact sharing via NFC.

This project serves as a conversation starter and technical showcase during events like conferences, meetings, and interviews.

1.2 Scope

This document focuses exclusively on the software implementation of MicroBadge. It covers the architecture, data structures, behavior, and design choices used to implement the badge’s app-switching system and core applications using Rust and the embassy async runtime.

1.3 Audience

This document is intended for:

• Reviewers evaluating its design.
• Recruiters or interviewers reviewing technical work.
• Anyone trying to learn how to write Rust on an embedded platform.

2. System Overview

MicroBadge is an embedded application for the micro:bit v2. It uses the Embassy async runtime to manage multiple cooperative tasks without a traditional RTOS. The system is modular and consists of an app switcher, an LED display task, button listeners, and multiple interactive apps.

2.1 Runtime and Concurrency

MicroBadge uses Embassy's async executor. It runs the following tasks:

• display_task -- Consumes frame buffers and drives the LED matrix.
• button_listener -- One per button (A, B, Start). Waits for input and debounces it before sending an event.
• app_task -- Runs the currently selected app. Allows apps to yield and re-enter on each loop.

All communication is channel-based using embassy_sync::channel::Channel.

[Task UML][./uml/tasks.png]

2.2 App Switcher

The Switcher manages app selection and transition. It displays a menu and uses the A, B, and Start buttons to navigate between apps.

Each app implements a shared App trait with an async run() method. Apps are isolated and run cooperatively, returning control when done.

Current apps:

• Menu. The top-level app that allows selecting from installed apps.
• Badge. Scrolls a string (e.g. your name) across the LED matrix.
• Snake. A basic snake game with food, direction control, and score.
• NFC Card (in development). Will present contact info via NFC.

[Switcher UML][./uml/switcher.png]

2.3 Input System

Each button is handled by a separate button_listener task. When a button is pressed, it sends a Button enum into a shared channel.

Apps listen for button input using the receiver end of the channel.

• A and B buttons are mapped to actions like turn left and right.
• Start is used to confirm or start an app. It is mapped to the capacitive touch sensor logo.
• A debounce delay of 100 ms is used for stability.

2.4 Rendering System

The rendering system uses a frame buffer that is written by the active app and read by the display_task.

Apps write into this buffer using a Renderer abstraction. Drawing is done in an offscreen buffer that is later pushed to the display.

• The screen is a 5x5 LED grid.
• Per-frame updates allow for animations and dynamic content.
• LED brightness levels are supported.

2.5 Code Organization

The system is split into modules for clarity and reuse:

• app. Defines the App trait and shared app interface.
• display. Low-level display driver and LED control.
• renderer. Provides drawing primitives for apps.
• channel. Shared async channels for button and frame messages.
• switcher. App selection logic and switching behavior.
• snake, menu, badge. App implementations.
• microbit. Definitions for button identifiers and device pins.

Each module is self-contained and uses only the shared channels and traits for interaction.

3. Application Features

3.1 Name Scroller

• Scrolls a configured name across the LED display.
• Uses an async timer to advance frames.
• Simple input handling: Any Button returns to the menu.

3.2 Snake Game

• 5x5 LED grid snake game using a wrapped grid (WrappedU8<0, 4>).
• Buttons A and B turn the snake left/right.
• Food spawns randomly in empty grid cells.
• On collision with self, enters game-over state and displays score.

3.3 NFC Business Card (WIP)

• Intended to broadcast a vCard or custom URI over NFC.
• Plan to use the BLE softdevice on the chip.
• Currently under development.

4. System Architecture

This system uses Embassy's async runtime to coordinate application execution, hardware input, and rendering on the micro:bit v2 board. It is divided into distinct tasks: input listeners, a display task, and an app task.

The overall architecture is message-passing oriented. Input events and screen updates are communicated over embassy channels.

Application logic is encapsulated in independent modules conforming to a shared App trait. The Switcher manages the active app and transitions between them.

4.1 Components

• main.rs: Entry point. Spawns system tasks using Embassy.
• Display: Renders 5x5 LED frames from a channel receiver using PWM.
• ButtonListener: Listens for button presses and sends events via channel.
• Switcher: Manages app lifecycle and transitions.
• App: Trait for any runnable application module.
• menu, badge, snake, nfc: App implementations.

5. Data Structures and State

5.1 Position, Direction, and Snake Body

The board is a fixed 5×5 grid. Positions are stored using a custom Position struct, which holds a ClampedU8 for both x and y axes, ensuring values remain within bounds.

• Position: Represents a coordinate on the board with safe bounds.
• Direction: Enum for movement direction: Up, Down, Left, Right.
• Snake: Maintains a list of Position elements representing the snake's body. The first item is always the head.

Snake direction is updated via input, and movement wraps to stay within the board.

5.2 Message-Passing and Input State

User input is handled asynchronously via Embassy channels.

• Button presses are detected using button_listener tasks.
• Events are sent to the ButtonChannel.
• Applications read input non-blockingly using try_receive().

This decouples physical input handling from application logic and allows clean, testable state transitions.

6. Component Interactions

6.1 How Components Interact Over Time

At runtime, three core tasks are running:

• display_task: Receives rendered frames and presents them on the display.
• button_listener: Spawns three tasks, one per button (A, B, Start).
• app_task: Owns the app switcher and runs the current app.

All interactions are asynchronous and use message-passing over embassy channels.

6.2 Flow of Control

1. User presses a button.
2. The button task sends a message to the channel.
3. The app reads the button event from the channel.
4. The app updates internal state (e.g., direction or selection).
5. The app prepares a frame and sends it to the frame channel.
6. The display task renders the frame.

This loop repeats, giving a responsive, concurrent embedded UI.

7. Development Environment

7.1 Rust + Embassy

This project uses Rust with the embassy async runtime. It provides interrupt-driven, non-blocking execution suitable for low-power embedded devices.

7.2 Tools

• probe-rs: For flashing and debugging firmware.
• defmt: Lightweight logging for embedded targets.
• panic-probe: Panic handler integrated with defmt output.
• cargo-embed: For development workflow and flashing.

Development was done on Linux using vim and CLI tooling.

8. Design Decisions

8.1 Why Embassy

Embassy was chosen for its async-first architecture, which maps well to reactive, event-driven embedded applications like games and UI. It allows multiple concurrent tasks without needing an RTOS or blocking code.

8.2 Fixed Board Size

The micro:bit's 5×5 LED matrix is inherently fixed. Game logic and rendering are simplified by using a constant-size grid, avoiding the need for dynamic allocation or scaling logic.

8.3 Data Wrapping and Clamping

Out-of-bounds positions are prevented using custom ClampedU8 types. These provide safe arithmetic that prevents overflow and keeps all positions within 0–4 inclusive. This reduces bugs and runtime checks in critical loops.

9. Future Work

9.1 NFC Business Card App

An in-progress app will emulate a contact card via NFC. The goal is to allow devices to scan the badge and receive contact information, a URL, or a vCard.

9.3 UI Polish