How kacman62/pi-pico-handheld-dice works
Project Type and Purpose
• This is a hardware-software co-design for an embedded, handheld Dungeons & Dragons device (“DM Atlas”) built around a Raspberry Pi Pico 2 on a custom KiCad PCB, with a 3D-printed case and custom UI art.
• Core functionality: roll dice, display character/enemy stats, render animations and images on a small screen, all controlled via onboard buttons.
High-Level Components
A. Hardware Layer
1. Custom PCB
• Raspberry Pi Pico 2 (RP2040 microcontroller)
• Power management & battery charging circuit
• GPIO lines to display, buttons, encoder knob
2. Peripherals
• LCD/OLED display for UI
• Input buttons (4 corners) + rotary encoder knob
• Battery, charging port
3. Mechanical Enclosure
• Onshape-designed top/bottom case, encoder knob, mounting points
B. Software/Firmware Layer
1. Bootloader & Runtime (RP2040 SDK)
2. PlatformIO Build System (platformio.ini)
3. Application Modules (Code/src/)
• main.cpp: initialization & main loop, state machine
• animations.cpp/h: sprite/transition routines
• dice.cpp/h: dice-roll logic, random number generator
• images.cpp/h: UI assets exported from Aseprite
4. Abstraction & Libraries (Code/include/ and Code/lib/)
• Hardware abstraction (GPIO, SPI/I²C for display)
• Utility libraries (e.g., random, button debounce)
5. Tests (Code/test/)
External Tools & Data Flow
• VS Code + PlatformIO: edit, compile, link, and flash firmware over USB
• Aseprite: author PNG/bitmap assets → converted into .cpp image headers
• KiCad: schematic/PCB → generates Gerbers for manufacturing
• Onshape: CAD model for 3D printing
Relationships & Interactions
• Bootloader → loads firmware into RP2040
• Firmware’s main() initializes hardware abstraction layer (HAL) for display, buttons, battery ADC
• Event loop:
• Read inputs (buttons/encoder) → dispatch to menu/dice logic (dice.cpp)
• Update UI state → call animations module
• Push pixel/frame buffer to display via SPI/I²C driver
• Power management circuit provides stable 3.3 V to RP2040 and peripherals, monitors battery state
Architectural Patterns & Principles
• Layered architecture: Hardware Abstraction → Core Logic (dice, animations, images) → Application State Machine
• Modular code organization: each functional area in its own .cpp/.h pair
• Single-threaded, event-driven loop suitable for microcontrollers
• Separation of concerns: asset code (images.cpp) generated from art, logic code (dice, animations) separate
• Host Development Environment (VS Code + PlatformIO)
• Firmware Build & Flash Pipeline
• RP2040 Microcontroller (include HAL & runtime)
• Modules: Input Handler, Dice Logic, UI/Animation, Display Driver
• Hardware: Display, Buttons, Encoder, Battery & Charger, PCB
• Mechanical Case (optional, for completeness)
• Host → Build → Firmware Binary → Flash → RP2040
• RP2040 ↔ Display (SPI/I²C data lines)
• RP2040 ← Buttons/Encoder (GPIO inputs)
• UI module → Display Driver → Display
• Dice Logic → UI state changes
• Battery Circuit → RP2040 power rails
c. Technologies & Frameworks:
• RP2040 SDK / PlatformIO framework
• C++17 classes/enums for logic modules
• Aseprite asset pipeline → images.cpp
• KiCad for PCB
• Onshape for case CAD