# zhangkeliang0627/easygps architecture

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

- Interactive diagram: https://gitdiagram.com/zhangkeliang0627/easygps
- Repository: https://github.com/zhangkeliang0627/easygps

## Overview

This project is an embedded firmware application for an ESP32S3‐based GPS tracking and smart assistant device. It integrates a wide range of hardware and software components including GPS, BLE, compass, IMU, display elements (with LVGL), SD card resources, and various peripheral drivers. The project structure is split into hardware design (PCB Gerber files and hardware README), firmware (source code, libraries, app modules, and hardware abstraction “ChappieCore”), and additional models and resource files for 3D printing and assets.

##### Main System Components
- Hardware Board – Represent the physical ESP32S3-based device (including onboard modules such as the GPS receiver, compass sensor [QMC5883L], IMU, BLE, SD card interface, potential display, etc.) as a central hardware component.
- Firmware – Divide this into at least two major layers:
– ChappieCore (hardware drivers and peripheral abstraction): This module contains drivers for BLE, buttons, buzzer, GPS, IMU, LVGL (GUI), etc.
– Application Layer (“App”): This includes high-level application logic such as page management, data processing, configuration, resource management, and UI pages (e.g., Compass, BLEKeyboard, Settings, SmartAssistant, LiveMap, etc.).
- External Libraries – Include key external libraries such as:
– ESP32-BLE-Combo (Bluetooth functionality)
– FastLED (LED control)
– NimBLE-Arduino (enhanced BLE support)
– TinyGPSPlus (GPS parsing)
– QMC5883LCompass (compass sensor interface)
- Resource and Data Files – The TF card structure (fonts, maps, system configuration JSON files) and the static assets that support the GUI and other functionalities.

##### Component Relationships and Data Flows
– Sensors (GPS, compass, IMU, buttons) send data to ChappieCore drivers.
– ChappieCore processes raw sensor data and provides an interface to the App layer.
– The application layer uses data from ChappieCore, performs higher-level data processing (for instance, data for BLE, map display, clock, and other UI pages), and then communicates to the LVGL-based GUI.
– Outbound communications (e.g., BLE/WiFi) interface with external mobile or web applications.
– The SD card (TF card) resources feed into the application (font, image, resource configuration retrieval, and backup).

##### Architectural Patterns and Design Principles
- Separation of Concerns – Note how the firmware is modularized: low-level hardware abstraction (in ChappieCore) is separate from high-level application logic (under App).
- Reuse of Open-Source Modules – The project builds on existing frameworks (X-TRACK, Chappie-Core) and integrates standard libraries for BLE, FastLED, GPS, etc.
- Resource and UI Management – There is a dedicated resource management module and UI page management in the App layer which clearly separates presentation from underlying hardware operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        HW["Hardware Board"]:::hardware
    end

    %% Firmware Layer
    subgraph "Firmware Layer"
        subgraph "ChappieCore"
            CC["ChappieCore (Drivers & Abstraction)"]:::firmware
        end
        subgraph "Application Layer"
            APP["App (High-level Logic & UI Pages)"]:::firmware
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        BLECombo["ESP32-BLE-Combo"]:::external
        FastLED["FastLED"]:::external
        NimBLE["NimBLE-Arduino"]:::external
        TinyGPS["TinyGPSPlus"]:::external
        QMC5883L["QMC5883LCompass"]:::external
    end

    %% Resources & Assets
    subgraph "Resources & Assets"
        TF["TF Card (Fonts, Maps, Configs)"]:::resource
        Models["3D Models & Assets"]:::resource
    end

    %% Connections
    HW -->|"sends_sensor_data"| CC
    CC -->|"provides_data"| APP
    CC -->|"uses"| BLECombo
    CC -->|"uses"| NimBLE
    CC -->|"uses"| TinyGPS
    CC -->|"uses"| QMC5883L
    CC -->|"uses"| FastLED
    TF -->|"resources_loaded"| APP
    Models -->|"UI_assets"| APP

    %% Click Events
    click HW "https://github.com/zhangkeliang0627/easygps/blob/main/1.Hardware"
    click CC "https://github.com/zhangkeliang0627/easygps/tree/main/2.Firmware/src/ChappieCore"
    click APP "https://github.com/zhangkeliang0627/easygps/tree/main/2.Firmware/src/App"
    click BLECombo "https://github.com/zhangkeliang0627/easygps/tree/main/2.Firmware/lib/ESP32-BLE-Combo"
    click FastLED "https://github.com/zhangkeliang0627/easygps/tree/main/2.Firmware/lib/FastLED"
    click NimBLE "https://github.com/zhangkeliang0627/easygps/tree/main/2.Firmware/lib/NimBLE-Arduino"
    click TinyGPS "https://github.com/zhangkeliang0627/easygps/tree/main/2.Firmware/lib/TinyGPSPlus"
    click QMC5883L "https://github.com/zhangkeliang0627/easygps/tree/main/2.Firmware/lib/QMC5883LCompass"
    click TF "https://github.com/zhangkeliang0627/easygps/tree/main/5.Resource/MicroSDcard"
    click Models "https://github.com/zhangkeliang0627/easygps/blob/main/3.Models"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef firmware fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef resource fill:#FFFFE0,stroke:#000,stroke-width:2px;
```
