diff --git a/README.md b/README.md index 4a8303f..002527d 100644 --- a/README.md +++ b/README.md @@ -98,13 +98,16 @@ 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 -o ./docs/design.pdf +pandoc ./docs/design.md --pdf-engine=weasyprint -o ./docs/design.pdf ``` ### Software Design Doc @@ -113,7 +116,7 @@ The [Software Design Doc][./docs/sdd.pdf] is generated with pandoc from the mark file. ```bash -pandoc ./docs/sdd.md -o ./docs/sdd.pdf +pandoc ./docs/sdd.md --pdf-engine=weasyprint -o ./docs/sdd.pdf ``` ### UML diff --git a/docs/design.md b/docs/design.md deleted file mode 100644 index f518056..0000000 --- a/docs/design.md +++ /dev/null @@ -1,76 +0,0 @@ -# Design Document: MicroBadge - -## Overview - -**MicroBadge** is an interactive embedded application built for the BBC -micro:bit v2. It is written in **Rust** using the **Embassy** async embedded -runtime. The project functions as a **conference name badge** that acts as a -professional and technical icebreaker at events. - -The application framework includes: -* A **menu system** for switching between apps. -* A **name scroller** for displaying your name or custom message. -* A **Snake game** for fun and interactivity. -* A **NFC business card** app for sharing contact info. **Still in progress** - -## Goals - -* Provide a custom and memorable name badge experience. -* Showcase embedded Rust development using async and no-std. -* Enable fun interactions and sharing via NFC. -* Serve as a technical portfolio piece for conferences, meetings, and - interviews. - -## Architecture - -### 1. Core Framework - -* Built on **Embassy** for asynchronous concurrency. -* Uses hardware abstraction layers (HALs) for GPIO, timers, display, and - buttons. -* Implements a lightweight app-switcher system with a menu UI. - -### 2. Applications - -#### Name Scroller -* Scrolls a name or message across the LED matrix. -* Configurable for speed and repeat mode. -* Useful for identifying the wearer at a glance. - -#### Snake Game -* Classic Snake game rendered on the 5x5 LED display. -* Uses `Button A` and `Button B` for turning. -* Includes food spawning, score tracking, and difficulty selection. -* Uses PWM for different intensity led lights. - -#### NFC Business Card (WIP) -* Leverages the onboard NFC peripheral. -* Intends to share vCard/contact data over NFC. -* Targeted at mobile phones for quick transfer of contact info - -## User Interaction - -* Navigation is handled via micro:bit's `Button A`, `Button B`, and long-press `Start` gesture -* LED matrix provides visual feedback for game states and menu navigation -* Apps are selected from a simple menu UI -* Snake game is tuned to a slower speed (~4Hz) for usability - -## Development Environment - -* Written entirely in **Rust**, `#![no_std]` -* Uses **Embassy** for async device access and task scheduling -* Debugging output via `defmt` -* Built and flashed using `probe-rs` and `cargo-embed` - -## Future Improvements - -* Finalize NFC vCard transmission -* Add configuration storage via flash memory -* Create a desktop companion app for editing settings -* Support BLE for data sync or configuration - -## Summary - -MicroBadge combines a fun hardware platform with modern Rust development. -It serves not only as a name badge but also as a way to demonstrate embedded -skills, share contact info, and invite technical discussion at events. diff --git a/docs/design.pdf b/docs/design.pdf deleted file mode 100644 index 1eaf304..0000000 Binary files a/docs/design.pdf and /dev/null differ diff --git a/docs/prd.md b/docs/prd.md new file mode 100644 index 0000000..2a6d78c --- /dev/null +++ b/docs/prd.md @@ -0,0 +1,264 @@ +# MicroBadge +## Product Design Document +**Version:** 1.0 +**Date:** July 11, 2025 +**Author(s):** CyberMages, LLC (Jason Smith) +**Stakeholders:** Self, Potential Conference Attendees, Hobbyists + +--- + +1. [Introduction](#introduction) + - [Purpose of this Document](#purpose-of-this-document) + - [Product Overview](#product-overview) + - [Target Audience](#target-audience) + - [Scope](#scope) +2. [Business Case & Goals](#business-case-goals) + - [Problem Statement](#problem-statement) + - [Business Objectives](#business-objectives) + - [Key Performance Indicators (KPIs)](#key-performance-indicators-kpis) +3. [User Stories / Use Cases / Features](#user-stories-use-cases-features) + - [User Personas](#user-personas) + - [Core Features](#core-features) + * [Menu System](#menu-system) + * [Name Scroller](#name-scroller) + * [NFC Business Card](#nfc-business-card) + * [Snake Game](#snake-game) + - [Out-of-Scope Features](#out-of-scope-features) +4. [User Experience (UX) & User Interface (UI)](#user-experience-ux-user-interface-ui) + - [User Flows](#user-flows) + - [Wireframes / Mockups](#wireframes-mockups) + - [Interaction Design](#interaction-design) + - [Accessibility Considerations](#accessibility-considerations) + - [Brand & Style Guidelines](#brand-style-guidelines) +5. [Technical Considerations (High-Level)](#technical-considerations-high-level) + - [System Integrations](#system-integrations) + - [Performance Requirements](#performance-requirements) + - [Security Considerations](#security-considerations) + - [Data Privacy](#data-privacy) +6. [Release Plan & Roadmap](#release-plan-roadmap) + - [Phased Rollout Strategy](#phased-rollout-strategy) + - [Future Considerations / Roadmap](#future-considerations-roadmap) +7. [Success Metrics & Analytics](#success-metrics-analytics) + - [Key Metrics to Track](#key-metrics-to-track) + - [Analytics Tools](#analytics-tools) +8. [Open Questions and Assumptions](#open-questions-and-assumptions) + - [Open Questions](#open-questions) + - [Assumptions](#assumptions) +9. [Appendices](#appendices) + - [Glossary](#glossary) + - [References](#references) + +--- + +## Introduction +### Purpose of this Document +This document defines the **product vision**, **features**, and **user +experience** for MicroBadge, an interactive name badge application, to guide +its development and align on its purpose. + +### Product Overview +**MicroBadge** is an interactive embedded application built for the BBC +micro:bit v2, functioning as a **conference name badge**. It provides a +**professional and technical icebreaker** at events through various +interactive apps. + +### Target Audience +* Professionals attending conferences and networking events. +* Individuals looking for unique icebreakers and conversation starters. +* Developers interested in embedded Rust and interactive hardware. +* Anyone seeking a personalized, memorable name badge experience. + +### Scope +This document covers the **initial release** of MicroBadge, including its +core menu system, name scroller, Snake game, and the NFC business card +functionality. + +## Business Case & Goals +### Problem Statement +* Traditional name badges are often static and unengaging, failing + to facilitate professional or technical icebreaking effectively. +* Networking often lacks memorable, interactive elements. +* Sharing contact information can be cumbersome. + +### Business Objectives +* Provide a **custom and memorable name badge experience**. +* Enable **fun interactions** and **easy sharing of contact info via NFC**. +* Serve as a **technical portfolio piece** for conferences, meetings, + and interviews. +* **Showcase embedded Rust development** using async and no-std. + +### Key Performance Indicators (KPIs) +* Number of positive comments received about the badge. +* Frequency of badge-initiated conversations. +* Successful NFC contact transfers (post-completion). +* Completion rate of the Snake game by others. + +--- + +## User Stories / Use Cases / Features +### User Personas +* **Conference Attendee Alex:** Wants to easily display their name, + engage in lighthearted interactions, and quickly share contact + details without fumbling for cards. +* **Tech Enthusiast Tara:** Appreciates the technical sophistication + and wants to use the badge as a conversation starter about embedded + Rust. + +### Core Features +#### Menu System +**Description:** Allows the user to switch between different + applications on the micro:bit. + +**User Stories:** As a user, I want to easily navigate between different + badge functionalities so I can quickly access the app + I need. + +**Acceptance Criteria:** +* Menu is visible on the LED matrix. +* Navigation via physical buttons is intuitive and responsive. +* Selecting an app loads it promptly. + +**Priority:** Must Have + +#### Name Scroller +**Description:** Scrolls a user-defined name or custom message + across the 5x5 LED matrix. + +**User Stories:** As a conference attendee, I want my name to scroll across + the badge so others can easily identify me from a distance. + +**Acceptance Criteria:** +* Name scrolls smoothly and is legible. +* Scrolling text supports English ASCII characters only. +* Speed and repeat mode are configurable (future state). + +**Priority:** Must Have + +#### NFC Business Card +**Description:** Leverages the onboard NFC peripheral to share vCard/contact + data with mobile phones. + +**User Stories:** As a user, I want to quickly share my contact information + by tapping my badge on a phone, saving time and effort. + +**Acceptance Criteria:** +* Badge emits vCard data via NFC upon activation. +* Mobile phones can successfully read and import the data. + +**Priority:** Must Have + +#### Snake Game +**Description:** A classic Snake game playable on the 5x5 LED display, + designed for fun and interactivity. + +**User Stories:** As a user, I want a simple, engaging game on my badge to + break the ice or pass time. + +**Acceptance Criteria:** +* Game renders correctly on the 5x5 LED matrix. +* Controls (Button A, Button B for turning) are responsive. +* Game includes food, score tracking, and game over conditions. +* Game speed is tuned for usability. + +**Priority:** Should Have + +### Out-of-Scope Features +* Configuration storage via flash memory. +* Desktop companion app for editing settings. +* BLE for data sync or configuration. + +## User Experience (UX) & User Interface (UI) +### User Flows +* **Power On:** Device boots, then goes directly to the main menu. +* **App Selection:** From main menu, user presses Button A to cycle + through apps, Button B to select. +* **App Interaction:** User interacts with the active app (e.g., + scrolling name, playing Snake). +* **Return to Menu:** Pressing the **Reset button** on the back of + the device returns to the main menu. + +### Wireframes / Mockups +The primary UI is the **5x5 LED matrix**. Visuals are abstract patterns or +simple character representations. (No detailed wireframes beyond conceptual +understanding of 5x5 limits). + +### Interaction Design +* `Button A`: Navigation (e.g., move down in menu, turn left in Snake). +* `Button B`: Selection (e.g., select app, turn right in Snake). +* `Start Button` (capacitive touch logo): Its function varies by app: + - In the **Menu**, it selects the currently highlighted application. + - In the **Name Scroller**, pressing any button (A, B, or Start) + will return to the main menu. + - In the **Snake game**, the Start button is used for selections + within the game (e.g., choosing difficulty). +* LED matrix provides immediate **visual feedback** for selections, game + states, and menu navigation. + +### Accessibility Considerations +Limited by the 5x5 LED matrix. Focus is on **clear, distinct visual +patterns** where possible. + +### Brand & Style Guidelines +Adheres to the physical aesthetic of the BBC micro:bit v2, with simple, +functional LED display patterns. + +## Technical Considerations (High-Level) +### System Integrations +* Onboard NFC peripheral (for NFC Business Card app). +* GPIO for button input. +* LED matrix display control. + +### Performance Requirements +* Menu navigation must be responsive. +* Snake game refresh rate tuned for smooth play. + +### Security Considerations +NFC data transfer should minimize privacy risks (e.g., only share public +contact info). No sensitive data stored. + +### Data Privacy +VCard data intended for public sharing only. No personal data collected or +stored by the application itself. + +## Release Plan & Roadmap +### Phased Rollout Strategy +Initial single release. No phased rollout planned for this version. + +### Future Considerations / Roadmap +* Finalize NFC vCard transmission. +* Add configuration storage via flash memory for user preferences. +* Create a desktop companion app for easier settings editing. +* Support BLE for data synchronization or advanced configuration. + +## Success Metrics & Analytics +### Key Metrics to Track +As listed in section 4.3 (e.g., qualitative feedback, observations of +interaction, NFC transfer success rate). + +### Analytics Tools +Primarily anecdotal observation and direct user feedback due to the +embedded, standalone nature of the device. + +## Open Questions and Assumptions +### Open Questions +* Exact vCard data format for NFC compatibility across devices. +* Optimal user experience for NFC activation on the micro:bit. + +### Assumptions +* Users will be familiar with basic micro:bit interactions. +* The 5x5 LED matrix provides sufficient visual fidelity for intended + applications. +* NFC peripheral provides reliable data transfer. + +## Appendices +### Glossary +**Embassy:** An asynchronous embedded runtime for Rust. +**HALs:** Hardware Abstraction Layers, providing a consistent API for + hardware peripherals. +**micro:bit v2:** A small, programmable computer designed for + education and hobbyists. +**NFC:** Near Field Communication, a set of communication protocols. +**PWM:** Pulse-width modulation, used for controlling LED intensity. +**vCard:** An electronic business card file format. + +### References diff --git a/docs/sdd.pdf b/docs/sdd.pdf deleted file mode 100644 index 89237d9..0000000 Binary files a/docs/sdd.pdf and /dev/null differ