# jvpernis/esp32-ps3 architecture

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

- Interactive diagram: https://gitdiagram.com/jvpernis/esp32-ps3
- Repository: https://github.com/jvpernis/esp32-ps3

## Overview

##### Project Type and Purpose
- This is an embedded library (PS3 Controller Host) for ESP32-based projects. It provides C/C++ APIs to connect and interact with a PS3 controller over Bluetooth (via ESP-IDF or Arduino).
- Key use cases: reading button/analog/accelerometer data, sending rumble commands, LED control, and retrieving the ESP32’s MAC address for pairing.

##### High-Level File Structure Analysis
- Top-level
- library.properties, keywords.txt – Arduino library metadata
- component.mk – ESP-IDF component build descriptor
- examples/… – Arduino sketches demonstrating library usage
- src/
- Ps3Controller.cpp/.h – C++ wrapper and user-facing API for Arduino
- ps3.c, ps3_l2cap.c, ps3_parser.c, ps3_spp.c – Core PS3 protocol implementation in C
- src/include/ps3.h, ps3_int.h – Public and internal headers
- src/osi/allocator.h, bt_target.h – OS-abstraction layer (memory, platform)
- src/stack/… – Bluetooth stack API definitions (L2CAP, GAP, SPP, HCI types)

##### Key Components
a. User Application Layer
- Arduino sketch or ESP-IDF app
- Calls Ps3.begin(), ps3Init(), registers callbacks
b. PS3 Controller Host Library
- C++ API (Ps3Controller.cpp/h)
- C core modules:
- Protocol parsers & packet handlers (ps3_parser.c)
- L2CAP channel management (ps3_l2cap.c)
- SPP transport layer (ps3_spp.c)
- Main logic & state machine (ps3.c)
- OSI Abstraction (allocator.h, bt_target.h)
- Stack definitions (stack/*.h)
c. Bluetooth Stack (Espressif Bluedroid/Dual-mode)
- HCI driver, L2CAP, GAP, SPP implementation provided by ESP-IDF
d. Hardware
- ESP32 SoC (Bluetooth radio & controller)
- PS3 Controller (BR/EDR Bluetooth device)
e. External Tools (pairing utilities)

##### Relationships and Data Flow
1. User App → C++ API calls (begin, set callbacks)
2. C++ API → C Core (state machine, event loop)
3. C Core → OSI → ESP-IDF Bluetooth stack APIs
4. Stack → HCI → Bluetooth radio
5. Radio ↔ PS3 Controller (pairing, data packets)
6. PS3 packets → Radio → Stack → C Core → User callbacks

##### Architectural Patterns and Principles
- Layered Architecture:
- Presentation (C++ API)
- Domain Logic (PS3 protocol handlers)
- Platform Abstraction (OSI layer)
- Infrastructure (ESP-IDF Bluetooth stack & hardware)
- Separation of Concerns: clear borders between user API, protocol implementation, and hardware abstraction.
- Extensibility: OSI layer allows porting to other RTOS or Arduino; header-only stack definitions ease customization.

##### Final Recommendations
- Break the Library layer into sub-modules (C++ API, C core, OSI, stack definitions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Application Layer
    subgraph "User Application Layer" 
        direction TB
        Examples["Arduino Sketches (examples/)"]:::user
        App["ESP-IDF App"]:::user
    end

    %% Library Layer
    subgraph "PS3 Controller Host Library"
        direction TB
        subgraph "C++ API" 
            direction TB
            CPP["Ps3Controller.cpp/.h"]:::user
        end
        subgraph "C Core Modules"
            direction TB
            Core["ps3.c (State Machine)"]:::core
            Parser["ps3_parser.c"]:::core
            L2CAP["ps3_l2cap.c"]:::core
            SPP["ps3_spp.c"]:::core
        end
        subgraph "Public/Internal Headers"
            direction TB
            PubH["ps3.h"]:::core
            IntH["ps3_int.h"]:::core
        end
        subgraph "OSI Abstraction"
            direction TB
            Alloc["allocator.h"]:::abs
            BTTarget["bt_target.h"]:::abs
        end
        subgraph "Stack Definitions"
            direction TB
            BTTypes["bt_types.h"]:::stack
            BtmAPI["btm_api.h"]:::stack
            GAP["gap_api.h"]:::stack
            HCI["hcidefs.h"]:::stack
            L2CAPI["l2c_api.h"]:::stack
            L2CDefs["l2cdefs.h"]:::stack
            Profiles["profiles_api.h"]:::stack
        end
    end

    %% Bluetooth Stack Layer
    subgraph "ESP-IDF Bluetooth Stack (Bluedroid)" 
        direction TB
        HCIDrv["HCI Driver"]:::stack
        L2CAPStack["L2CAP"]:::stack
        GAPStack["GAP"]:::stack
        SPPStack["SPP"]:::stack
    end

    %% Hardware Layer
    subgraph "Hardware"
        direction TB
        ESP32[(ESP32 SoC)]:::hardware
        PS3Ctrl(["PS3 Controller"]):::hardware
    end

    %% Build & Metadata
    subgraph "Build & Metadata"
        direction TB
        CMK["component.mk"]:::metadata
        LibProp["library.properties"]:::metadata
        Keywords["keywords.txt"]:::metadata
        README["README.md"]:::metadata
        GitIgn[".gitignore"]:::metadata
    end

    %% Connections
    Examples -->|"calls Ps3.begin(), set callbacks"| CPP
    App -->|API calls| CPP
    CPP -->|"ps3Init(), event loop"| Core
    Parser -->|parses packets| Core
    L2CAP -->|manages channels| Core
    SPP -->|transport layer| Core
    Core -->|uses OSI calls| Alloc
    Core -->|uses OSI calls| BTTarget
    Alloc -->|malloc/free| HCIDrv
    BTTarget -->|platform config| HCIDrv
    BTTypes -->|type defs| HCIDrv
    BtmAPI -->|API| L2CAPStack
    GAP -->|API| GAPStack
    HCI -->|commands| HCIDrv
    L2CAPI -->|API| L2CAPStack
    L2CDefs -->|defs| L2CAPStack
    Profiles -->|profiles| SPPStack
    HCIDrv -->|HCI transport| ESP32
    L2CAPStack -->|L2CAP packets| ESP32
    GAPStack -->|GAP signaling| ESP32
    SPPStack -->|SPP transport| ESP32
    ESP32 -->|BR/EDR Bluetooth| PS3Ctrl
    PS3Ctrl -->|data packets| ESP32

    %% Click Events
    click Examples "https://github.com/jvpernis/esp32-ps3/tree/master/examples/"
    click CPP "https://github.com/jvpernis/esp32-ps3/blob/master/src/Ps3Controller.cpp"
    click CPP "https://github.com/jvpernis/esp32-ps3/blob/master/src/Ps3Controller.h"
    click Core "https://github.com/jvpernis/esp32-ps3/blob/master/src/ps3.c"
    click Parser "https://github.com/jvpernis/esp32-ps3/blob/master/src/ps3_parser.c"
    click L2CAP "https://github.com/jvpernis/esp32-ps3/blob/master/src/ps3_l2cap.c"
    click SPP "https://github.com/jvpernis/esp32-ps3/blob/master/src/ps3_spp.c"
    click PubH "https://github.com/jvpernis/esp32-ps3/blob/master/src/include/ps3.h"
    click IntH "https://github.com/jvpernis/esp32-ps3/blob/master/src/include/ps3_int.h"
    click Alloc "https://github.com/jvpernis/esp32-ps3/blob/master/src/osi/allocator.h"
    click BTTarget "https://github.com/jvpernis/esp32-ps3/blob/master/src/common/bt_target.h"
    click BTTypes "https://github.com/jvpernis/esp32-ps3/blob/master/src/stack/bt_types.h"
    click BtmAPI "https://github.com/jvpernis/esp32-ps3/blob/master/src/stack/btm_api.h"
    click GAP "https://github.com/jvpernis/esp32-ps3/blob/master/src/stack/gap_api.h"
    click HCI "https://github.com/jvpernis/esp32-ps3/blob/master/src/stack/hcidefs.h"
    click L2CAPI "https://github.com/jvpernis/esp32-ps3/blob/master/src/stack/l2c_api.h"
    click L2CDefs "https://github.com/jvpernis/esp32-ps3/blob/master/src/stack/l2cdefs.h"
    click Profiles "https://github.com/jvpernis/esp32-ps3/blob/master/src/stack/profiles_api.h"
    click CMK "https://github.com/jvpernis/esp32-ps3/blob/master/component.mk"
    click LibProp "https://github.com/jvpernis/esp32-ps3/blob/master/library.properties"
    click Keywords "https://github.com/jvpernis/esp32-ps3/blob/master/keywords.txt"
    click README "https://github.com/jvpernis/esp32-ps3/blob/master/README.md"
    click GitIgn "https://github.com/jvpernis/esp32-ps3/blob/master/.gitignore"

    %% Styles
    classDef user fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef core fill:#e0f0ff,stroke:#333,stroke-width:1px
    classDef abs fill:#ffffcc,stroke:#333,stroke-width:1px
    classDef stack fill:#ccf2ff,stroke:#333,stroke-width:1px
    classDef hardware fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef metadata fill:#f2f2f2,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
```
