microbadge/README.md

# MicroBadge

[![License-Shield][license-shield]][license-url]
[![LinkedIn-Shield][linkedin-shield]][linkedin-url]


MicroBadge is a software application suite for the BBC micro:bit v2, designed
as a digital conference badge.


---

<!-- TABLE OF CONTENTS -->
<details>
  <summary>Table of Contents</summary>
  <ol>
    <li>
      <a href="#about-the-project">About The Project</a>
      <ul>
        <li><a href="#features">Features</a></li>
      </ul>
      <ul>
        <li><a href="#built-with">Built With</a></li>
      </ul>
    </li>
    <li>
      <a href="#project-structure">Project Structure</a>
    </li>
    <li>
      <a href="#getting-started">Getting Started</a>
      <ul>
        <li><a href="#prerequisites">Prerequisites</a></li>
        <li><a href="#build-and-flash">Build and Flash</a></li>
      </ul>
    </li>
    <li><a href="#copyright-&-license">Copyright & License</a></li>
  </ol>
</details>

## About The Project

This project provides a modular and extensible application framework for the
BBC micro:bit. It supports multiple interactive applications with a shared UI
and rendering infrastructure. It uses message-passing channels and safe numeric
arithmetic via bounded, clamped, and wrapped integer types.

## Features

* Modular application management with a switcher component.
* Menu, Snake, Badge, and future NFC applications included.
* Real-time rendering to the micro:bit LED matrix.
* Button input driven by asynchronous event channels.
* Renderer abstraction for pixel-level control.
* Channel-based messaging for input and output decoupling.
* Safe integer handling using bounded, clamped, and wrapped types.

### Built With

* [Embassy][embassy-url]
* [defmt][defmt-url]

## Project Structure

```text
src/
├── main.rs                 Entry point of the application.
├── menu/                   The Menu Applicaiton.
├── badge/                  The Badge Application.
├── snake/                  The Snake Application.
```

## Getting Started

### Prerequisites

* Properly installed [Rust toolchain][rust-url].
* gdb-multiarch Tested version: 15.0.50.
* minicom Tested version: 2.9.
* [cargo-binutils][binutils-url] Tested Version: 0.3.6.
* [probe-rs-tools][probers-url] Tested Version: 0.24.

The [Rust discovery book][discovery-setup] has a great section on how to setup a
build environment.

Make sure you have the correct bulid target installed.

```bash
rustup target add thumbv7em-none-eabihf
```

### Build and Flash

To build and flash the program to your Microbit just run:

```bash
cargo embed
```

## Documentation

To generate all the documentation you will need to have pandoc and weasyprint
installed.

### Design Doc

The [Design Doc][./docs/design.pdf] is generated with pandoc from the markdown
file.

```bash
pandoc ./docs/design.md --pdf-engine=weasyprint -o ./docs/design.pdf
```

### Software Design Doc

The [Software Design Doc][./docs/sdd.pdf] is generated with pandoc from the markdown
file.

```bash
pandoc ./docs/sdd.md --pdf-engine=weasyprint -o ./docs/sdd.pdf
```

### UML

[UML][./docs/uml/] is generated using Plant UML on the \*.puml files.

```bash
plantuml ./docs/uml/*.puml
```
---

## Copyright & License

Copyright 2025 CyberMages LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this library except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS





[license-shield]: https://img.shields.io/badge/License-Apache%202.0-%23008400?style=for-the-badge&
[license-url]: https://workshop.cybermages.tech/myrddin/microbadge/src/branch/main/LICENSE.md
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://www.linkedin.com/in/jason-smith-cybermages/
[embassy-url]: https://github.com/embassy-rs/embassy
[defmt-url]: https://github.com/knurling-rs/defmt
[rust-url]: https://www.rust-lang.org/learn/get-started
[binutils-url]: https://github.com/rust-embedded/cargo-binutils
[probers-url]: https://probe.rs/docs/overview/about-probe-rs/
[discovery-setup]: https://docs.rust-embedded.org/discovery-mb2/03-setup/index.html