# jasoni111/pong architecture

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

- Interactive diagram: https://gitdiagram.com/jasoni111/pong
- Repository: https://github.com/jasoni111/pong

## Overview

##### Project Type and Purpose
- This is an embedded firmware project (no separate frontend/backend).
- Purpose: Run a two-player Pong game on Smart Car boards, synchronizing over Bluetooth.

##### File Structure
- Top-level build scripts:
- Makefile, MakeConfig.inc – orchestrate compilation & linking.
- build/*.ld – linker scripts for various MCUs (d10, f15, z4).
- inc/ – hardware abstraction & game module headers:
- config.h – board-specific pin/timer configs.
- comm.h – abstract Comm interface.
- bluetooth.h – concrete Bluetooth implementation of Comm.
- sprite.h – abstract rendering API for on-screen objects.
- ball.h, platform.h – game object classes.
- src/main.cpp – game loop, instantiates objects, handles game logic & event dispatch.

##### README Insights
- Uses libbase & libsc (board support libraries) to access timers, display, Bluetooth (JyMcuBt106).
- Communication protocol must be implemented in Bluetooth::SendBuffer and EnableTimer.
- Game objects (Ball, Platform) inherit from Sprite and use Comm to sync state.

##### Main Components
a. Hardware Layer
- MCU Core (Cortex-M or equivalent)
- Bluetooth Radio (JyMcuBt106 module)
- / Graphics Driver (LCD/TFT)
- Timers / PIT for periodic interrupts
- Input controls (buttons/joystick)
b. Software Layer
- HAL / Board Support (libbase/libsc)
- Comm Interface (abstract class)
- Bluetooth Module (Comm implementation)
- Sprite Framework (abstract rendering API)
- Game Objects: Ball, Platform
- Main Game Controller (in main.cpp)
- Build System (Makefile + Linker Scripts)

##### Relationships & Interactions
- Main Game Controller
→ Instantiates Ball & Platform
→ Reads Input → libsc GPIO APIs
→ Uses Comm.send()/recv() → Bluetooth Module
- Bluetooth Module
→ Uses PIT timer interrupts → sends/receives packets via UART to radio
- Sprite Framework
- Game Objects
→ Extend Sprite; maintain position/state
- Build System
→ Compiles src + libbase/libsc → final firmware → target MCU via linker scripts

##### Architectural Patterns & Principles
- Layered Architecture:
Hardware Abstraction → Comm/Sprite Interfaces → Game Logic
- Dependency Inversion: high-level game logic depends on abstract Comm & Sprite, not concrete Bluetooth or display code.
- Event-driven via interrupts/timers for synchronization and refresh.

##### Putting It All Together
Hardware on the far left → HAL → Interfaces → Game Logic → back to Hardware.
- Or stack layers vertically.
- Notes for key protocols (e.g., “Bluetooth UART @ 9600 bps, custom packet format”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        MCU["MCU Core"]:::hardware
        Radio["Bluetooth Radio\n(JyMcuBt106)"]:::hardware
        Display["Display / Graphics Driver"]:::hardware
        Timer["Timers / PIT"]:::hardware
        Input["Input Controls"]:::hardware
    end

    %% HAL / Board Support
    subgraph "HAL / Board Support"
        HAL["libbase / libsc"]:::hal
        Config["config.h"]:::hal
    end

    %% Interfaces
    subgraph "Interfaces"
        CommI["Comm Interface\n(inc/comm.h)"]:::interface
        SpriteI["Sprite Framework\n(inc/sprite.h)"]:::interface
    end

    %% Middleware
    subgraph "Middleware"
        Bluetooth["Bluetooth Module\n(inc/bluetooth.h)"]:::interface
    end

    %% Application Logic
    subgraph "Application Logic"
        Ball["Ball\n(inc/ball.h)"]:::app
        Platform["Platform\n(inc/platform.h)"]:::app
        Main["Main Game Controller\n(src/main.cpp)"]:::app
    end

    %% Build System
    subgraph "Build System"
        Makefile["Makefile"]:::build
        ConfigInc["MakeConfig.inc"]:::build
        subgraph "Linker Scripts"
            LD1["d10.ld"]:::build
            LD2["f15.ld"]:::build
            LD3["z4.ld"]:::build
        end
    end

    %% Connections
    Main --> Ball
    Main --> Platform
    Main -->|"draw()"| SpriteI
    SpriteI -->|"low-level draw"| Display
    Main -->|"send()/recv()"| CommI
    CommI <--> Bluetooth
    Bluetooth -->|"UART packets"| Radio
    Bluetooth -->|"timer IRQ"| Timer
    Main -->|"read input"| Input
    Main -->|"GPIO APIs"| HAL
    HAL --> Timer
    HAL --> Display
    HAL --> Radio
    HAL --> Input
    Makefile --> Main
    ConfigInc --> Makefile
    LD1 --> Makefile
    LD2 --> Makefile
    LD3 --> Makefile

    %% Click Events
    click Makefile "https://github.com/jasoni111/pong/tree/master/Makefile"
    click ConfigInc "https://github.com/jasoni111/pong/blob/master/MakeConfig.inc"
    click LD1 "https://github.com/jasoni111/pong/blob/master/build/d10.ld"
    click LD2 "https://github.com/jasoni111/pong/blob/master/build/f15.ld"
    click LD3 "https://github.com/jasoni111/pong/blob/master/build/z4.ld"
    click Config "https://github.com/jasoni111/pong/blob/master/inc/config.h"
    click CommI "https://github.com/jasoni111/pong/blob/master/inc/comm.h"
    click Bluetooth "https://github.com/jasoni111/pong/blob/master/inc/bluetooth.h"
    click SpriteI "https://github.com/jasoni111/pong/blob/master/inc/sprite.h"
    click Ball "https://github.com/jasoni111/pong/blob/master/inc/ball.h"
    click Platform "https://github.com/jasoni111/pong/blob/master/inc/platform.h"
    click Main "https://github.com/jasoni111/pong/blob/master/src/main.cpp"

    %% Styles
    classDef hardware fill:#D3D3D3,stroke:#000
    classDef hal fill:#AEDFF7,stroke:#000
    classDef interface fill:#C8E6C9,stroke:#000
    classDef app fill:#FFCC80,stroke:#000
    classDef build fill:#E1BEE7,stroke:#000
```
