# air-sense/airsense_esp32-idf_rtos architecture

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

- Interactive diagram: https://gitdiagram.com/air-sense/airsense_esp32-idf_rtos
- Repository: https://github.com/air-sense/airsense_esp32-idf_rtos

## Overview

##### Project Type and Purpose
- This is an embedded IoT firmware project built on Espressif’s ESP‑IDF framework for the ESP32.
- It gathers environmental and time data (from BME280/BMP280, PMS7003, DS3231), timestamps it, stores it on an SD card, and publishes it (e.g., via MQTT).

##### File‐Structure Analysis
- Top‐Level:
- CMakeLists.txt, Makefile, sdkconfig – build and config for ESP‑IDF
- component/ – all reusable modules (drivers, managers, helpers)
- main/ – application entry point (main.c)
- component/:
- Sensor drivers: BME280, BMP280, PMS7003 (each has .c/.h, CMakeLists.txt, component.mk, Kconfig)
- DS3231 + Time: Real Time Clock driver + wrapper for timestamp handling
- FileManager: SD‑card abstraction
- DataManager: aggregation and orchestration of sensor data
- DeviceManager: high‑level device control (init/sequencing)
- SNTP_Sync: external time synchronization over Wi‑Fi
- i2cdev, esp_idf_lib_helpers: low‑level I²C helper libraries
- main/:
- main.c: creates FreeRTOS tasks or timers, initializes components via DeviceManager

##### Extracted Architectural Insights from README
- Uses ESP‑IDF v5.1.2 with FreeRTOS
- Key features: sensor read, SD storage, MQTT publish
- Modular “component” layout follows ESP‑IDF component paradigm
- Kconfig.projbuild files allow per‑component configuration via menuconfig

a. Main Components
- Hardware layer: ESP32 SoC, I²C bus, UART (for PMS7003), SD‑card interface, Wi‑Fi radio
- ESP‑IDF framework (FreeRTOS scheduler, Wi‑Fi, peripheral drivers)
- Helper libraries: i2cdev, esp_idf_lib_helpers
- Sensor drivers: BME280, BMP280, PMS7003, DS3231
- Time services: DS3231Time + SNTP_Sync
- Managers: DeviceManager, DataManager, FileManager
- Application layer: main.c (task orchestration)
- External services: MQTT broker (cloud), NTP server (internet)
b. Relationships & Data Flows
1. At boot: main.c → DeviceManager initializes sensors + network → RTOS tasks start
2. Sensor tasks: use i2cdev/driver → read BME280/BMP280/PMS7003 periodically
3. Time sync: DS3231Time task reads RTC; SNTP_Sync updates RTC via Wi‑Fi
4. DataManager aggregates sensor+timestamp → passes payload to:
– FileManager (writes to SD‑card)
– MQTT publish function (via ESP‑IDF MQTT client API)
c. Architectural Patterns & Principles
– Layered: Hardware → Driver libraries → Component drivers → Manager services → Application
– Component‑based (ESP‑IDF recommended layout)
– Separation of concerns: I/O, storage, networking, orchestration each in its own component
– FreeRTOS tasks encapsulate periodic or event‑driven behavior
d. Key Technologies
– ESP‑IDF (FreeRTOS, Wi‑Fi, peripheral APIs)
– I²C via i2cdev
– SD‑card via FATFS (FileManager)
– MQTT client (inside DeviceManager or DataManager)
– SNTP (built‑in LWIP SNTP in ESP‑IDF)
– Kconfig for runtime configuration

##### Essential Details not to Miss
- The dual time‐source (DS3231 RTC vs. SNTP) and how they synchronize
- The use of Kconfig for dynamic pin/parameter reconfiguration
- FreeRTOS tasks as fundamental runtime units
- The component.mk/CMakeLists.txt build separation
- The flow from on‑device storage to cloud publishing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Peripherals"
        style Hardware fill:#E0F7FA,stroke:#006064
        ESP32["ESP32 SoC"]:::hardware
        I2C["I²C Bus"]:::hardware
        UART["UART Bus"]:::hardware
        SDIF["SD‑Card Interface"]:::hardware
        WiFiRadio["Wi‑Fi Radio"]:::hardware
    end

    %% Framework & Libraries
    subgraph "ESP‑IDF & Helper Libraries"
        style Framework fill:#E8F5E9,stroke:#1B5E20
        ESP_IDF["ESP‑IDF Framework"]:::framework
        FreeRTOS["FreeRTOS Scheduler"]:::framework
        i2cdev["i2cdev"]:::framework
        esp_helpers["esp_idf_lib_helpers"]:::framework
    end

    %% Drivers Layer
    subgraph "Sensor & Time Drivers"
        style Drivers fill:#FFF8E1,stroke:#FF6F00
        BME280["BME280 Driver"]:::drivers
        BMP280["BMP280 Driver"]:::drivers
        PMS7003["PMS7003 Driver"]:::drivers
        DS3231["DS3231 RTC Driver"]:::drivers
        DS3231Time["DS3231Time Wrapper"]:::drivers
        SNTP["SNTP_Sync Service"]:::drivers
    end

    %% Managers Layer
    subgraph "Manager Components"
        style Managers fill:#FFE0B2,stroke:#E65100
        DeviceMgr["DeviceManager"]:::managers
        DataMgr["DataManager"]:::managers
        FileMgr["FileManager"]:::managers
    end

    %% Application Layer
    subgraph "Application"
        style App fill:#E1BEE7,stroke:#4A148C
        Main["main.c (Task Orchestration)"]:::application
    end

    %% External Services
    subgraph "External Services"
        style External fill:#ECEFF1,stroke:#37474F
        MQTT["MQTT Broker (Cloud)"]:::external
        NTP["NTP Server"]:::external
    end

    %% Connections: Control & Data
    Main -->|“init sequence”| DeviceMgr
    DeviceMgr -.->|“init drivers & network”| ESP_IDF
    ESP_IDF --> FreeRTOS
    FreeRTOS -.->|“start tasks”| Main

    %% Sensor Read Flows
    I2C --> BME280
    I2C --> BMP280
    UART --> PMS7003
    DS3231 --> DS3231Time
    WiFiRadio --> SNTP
    SNTP -->|“time update”| DS3231Time
    BME280 -->|“sensor data”| DataMgr
    BMP280 -->|“sensor data”| DataMgr
    PMS7003 -->|“sensor data”| DataMgr
    DS3231Time -->|“timestamp”| DataMgr

    %% Data Aggregation & Output
    DataMgr -->|“write payload”| FileMgr
    FileMgr -->|“SD write”| SDIF
    DataMgr -->|“MQTT publish”| ESP_IDF
    ESP_IDF -->|“MQTT API”| MQTT

    %% External Time
    SNTP -->|“NTP query”| NTP

    %% Library Dependencies
    ESP_IDF --> i2cdev
    ESP_IDF --> esp_helpers
    i2cdev --> BME280
    i2cdev --> BMP280
    i2cdev --> DS3231Time

    %% Click Events
    click BME280 "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/BME280"
    click BMP280 "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/BMP280"
    click PMS7003 "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/PMS7003"
    click DS3231 "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/DS3231"
    click DS3231Time "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/Time"
    click SNTP "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/SNTP_Sync"
    click DeviceMgr "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/DeviceManager"
    click DataMgr "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/DataManager"
    click FileMgr "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/FileManager"
    click i2cdev "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/i2cdev"
    click esp_helpers "https://github.com/air-sense/airsense_esp32-idf_rtos/tree/main/component/esp_idf_lib_helpers"
    click Main "https://github.com/air-sense/airsense_esp32-idf_rtos/blob/main/main/main.c"

    %% Styles
    classDef hardware fill:#B3E5FC,stroke:#0277BD,color:#000;
    classDef framework fill:#C8E6C9,stroke:#2E7D32,color:#000;
    classDef drivers fill:#FFECB3,stroke:#FF8F00,color:#000;
    classDef managers fill:#FFE0B2,stroke:#EF6C00,color:#000;
    classDef application fill:#E1BEE7,stroke:#6A1B9A,color:#000;
    classDef external fill:#CFD8DC,stroke:#455A64,color:#000;
```
