# youheng7185/esp32-ble-at architecture

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

- Interactive diagram: https://gitdiagram.com/youheng7185/esp32-ble-at
- Repository: https://github.com/youheng7185/esp32-ble-at

## Overview

##### Project type and purpose
- This is an embedded-firmware project targeting Espressif SoCs (ESP32, ESP32-S3, etc.) using the ESP-IDF framework.
- It produces a bootloader and application image, runs FreeRTOS, and interfaces with peripherals via IDF drivers (UART, Wi-Fi, etc.).

##### File structure
- Top-level CMakeLists.txt and build/ folders: define project build with CMake + Ninja.
- main/: contains application code (main.c, at_commands.c/h).
- build/bootloader-prefix, build/app-flash_args, partition_table-flash_args, flash_args: build artifacts and tooling.
- esp-idf/: vendored components (FreeRTOS, drivers, network stacks, HALs, mbedTLS, etc.).

##### Key components
a. Host Development Environment
- IDE (VSCode/.devcontainer) & idf.py/CMake/Ninja build system
- Toolchain (xtensa-gcc or riscv-gcc)
- esptool (serial flasher)
b. Build Artifacts
- Bootloader image
- Partition table
- Application ELF/.bin
c. Target Device
- Flash memory (stores bootloader, partitions, app)
- SoC block:
- CPU core (Xtensa/RISC-V)
- ROM, RAM
- Peripherals (UART, SPI, I²C, ADC, Wi-Fi/BLE MAC+PHY)
- IDF components executed as libraries (esp_system, freertos, drivers, lwIP, mbedTLS, etc.)
- Application task(s) (main, at_commands) running under FreeRTOS

##### Relationships and data flows
- Developer → IDE/CMake → generates build graph → Ninja invokes toolchain → produces images
- esptool over UART/USB → flashes images into MCU flash
- On reset: Boot ROM → Bootloader → reads partition table → loads App → starts FreeRTOS scheduler → application tasks
- Application uses IDF driver APIs to interact with hardware/peripherals

##### Architectural patterns and design principles
- Layered architecture:
- Hardware abstraction (HAL)
- Core services (esp_system, FreeRTOS)
- Middleware (netif, mbedTLS, lwIP, MQTT, protocomm)
- Application layer (main, at_commands)
- Modularity: IDF components are separate CMake targets/libraries

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Development Environment
    subgraph "Host Development Environment"
        direction TB
        IDE["IDE & Container"]:::build
        CMakeNinja["CMake + Ninja"]:::build
        Toolchain["xtensa-gcc/riscv-gcc"]:::build
        FlashArgs["Flash Args"]:::build
        SDKConfig["SDK Config Files"]:::build
        esptool["esptool (Serial Flasher)"]:::build
    end

    %% Build Artifacts
    subgraph "Build Artifacts"
        direction TB
        BootloaderBin["Bootloader Image\n(bootloader.bin/.elf)"]:::firmware
        PartitionTableBin["Partition Table\n(partition-table.bin)"]:::firmware
        AppBin["Application Image\n(.bin/.elf)"]:::firmware
    end

    %% Target Device
    subgraph "Target Device"
        direction TB
        FlashMem["Flash Memory"]:::hw
        BootROM["Boot ROM"]:::hw
        Bootloader["Bootloader"]:::firmware
        PartitionTable["Partition Table"]:::firmware
        AppImage["Application"]:::firmware

        subgraph "Runtime"
            direction TB
            FreeRTOS["FreeRTOS Kernel"]:::idf
            AppTasks["App Tasks\n(main, at_commands)"]:::firmware
            subgraph "IDF Components"
                direction TB
                HAL["HAL"]:::idf
                SystemLib["esp_system"]:::idf
                Drivers["Peripheral Drivers"]:::idf
                subgraph "Middleware & Network"
                    direction TB
                    lwIP["lwIP"]:::idf
                    netif["esp_netif"]:::idf
                    mbedTLS["mbedTLS"]:::idf
                end
            end
            Peripherals["Hardware Peripherals\n(UART, SPI, I²C, Wi-Fi)"]:::hw
        end
    end

    %% Build Flow
    IDE -->|defines build| CMakeNinja
    SDKConfig -->|used by| CMakeNinja
    CMakeNinja -->|invokes| Toolchain
    Toolchain -->|produces| BootloaderBin
    Toolchain -->|produces| PartitionTableBin
    Toolchain -->|produces| AppBin
    FlashArgs -->|configures flash| esptool
    CMakeNinja -->|generates build.ninja| FlashArgs

    %% Flash Flow
    esptool -->|flashes binaries| FlashMem

    %% Boot Flow
    FlashMem --> BootROM --> Bootloader --> PartitionTable --> AppImage --> FreeRTOS
    AppImage --> AppTasks

    %% Runtime Calls
    AppTasks -->|calls API| Drivers
    Drivers --> Peripherals
    AppTasks -->|uses RTOS| FreeRTOS
    FreeRTOS -->|schedules| AppTasks
    AppTasks -->|calls| mbedTLS
    AppTasks -->|network via| lwIP
    lwIP --> netif

    %% Dependencies
    AppTasks --> HAL
    HAL --> Peripherals
    AppTasks --> SystemLib

    %% Click Events
    click IDE "https://github.com/youheng7185/esp32-ble-at/tree/main/.devcontainer/Dockerfile"
    click IDE "https://github.com/youheng7185/esp32-ble-at/blob/main/.devcontainer/devcontainer.json"
    click CMakeNinja "https://github.com/youheng7185/esp32-ble-at/blob/main/CMakeLists.txt"
    click CMakeNinja "https://github.com/youheng7185/esp32-ble-at/blob/main/build.ninja"
    click esptool "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/esptool_py/"
    click Toolchain "https://github.com/youheng7185/esp32-ble-at/tree/main/CMakeFiles/"
    click Bootloader "https://github.com/youheng7185/esp32-ble-at/tree/main/bootloader-prefix/src/"
    click Bootloader "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/bootloader_support/"
    click BootloaderBin "https://github.com/youheng7185/esp32-ble-at/blob/main/build/bootloader/bootloader.bin"
    click BootloaderBin "https://github.com/youheng7185/esp32-ble-at/blob/main/build/bootloader/bootloader.elf"
    click PartitionTableBin "https://github.com/youheng7185/esp32-ble-at/blob/main/build/partition_table/partition-table.bin"
    click PartitionTableBin "https://github.com/youheng7185/esp32-ble-at/tree/main/partition-table-flash_args"
    click AppTasks "https://github.com/youheng7185/esp32-ble-at/blob/main/main/main.c"
    click AppTasks "https://github.com/youheng7185/esp32-ble-at/blob/main/main/at_commands.c"
    click AppTasks "https://github.com/youheng7185/esp32-ble-at/blob/main/main/at_commands.h"
    click AppBin "https://github.com/youheng7185/esp32-ble-at/blob/main/build/gap-discover.bin"
    click AppBin "https://github.com/youheng7185/esp32-ble-at/blob/main/build/gap-discover.elf"
    click FreeRTOS "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/freertos/"
    click FreeRTOS "https://github.com/youheng7185/esp32-ble-at/tree/main/build/esp-idf/freertos/"
    click HAL "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/hal/"
    click HAL "https://github.com/youheng7185/esp32-ble-at/tree/main/build/esp-idf/hal/"
    click SystemLib "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/esp_system/"
    click SystemLib "https://github.com/youheng7185/esp32-ble-at/tree/main/build/esp-idf/esp_system/"
    click Drivers "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/driver/"
    click Drivers "https://github.com/youheng7185/esp32-ble-at/tree/main/build/esp-idf/driver/"
    click lwIP "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/lwip/"
    click lwIP "https://github.com/youheng7185/esp32-ble-at/tree/main/build/esp-idf/lwip/"
    click netif "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/esp_netif/"
    click netif "https://github.com/youheng7185/esp32-ble-at/tree/main/build/esp-idf/esp_netif/"
    click mbedTLS "https://github.com/youheng7185/esp32-ble-at/tree/main/esp-idf/mbedtls/"
    click mbedTLS "https://github.com/youheng7185/esp32-ble-at/tree/main/build/esp-idf/mbedtls/"
    click FlashArgs "https://github.com/youheng7185/esp32-ble-at/tree/main/flash_args"
    click FlashArgs "https://github.com/youheng7185/esp32-ble-at/tree/main/app-flash_args"
    click FlashArgs "https://github.com/youheng7185/esp32-ble-at/tree/main/bootloader-flash_args"
    click SDKConfig "https://github.com/youheng7185/esp32-ble-at/tree/main/sdkconfig"
    click SDKConfig "https://github.com/youheng7185/esp32-ble-at/blob/main/sdkconfig.default"

    %% Styles
    classDef build fill:#D0E6FF,stroke:#000,stroke-width:1px
    classDef firmware fill:#D0FFD6,stroke:#000,stroke-width:1px
    classDef idf fill:#FFF1B8,stroke:#000,stroke-width:1px
    classDef hw fill:#E0E0E0,stroke:#000,stroke-width:1px
```
