# kacman62/pi-pico-handheld-dice architecture

> Architecture diagram of the GitHub repository kacman62/pi-pico-handheld-dice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kacman62/pi-pico-handheld-dice
- Repository: https://github.com/kacman62/pi-pico-handheld-dice

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development Tools (Orange)
    subgraph "Development Environment" 
        direction TB
        VSCode["VS Code"]:::tools
        PlatformIO["PlatformIO Build System"]:::tools
        Aseprite["Aseprite Asset Pipeline"]:::tools
        KiCad["KiCad PCB Design"]:::tools
        Onshape["Onshape CAD Models"]:::tools
    end

    VSCode -->|edit/compile| PlatformIO
    Aseprite -->|export images| ImagesModule
    KiCad -->|generate Gerbers| PCBDir
    Onshape -->|export STEP files| CaseDir

    %% Firmware Build & Flash Pipeline
    PlatformIO -->|reads platformio.ini| PlatformIOIni
    PlatformIO -->|build firmware| FirmwareBin["Firmware Binary"]:::tools
    FirmwareBin -->|flash over USB| RP2040

    %% PCB Assembly (Hardware Layer, Blue)
    subgraph "PCB Assembly" 
        direction TB
        RP2040["RP2040 Microcontroller\n(Raspberry Pi Pico 2)"]:::hardware
        PowerCircuit["Power Management & Charger"]:::hardware
        Connectors["GPIO & Interfaces"]:::hardware
    end

    %% Peripherals
    Display["LCD/OLED Display"]:::hardware
    Buttons["Input Buttons"]:::hardware
    Encoder["Rotary Encoder Knob"]:::hardware
    Battery["Battery & Charging Port"]:::hardware

    RP2040 -->|3.3V power| PowerCircuit
    PowerCircuit -->|power rails| RP2040
    RP2040 -->|SPI/I2C data| Display
    RP2040 -->|GPIO inputs| Buttons
    RP2040 -->|GPIO inputs| Encoder

    %% Mechanical Enclosure
    CaseDir["Mechanical Enclosure (3D Print)"]:::hardware

    %% Firmware Modules (Green)
    subgraph "Firmware Modules" 
        direction TB
        MainLoop["main.cpp\nState Machine"]:::firmware
        HAL["Hardware Abstraction Layer"]:::firmware
        InputHandler["Input Handler"]:::firmware
        DiceLogic["Dice Logic Module"]:::firmware
        AnimationsModule["Animations Module"]:::firmware
        ImagesModule["UI Assets Module"]:::firmware
        DisplayDriver["Display Driver"]:::firmware
        Tests["Tests"]:::firmware
        HAL --> MainLoop
        MainLoop --> InputHandler
        InputHandler --> DiceLogic
        DiceLogic --> MainLoop
        MainLoop --> AnimationsModule
        MainLoop --> ImagesModule
        AnimationsModule --> DisplayDriver
        ImagesModule --> DisplayDriver
        DisplayDriver --> Display
    end

    %% Click Events for Component Mapping
    click PCBDir "https://github.com/kacman62/pi-pico-handheld-dice/tree/main/KiCad Custom PCB DMA"
    click CaseDir "https://github.com/kacman62/pi-pico-handheld-dice/tree/main/Case Print Files"
    click PlatformIOIni "https://github.com/kacman62/pi-pico-handheld-dice/blob/main/Code/platformio.ini"
    click MainLoop "https://github.com/kacman62/pi-pico-handheld-dice/blob/main/Code/src/main.cpp"
    click AnimationsModule "https://github.com/kacman62/pi-pico-handheld-dice/blob/main/Code/src/animations.cpp"
    click DiceLogic "https://github.com/kacman62/pi-pico-handheld-dice/blob/main/Code/src/dice.cpp"
    click ImagesModule "https://github.com/kacman62/pi-pico-handheld-dice/blob/main/Code/src/images.cpp"
    click HAL "https://github.com/kacman62/pi-pico-handheld-dice/tree/main/Code/include/"
    click HAL "https://github.com/kacman62/pi-pico-handheld-dice/tree/main/Code/lib/"
    click Tests "https://github.com/kacman62/pi-pico-handheld-dice/tree/main/Code/test/"
    click VSCode "https://github.com/kacman62/pi-pico-handheld-dice/tree/main/Code/.vscode/"
    click VSCode "https://github.com/kacman62/pi-pico-handheld-dice/blob/main/Code/.gitignore"

    %% Styles
    classDef hardware fill:#cde8ff,stroke:#0666a3,color:#0666a3;
    classDef firmware fill:#d9f7be,stroke:#267326,color:#267326;
    classDef tools fill:#ffe5b4,stroke:#e68a00,color:#e68a00;
```
