# addy771/simple-pico-vesc-display architecture

> Architecture diagram of the GitHub repository addy771/simple-pico-vesc-display, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/addy771/simple-pico-vesc-display
- Repository: https://github.com/addy771/simple-pico-vesc-display

## Overview

##### Project type and purpose
- This is an embedded firmware project (“Simple Pico VESC Display”) for the Raspberry Pi Pico (RP2040) that interfaces with VESC motor controllers over UART/CAN, renders a real‐time dashboard on an SSD1306 display, and logs data to microSD via FatFS.

##### File structure
- Top-level code files (buffer.c/h, display.cpp, packet.c/h, page_ctrl.cpp/h, log.cpp/hpp, nv_flash.cpp/hpp, hw_def.c/h, hw_config.c, crc.c/h) implement application logic, hardware abstraction, communication parsing, UI state, logging, and non-volatile storage.
- The “FatFS-SD” directory is the microSD SPI file-system module.
- The “u8g2” submodule provides the SSD1306 graphics library and drivers.
- The “bldc” directory is the VESC firmware source (GPL) included for reference or cross-compilation.
- CMakeLists.txt and pico_sdk_import.cmake orchestrate the build using the pico-sdk, often invoked via a Docker toolchain.

##### Extract insights from README
- Interfaces: UART or CAN to external VESC controllers.
- Outputs: SSD1306 (SPI-driven via PIO code), microSD logging.
- Build: cross-compile with pico-sdk under Docker, generate “display” binary.

##### Main components
a. Hardware Components
- RP2040 Microcontroller (dual-core, PIO engines)
- SSD1306 OLED Display (SPI/P0 bit-bang)
- microSD card (SPI, FatFS)
- External VESC Motor Controller(s) (UART and/or CAN bus)
- On-board QSPI flash (for nv_flash storage)
b. Software Modules (on RP2040)
- Hardware Abstraction Layer (hw_def, hw_config)
- PIO Drivers (spi_tx_9bit.pio)
- Comm Manager (UART/CAN receiver, packet.c parser)
- Data Model (datatypes.h structures for speed, voltage, etc.)
- UI Controller (page_ctrl: state machine for dashboard pages)
- Renderer (buffer.c/h, u8g2 library draws into frame buffer)
- Storage Manager (FatFS-SD drivers, nv_flash for config)
- Logging (log.cpp/hpp writes parsed data to SD via FatFS)
- Utility (crc check, buffer management, packet framing)
c. Build System
- CMake + pico-sdk
- Docker cross-compile environment

##### Relationships and data flow
- **Data In**: VESC → (UART/CAN) → Comm Manager → Packet Parser → Data Model
- **Application**: Data Model → Page Controller → Display Renderer → PIO SPI → SSD1306
- **Logging**: Data Model / Log module → FatFS → microSD
- **Config/State**: nv_flash module ↔ QSPI flash (stores user prefs, calibration)
- **Hardware Layer**: HAL provides pin mappings to Comm, PIO, SD drivers

##### Architectural patterns
- Layered architecture:
- HAL Layer (hw_def/config, PIO drivers)
- Driver Layer (UART/CAN, SPI, FatFS, u8g2)
- Service Layer (Comm Manager, Storage Manager, Logging)
- Application Layer (Page Controller, UI Renderer)
- State-machine pattern in page_ctrl for UI navigation.
- Producer–consumer pattern: incoming data feeds both UI and logger.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Components
    subgraph "Hardware Interfaces" 
        direction TB
        VESC["External VESC Controller(s)"]:::hardware
        SSD["SSD1306 OLED Display"]:::hardware
        SD["microSD Card"]:::hardware
        QSPI["On-board QSPI Flash"]:::hardware
    end

    %% Firmware Layers on RP2040
    subgraph "RP2040 Firmware"
        direction TB

        subgraph "HAL Layer"
            direction TB
            HAL_DEF["hw_def.c/h"]:::hal
            HAL_CFG["hw_config.c"]:::hal
        end

        subgraph "Driver Layer"
            direction TB
            PIO1["spi_tx_9bit.pio"]:::driver
            PIO2["spi_tx_9bit.pio.h"]:::driver
            PIO3["button_debounce.pio.h"]:::driver
            U8G2["u8g2 Library"]:::driver
            FATFS["FatFS-SD Module"]:::driver
        end

        subgraph "Service Layer"
            direction TB
            COMM["Comm Manager"]:::service
            STORAGE["Storage Manager"]:::service
            LOG["Logging Service"]:::service
        end

        subgraph "Application Layer"
            direction TB
            MODEL["Data Model"]:::app
            PAGE["UI Controller"]:::app
            RENDER["Display Renderer"]:::app
        end
    end

    %% Build System
    subgraph "Build System"
        direction TB
        CMAKE["CMakeLists.txt"]:::build
        SDKIMPORT["pico_sdk_import.cmake"]:::build
        BUILDWIN["build.bat"]:::build
        READMD["README.md"]:::build
    end

    %% External Reference
    BBLDC["bldc/ (VESC Firmware)"]:::external

    %% Data Flow
    VESC -->|UART/CAN| COMM
    COMM -->|"parsed packets"| MODEL
    MODEL -->|"state data"| PAGE
    PAGE -->|"UI state"| RENDER
    RENDER -->|"SPI PIO"| SSD
    MODEL -->|"data stream"| LOG
    LOG -->|"FatFS"| SD
    STORAGE -->|"config read/write"| QSPI
    HAL_DEF --> COMM
    HAL_DEF --> RENDER
    HAL_DEF --> STORAGE
    PIO1 --> RENDER
    PIO2 --> RENDER
    PIO3 --> PAGE
    U8G2 --> RENDER
    FATFS --> STORAGE
    COMM -->|"uses"| PACKET
    PACKET["packet.c/h"]:::service
    BUF["buffer.c/h"]:::service
    CRC["crc.c/h"]:::service
    COMM --> PACKET
    COMM --> BUF
    LOG --> BUF
    LOG --> FATFS

    MODEL --> DATAT["datatypes.h"]:::app

    PAGE --> PAGEF["page_ctrl.cpp/hpp"]:::app
    RENDER --> DISP["display.cpp"]:::app
    STORAGE --> NV["nv_flash.cpp/hpp"]:::driver

    %% Build connections
    CMAKE --> SDKIMPORT
    CMAKE --> BUILDWIN
    CMAKE --> READMD

    %% External reference
    BBLDC -.-> CMAKE

    %% Click Events
    click HAL_DEF "https://github.com/addy771/simple-pico-vesc-display/blob/main/hw_def.c"
    click HAL_DEF "https://github.com/addy771/simple-pico-vesc-display/blob/main/hw_def.h"
    click HAL_CFG "https://github.com/addy771/simple-pico-vesc-display/blob/main/hw_config.c"
    click PIO1 "https://github.com/addy771/simple-pico-vesc-display/blob/main/spi_tx_9bit.pio"
    click PIO2 "https://github.com/addy771/simple-pico-vesc-display/blob/main/spi_tx_9bit.pio.h"
    click PIO3 "https://github.com/addy771/simple-pico-vesc-display/blob/main/button_debounce.pio.h"
    click PACKET "https://github.com/addy771/simple-pico-vesc-display/blob/main/packet.c"
    click PACKET "https://github.com/addy771/simple-pico-vesc-display/blob/main/packet.h"
    click BUF "https://github.com/addy771/simple-pico-vesc-display/blob/main/buffer.c"
    click BUF "https://github.com/addy771/simple-pico-vesc-display/blob/main/buffer.h"
    click DATAT "https://github.com/addy771/simple-pico-vesc-display/blob/main/datatypes.h"
    click PAGEF "https://github.com/addy771/simple-pico-vesc-display/blob/main/page_ctrl.cpp"
    click PAGEF "https://github.com/addy771/simple-pico-vesc-display/blob/main/page_ctrl.hpp"
    click DISP "https://github.com/addy771/simple-pico-vesc-display/blob/main/display.cpp"
    click U8G2 "https://github.com/addy771/simple-pico-vesc-display/tree/main/u8g2/"
    click FATFS "https://github.com/addy771/simple-pico-vesc-display/tree/main/FatFS-SD/"
    click NV "https://github.com/addy771/simple-pico-vesc-display/blob/main/nv_flash.cpp"
    click NV "https://github.com/addy771/simple-pico-vesc-display/blob/main/nv_flash.hpp"
    click LOG "https://github.com/addy771/simple-pico-vesc-display/blob/main/log.cpp"
    click LOG "https://github.com/addy771/simple-pico-vesc-display/blob/main/log.hpp"
    click CRC "https://github.com/addy771/simple-pico-vesc-display/blob/main/crc.c"
    click CRC "https://github.com/addy771/simple-pico-vesc-display/blob/main/crc.h"
    click BBLDC "https://github.com/addy771/simple-pico-vesc-display/tree/main/bldc/"
    click CMAKE "https://github.com/addy771/simple-pico-vesc-display/blob/main/CMakeLists.txt"
    click SDKIMPORT "https://github.com/addy771/simple-pico-vesc-display/blob/main/pico_sdk_import.cmake"
    click BUILDWIN "https://github.com/addy771/simple-pico-vesc-display/blob/main/build.bat"
    click READMD "https://github.com/addy771/simple-pico-vesc-display/blob/main/README.md"

    %% Styles
    classDef hardware fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef hal fill:#fbe3f3,stroke:#c2185b,stroke-width:1px
    classDef driver fill:#bbdefb,stroke:#1976d2,stroke-width:1px
    classDef service fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef app fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
    classDef build fill:#eceff1,stroke:#607d8b,stroke-width:1px
    classDef external fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
```
