Adjusted the Design Document.
The Design Document is now the Product Design Document (PRD). It was rewritten to be a bit more in line with just describing the why and what of the product, not the how. It might not be perfect, but it is good enough. The README was adjusted to document that we are using the weasyprint pdf-engine for pandoc. I had started with just using the LaTex engine, but when you get to heading level 4, the heading is classified as a paragraph and not a proper heading. Also, all generated documents (*.pdf) were removed from the repository.
This commit is contained in:
@ -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
|
||||
|
||||
@ -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.
|
||||
BIN
docs/design.pdf
BIN
docs/design.pdf
Binary file not shown.
264
docs/prd.md
Normal file
264
docs/prd.md
Normal file
@ -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
|
||||
BIN
docs/sdd.pdf
BIN
docs/sdd.pdf
Binary file not shown.
Reference in New Issue
Block a user