# openstickcommunity/gp2040-ce architecture

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

- Interactive diagram: https://gitdiagram.com/openstickcommunity/gp2040-ce
- Repository: https://github.com/openstickcommunity/gp2040-ce

## Overview

This project is a multi-platform gamepad firmware—GP2040-CE—that runs on RP2040 microcontrollers (for example, the Raspberry Pi Pico) and supports a wide range of devices such as PC, various consoles (PlayStation, Xbox, Nintendo Switch, etc.), and even dual-mode functionality (input processing while driving LEDs, displays, and buzzers). It is a firmware product with a rich set of drivers and configuration layers, plus an integrated web configuration system served from an embedded http server.

##### And outline the main system components
- Firmware Core on RP2040:
- Input Processing Engine that gathers button presses, joystick positions, and so on.
- Device Drivers: Quite a few directories exist under src/drivers (e.g., drivers for PS3, PS4, XBOne, Keyboard, etc.), plus drivers for HID, USB, I2C, and even display protocols.
- Event and Configuration Management: Managed via modules in “headers” and “src” (for example, config_utils.cpp, configmanager.cpp, eventmanager.cpp, and storagemanager.cpp). Also, board-specific configuration files in the “configs” directory stand out as an essential part of tailoring the firmware for various hardware variants.
- Communication Layer: Includes USB (via TinyUSB), I2C interfaces (for displays, PCF8575, SSD1306, etc.), and SPI in some cases. This layer is abstracted in headers (interfaces, i2c sections) and source code.
- Core Libraries and Utility Functions: Organized under lib (e.g., NanoPB for protocol buffers, OneBitDisplay, PicoPeripherals) that support low-level hardware interactions and data encoding/decoding.

- Web-Based Configuration Frontend:
- Web Server and Embedded HTTPD: Located in “lib/httpd” and the “www/server” directory, it provides the built-in web configuration solution.
- Frontend Application: Found in the “www” folder with the typical modern web stack—React components (.jsx, .tsx), styles (.scss), and configuration files. This frontend allows custom splash screens upload, LED profile setups, and wire configuration for the gamepad.
- Integration with Backend: The embedded HTTPD and APIs (under “www/server/app.js”) likely interact with configuration storage provided by the firmware’s configuration manager.

- Build and Integration Components:
- Build System: The top-level CMakeLists.txt, various CMake scripts (CMakeFiles in “configs”, “lib”, “modules”, etc.), and Node.js-based workflows (see .github/workflows/node.js.yml).
- Third-Party Integrations: Such as TinyUSB for USB handling, NanoPB for Protocol Buffers based on the “proto” and “lib/nanopb” directories, providing structured messaging.

##### Relationships & Data Flow
- From Input to Processing: The firmware reads controller inputs via device drivers, which forward events to the event manager and configuration modules.
- Configuration and Customization: A dedicated configuration system reads board-specific settings (from “configs”) and might be updated via an embedded web UI (over HTTP served by the firmware). Configuration changes are then applied to adjust driver behavior, LED profiles, and display outputs.
- Communication: The firmware communicates with a host via USB (using classes from drivers, TinyUSB) and may also serve the web configuration pages on an internal network interface.
- Build and Deployment: CMake and Node.js workflows ensure that firmware builds, libraries compile, and the web UI is packaged (using scripts like makefsdata.js).

##### Architectural Patterns and Technologies
- Modular Design & Separation of Concerns: The project distinctly separates hardware-specific configurations (in “configs”), core firmware logic (in “src” and “headers”), and peripheral libraries (in “lib”).
- Abstraction Layers: Drivers are abstracted under “drivers” in addition to clearly defined interfaces in “headers/interfaces,” ensuring that hardware changes do not affect the central firmware logic.
- Client-Server Web Integration: The “www” directory represents a modern web application architecture (React/TypeScript) that interacts with the embedded HTTP server.
- Use of CMake and GitHub workflows enforce CI/CD integration into the build system, ensuring that tests (also visible in “lib/nanopb/tests”) and firmware configuration management are maintained.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GP2040-CE Firmware System"
        subgraph "Firmware Core"
            IP["Input Processing Engine"]:::fw
            DD["Device Drivers"]:::fw
            ECM["Event & Config Manager"]:::fw
            BSC["Board-Specific Configs"]:::fw
            CS["Communication Layer"]:::fw
            CL["Core Libraries & Utilities"]:::fw

            IP -->|"processes"| DD
            DD -->|"sendsEvents"| ECM
            BSC -->|"configures"| ECM
            ECM -->|"controls"| CS
            CS -->|"uses"| CL
        end

        subgraph "Web Configuration & UI"
            EHS["Embedded HTTP Server"]:::web
            FA["Frontend Application"]:::web

            FA -->|"interactsWith"| EHS
            EHS -->|"updatesConfig"| ECM
        end
    end

    subgraph "Build System"
        BS["Build System"]:::build
    end

    BS -->|"builds"| IP
    BS -->|"builds"| DD
    BS -->|"builds"| ECM
    BS -->|"builds"| EHS
    BS -->|"builds"| FA

    CS -->|"USB/I2C/SPI"| PI["Peripheral Interfaces"]:::ext

    click IP "https://github.com/openstickcommunity/gp2040-ce/blob/main/src/main.cpp"
    click DD "https://github.com/openstickcommunity/gp2040-ce/tree/main/src/drivers"
    click ECM "https://github.com/openstickcommunity/gp2040-ce/blob/main/headers/configmanager.h"
    click BSC "https://github.com/openstickcommunity/gp2040-ce/tree/main/configs"
    click CS "https://github.com/openstickcommunity/gp2040-ce/blob/main/headers/usbdriver.h"
    click CL "https://github.com/openstickcommunity/gp2040-ce/tree/main/lib/nanopb"
    click EHS "https://github.com/openstickcommunity/gp2040-ce/tree/main/lib/httpd"
    click FA "https://github.com/openstickcommunity/gp2040-ce/tree/main/www"
    click BS "https://github.com/openstickcommunity/gp2040-ce/blob/main/CMakeLists.txt"

    classDef fw fill:#DDEEFF,stroke:#1F78B4,stroke-width:2px;
    classDef web fill:#FFEEDD,stroke:#E69F00,stroke-width:2px;
    classDef build fill:#E5FFCC,stroke:#33A02C,stroke-width:2px;
    classDef ext fill:#FFCCCC,stroke:#E31A1C,stroke-width:2px;
```
