# pimoroni/pimoroni-pico architecture

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

- Interactive diagram: https://gitdiagram.com/pimoroni/pimoroni-pico
- Repository: https://github.com/pimoroni/pimoroni-pico

## Overview

##### Project Type and Purpose
- This repository is a hybrid ecosystem: it provides hardware interface libraries (drivers and board-specific libraries), higher-level examples and applications, and custom MicroPython builds (with board configuration files) for Pimoroni add-ons and breakouts.
- Its purpose is to allow users to quickly build applications (either in C/C++ or MicroPython) for various RP2040 systems, controlling displays, sensors, and other peripherals.

##### High-Level Components
a. Core Build and Configuration Layer:
– CMake files (CMakeLists.txt at the root and subdirectories) that govern the build process.
– CI pipeline definitions in the .github/workflows to ensure automated testing and integration.
b. Common and Drivers:
– The “common” directory with shared components and utility functions for Pimoroni.
– The “drivers” folder that contains individual subdirectories for many sensors and peripherals (analog, i2c drivers, and many device-specific drivers such as for bme280, hub75, etc.).
– These drivers implement low-level hardware interfaces that are reused by the libraries and examples.
c. Libraries:
– The “libraries” directory holds board packs, display graphics, font libraries, and other support code that builds on the drivers.
– It acts as an abstraction layer that can supply common functionality (like Pico Display, Pico Explorer, etc.) to both products and examples.
d. Examples:
– Both the “examples” and the “micropython/examples” directories showcase sample projects that demonstrate how to use the drivers and libraries.
– For C/C++ examples, these reside outside the micropython folder; for MicroPython, there’s a dedicated section.
e. MicroPython Specifics:
– The “micropython” folder encapsulates board definitions (under micropython/board), project-specific modifications for MicroPython (including modules, examples, and modules_py), and various MicroPython builds.
– Board configuration files (e.g., board.json, manifest.py) for different Pimoroni boards are maintained here.
f. CI and Build Infrastructure:
– GitHub workflows (.github/workflows) for building and testing using different configurations (CMake, MicroPython builds, PicoW, etc.).
– Import scripts for pico-sdk integrations (e.g., pico_sdk_import.cmake, pimoroni_pico_import.cmake).

##### Relationships and Interactions
– Drivers feed into both libraries and examples. For instance, a specific sensor driver from the “drivers” directory is used by corresponding libraries in “libraries” and demonstrated in “examples”.
– The core projects (both C/C++ and MicroPython) depend on the board configurations that reside in the micropython/board hierarchy.
– The CI pipelines rely on the CMake and build configuration files to run automated builds across different targets.
– External tools (pico-sdk and MicroPython builds) sit outside the project structure but are essential to the build and deployment pipelines.

##### Architectural Patterns and Technologies
– Modularity is key: each driver and library is designed to be independent yet composable.
– The project leverages the CMake build system to manage a large number of sub-projects and to support cross-compilation for the RP2040.
– For MicroPython, it follows a “batteries-included” approach where board-specific firmware builds integrate custom drivers.
– CI/CD configurations indicate an emphasis on automatic testing and integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Tools
    External["External Tools (pico-sdk, MicroPython builds)"]:::external

    %% Core Build and Configuration Layer
    subgraph "Core Build and Configuration"
        cmake["CMakeLists.txt"]:::build
        pico_sdk["pico_sdk_import.cmake"]:::build
        pim_pico["pimoroni_pico_import.cmake"]:::build
        ci["CI Pipelines (.github/workflows)"]:::ci
        ci_mpy["CI Script (ci/micropython.sh)"]:::ci
    end

    %% Common and Drivers Layer
    subgraph "Common and Drivers"
        common["Common Utilities (common)"]:::module
        drivers["Hardware Drivers (drivers)"]:::module
    end

    %% Libraries Layer
    subgraph "Libraries"
        libraries["High-Level Libraries (libraries)"]:::module
    end

    %% Examples and MicroPython Ecosystem
    subgraph "Examples"
        c_cpp["C/C++ Examples (examples)"]:::module
        micropython_board["Board Config & Modules (micropython)"]:::micropython
        micropython_examples["MicroPython Examples (micropython/examples)"]:::micropython
    end

    %% Relationships and Data Flow
    External --> cmake
    External --> ci

    cmake --> common
    pico_sdk --> common
    pim_pico --> common
    ci --> common
    ci_mpy --> common

    common --> libraries
    drivers --> libraries

    drivers --> c_cpp
    libraries --> c_cpp

    ci --> micropython_board
    drivers --> micropython_board

    micropython_board --> micropython_examples
    libraries --> micropython_examples
    drivers --> micropython_examples

    %% Styles
    classDef external fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef build fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef ci fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef module fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef micropython fill:#FFA07A,stroke:#CD5C5C,stroke-width:2px;

    %% Click Events
    click cmake "https://github.com/pimoroni/pimoroni-pico/blob/main/CMakeLists.txt"
    click pico_sdk "https://github.com/pimoroni/pimoroni-pico/blob/main/pico_sdk_import.cmake"
    click pim_pico "https://github.com/pimoroni/pimoroni-pico/blob/main/pimoroni_pico_import.cmake"
    click ci "https://github.com/pimoroni/pimoroni-pico/tree/main/.github/workflows"
    click ci_mpy "https://github.com/pimoroni/pimoroni-pico/blob/main/ci/micropython.sh"
    click common "https://github.com/pimoroni/pimoroni-pico/tree/main/common"
    click drivers "https://github.com/pimoroni/pimoroni-pico/tree/main/drivers"
    click libraries "https://github.com/pimoroni/pimoroni-pico/tree/main/libraries"
    click c_cpp "https://github.com/pimoroni/pimoroni-pico/tree/main/examples"
    click micropython_board "https://github.com/pimoroni/pimoroni-pico/tree/main/micropython"
    click micropython_examples "https://github.com/pimoroni/pimoroni-pico/tree/main/micropython/examples"
```
