The build files and project documents.

This sets up the basic build for the microbit project. The documentation
needed to code against it has been assembled in the documents directory.

README.md

@@ -1,6 +1,97 @@
-# microbadge
+# MicroBadge
 
-MicroBadge is a software application suite for the BBC micro:bit v2, designed as a digital conference badge.
+[![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.
+```
+
+## 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
+```
 
 
 
@@ -18,3 +109,18 @@ You may obtain a copy of the License at
 
 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