# airowl-iot/airowl architecture

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

- Interactive diagram: https://gitdiagram.com/airowl-iot/airowl
- Repository: https://github.com/airowl-iot/airowl

## Overview

##### Project type and purpose
- This is an embedded IoT product (“Airowl”) for indoor air-quality measurement.
- It combines hardware (3D-printed case, PCB, M5Stack Core S3 SE board, Sensirion SEN54 sensor), embedded firmware (built with PlatformIO/CMake), a touchscreen UI (LVGL + SquareLine), Matter protocol integration, and design/source files (PCB, 3D prints).

##### File structure
- Top‐level directories:
- Designfiles (3D case & facia)
- Mountingboard (KiCad PCB project)
- Firmware (PlatformIO project + libraries)
- squareline (UI designer assets)
- src (main firmware code + UI code)
- Firmware/lib contains sub‐libs: Arduino_GFX (display control), Matter (Matter stack), TFT_eSPI, TouchLib, lvgl (GUI), etc.
- The src folder holds main.cpp, sensor interface, LVGL setup, Matter wrapper, and UI screen modules.

##### README for insights
- The device uses ESP32-S3 (Wi-Fi + Matter).
- Displays air quality graphs for PM1, PM2.5, PM4, TVOC, etc.
- Matter compatibility enables integration with Apple HomeKit, Google Home.
- SquareLine Studio generates the lvgl UI components under src/ui.

##### Main components & interactions
a. Hardware components (physical layer)
- Sensirion SEN54 air-quality sensor (I²C)
- M5Stack Core S3 SE module (ESP32-S3 MCU, Wi-Fi/BT, AXP2101 PMIC)
- 320×240 capacitive touch LCD
- Speaker, power management
- 3D printed case & front facia
b. Firmware components (embedded software layer)
- PlatformIO/CMake build system
- Board initialization & power management (AXP2101 driver)
- Sensor driver (Sensor.h/time_func.h → read air-quality data)
- UI framework:
- lvgl core + SquareLine-generated screens
- Arduino_GFX/TFT_eSPI for low-level display bus
- TouchLib for capacitive touch input
- Matter stack:
- Matter.cpp/H wrapper → advertises device to Matter network
- Endpoint definitions for sensors/lights if any
- Application logic: data acquisition, UI update, Matter reporting
c. External services
- Matter network over Wi-Fi
- Home ecosystems: Apple HomeKit, Google Home

##### Architectural patterns & design principles
- Layered architecture:
- HAL layer (GPIO, I²C, TFT bus, touch bus)
- Middleware (Arduino_GFX, TFT_eSPI, TouchLib, lvgl, Matter)
- Application layer (main.cpp, sensor reading, UI screens, Matter wrapper)
- Separation of concerns:
- UI generation isolated under src/ui (SquareLine)
- Networking/Matter integration isolated in Matter lib
- Sensor logic in Sensor.h / time_func.h

##### Elements
- Clear labels for each component (e.g., “ESP32-S3 MCU”, “Sensirion SEN54 (I²C)”)
- Sensor → MCU → UI → display
- MCU → Matter stack → Wi-Fi → Cloud/Home
- Rounded rectangles for hardware
- Stacked blocks for firmware modules

- Attach “I²C → SEN54 sensor”
- Attach “SPI/QSPI → 320×240 LCD” and “Touch interface → touch controller”
- Speaker output, power supply chain
- HAL: I²C driver, SPI/TFT driver, touch driver, PMIC driver
- Middleware: Arduino_GFX/TFT_eSPI, TouchLib, lvgl, Matter
- Application: main.cpp, Sensor module, UI screens, Matter wrapper
d. Interactions:
- Sensor readings flow upwards into application logic
- Application pushes data to UI and to Matter reporting
- UI events (touch) flow down into lvgl middleware, then to application event handlers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        direction TB
        Net["Matter Network"]:::external
        HomeKit["Apple HomeKit"]:::external
        Google["Google Home"]:::external
        Net --> HomeKit
        Net --> Google
    end

    WiFi["Wi-Fi Antenna"]:::external
    WiFi --> Net

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Main["main.cpp"]:::app
        SensorMod["Sensor Module\n(Sensor.h / time_func.h)"]:::app
        UIInit["UI Init\n(lv_setup.cpp)"]:::app
        UICore["UI Core\n(ui.c / ui.h)"]:::app
        UIEvents["UI Events\n(ui_events.cpp / ui_events.h)"]:::app
        UIHelpers["UI Helpers\n(ui_helpers.c / ui_helpers.h)"]:::app
        Screens["LVGL Screens\n(ui_PM1graph.c, ui_PM25graph.c, ui_PM4graph.c,\nui_PM10graph.c, ui_TVOCgraph.c, ui_dashboard.c, ui_Intro.c,\nui_owl.c, ui_qrcode.c)"]:::app
        MatterWrap["Matter Wrapper\n(matter_wrapper.cpp / matter_wrapper.h)"]:::app
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        direction TB
        AGFX["Arduino_GFX"]:::mid
        TFT["TFT_eSPI"]:::mid
        TL["TouchLib"]:::mid
        LVGLLib["lvgl"]:::mid
        MatterLib["Matter Library"]:::mid
    end

    %% HAL Layer
    subgraph "HAL Layer"
        direction TB
        I2C["I²C Driver"]:::hal
        SPI["SPI/TFT Driver"]:::hal
        TouchDrv["Touch Driver"]:::hal
        PMIC["PMIC Driver\n(AXP2101)"]:::hal
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        Board["M5Stack Core S3 SE\n(ESP32-S3 + AXP2101)"]:::hw
        SensorHW["Sensirion SEN54\n(I²C)"]:::hw
        Display["320×240 LCD\n(SPI)"]:::hw
        TouchHW["Touch Controller"]:::hw
        Speaker["Speaker"]:::hw
        Power["Power Management"]:::hw
    end

    %% Build & Design Files
    subgraph "Project Files"
        direction TB
        Case3D["3D-Printed Case\nDesignfiles/Backcover"]:::external
        Facia["Front Facia\nDesignfiles/Frontfacia"]:::external
        PCB["PCB KiCad Project\nMountingboard/AirOwl_v1/AirOwl_v1.kicad_pcb"]:::external
        PlatformIO["PlatformIO Build Config\nFirmware/platformio.ini"]:::external
        BoardsDef["Board Definitions\nFirmware/boards/m5stack-coreS3-mah.json"]:::external
        Config["Global Config\nFirmware/include/config.h"]:::external
        Secrets["Secrets\nFirmware/include/secrets.h"]:::external
        SquareLine["SquareLine UI Assets\nFirmware/squareline/projects/ui_square_line"]:::external
    end

    %% Connections
    SensorHW -->|I²C| Board
    Display -->|SPI| Board
    TouchHW -->|Touch Interface| Board
    Speaker -->|Audio Out| Board
    Power -->|Power| Board

    Board --> I2C
    Board --> SPI
    Board --> TouchDrv
    Board --> PMIC
    Board --> WiFi

    I2C --> AGFX
    SPI --> TFT
    TouchDrv --> TL
    I2C --> LVGLLib
    PMIC --> Main

    AGFX --> UIInit
    TFT --> UICore
    TL --> UIEvents
    LVGLLib --> Screens
    MatterLib --> MatterWrap

    Main --> SensorMod
    Main --> UIInit
    Main --> MatterWrap
    SensorMod -->|reads| SensorHW
    UIInit --> UICore
    UICore --> UIEvents
    UIEvents --> UIHelpers
    UIHelpers --> Screens
    Screens --> Display
    MatterWrap --> WiFi

    %% Build & Generation
    PlatformIO -->|builds| Board
    BoardsDef --> PlatformIO
    Config --> Main
    Secrets --> Main
    SquareLine --> UICore
    SquareLine --> Screens

    %% Click Events
    click Case3D "https://github.com/airowl-iot/airowl/tree/main/Designfiles/Backcover"
    click Facia "https://github.com/airowl-iot/airowl/tree/main/Designfiles/Frontfacia"
    click PCB "https://github.com/airowl-iot/airowl/blob/main/Mountingboard/AirOwl_v1/AirOwl_v1.kicad_pcb"
    click PlatformIO "https://github.com/airowl-iot/airowl/blob/main/Firmware/platformio.ini"
    click BoardsDef "https://github.com/airowl-iot/airowl/blob/main/Firmware/boards/m5stack-coreS3-mah.json"
    click Config "https://github.com/airowl-iot/airowl/blob/main/Firmware/include/config.h"
    click Secrets "https://github.com/airowl-iot/airowl/blob/main/Firmware/include/secrets.h"
    click SensorMod "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/Sensor.h"
    click SensorMod "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/time_func.h"
    click Main "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/main.cpp"
    click UIInit "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/lv_setup.cpp"
    click UICore "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/ui.c"
    click UICore "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/ui.h"
    click UIEvents "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/ui_events.cpp"
    click UIEvents "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/ui_events.h"
    click UIHelpers "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/ui_helpers.c"
    click UIHelpers "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/ui_helpers.h"
    click MatterWrap "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/matter_wrapper.cpp"
    click MatterWrap "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/matter_wrapper.h"
    click SquareLine "https://github.com/airowl-iot/airowl/tree/main/Firmware/squareline/projects/ui_square_line"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_PM1graph.c"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_PM25graph.c"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_PM4graph.c"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_PM10graph.c"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_TVOCgraph.c"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_dashboard.c"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_Intro.c"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_owl.c"
    click Screens "https://github.com/airowl-iot/airowl/blob/main/Firmware/src/ui/screens/ui_qrcode.c"
    click AGFX "https://github.com/airowl-iot/airowl/tree/main/Firmware/lib/Arduino_GFX"
    click TFT "https://github.com/airowl-iot/airowl/tree/main/Firmware/lib/TFT_eSPI"
    click TL "https://github.com/airowl-iot/airowl/tree/main/Firmware/lib/TouchLib"
    click LVGLLib "https://github.com/airowl-iot/airowl/tree/main/Firmware/lib/lvgl"
    click MatterLib "https://github.com/airowl-iot/airowl/blob/main/Firmware/lib/Matter/src/Matter.cpp"
    click MatterLib "https://github.com/airowl-iot/airowl/blob/main/Firmware/lib/Matter/src/Matter.h"
    click MatterLib "https://github.com/airowl-iot/airowl/blob/main/Firmware/lib/Matter/src/MatterEndpoints/MatterAirQualitySensor.cpp"

    %% Styles
    classDef hw fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef hal fill:#98FB98,stroke:#000
    classDef mid fill:#90EE90,stroke:#000
    classDef app fill:#32CD32,stroke:#000
    classDef external fill:#FFA500,stroke:#000
```
