# jef-sure/esp32-co2-station architecture

> Architecture diagram of the GitHub repository jef-sure/esp32-co2-station, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jef-sure/esp32-co2-station
- Repository: https://github.com/jef-sure/esp32-co2-station
- Video tour (about a minute): https://gitdiagram.com/jef-sure/esp32-co2-station/video

## Overview

This ESP32 firmware is a CO₂ air-quality station. Its main workflow reads SCD41 measurements, updates an animated on-device dashboard, and reports readings over MQTT; users can configure networking and measurement offsets through BLE provisioning or a local web page. The README also documents touch-based display control, Home Assistant discovery, and timezone settings. The excerpts show the sensor task, settings persistence, web handlers, MQTT behavior, and provisioning pieces, but omit parts of the main event loop, so uncertain call wiring is not shown.

Main entry points: [`main/app_settings.c`](https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_settings.c) (Settings store), [`main/main.c`](https://github.com/jef-sure/esp32-co2-station/blob/main/main/main.c) (SCD41 task), [`main/app_webserver.c`](https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_webserver.c) (Configuration server), [`main/provisioning.c`](https://github.com/jef-sure/esp32-co2-station/blob/main/main/provisioning.c) (BLE provisioning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Device measurement and display"]
  node_main["Application loop<br/>[main.c]"]
  node_sensor["SCD41 task<br/>[main.c]"]
  node_dashboard["Dashboard rendering<br/>[main.c]"]
  node_fonts["Dashboard fonts<br/>[app_fonts.c]"]
end

subgraph group_network["Network and configuration"]
  node_web["Configuration server<br/>[app_webserver.c]"]
  node_provision["BLE provisioning<br/>[provisioning.c]"]
  node_wifi{{"Wi-Fi station"}}
  node_mqtt["MQTT publisher<br/>[app_mqtt.c]"]
end

subgraph group_support["Persistent settings"]
  node_settings[("Settings store<br/>[app_settings.c]")]
  node_timezone["Timezone rules<br/>[tzones.c]"]
end

node_occupant(("Occupant"))
node_scd41{{"SCD41 sensor"}}
node_display{{"Round display"}}
node_broker{{"MQTT broker"}}

node_main -->|"starts task"| node_sensor
node_sensor -->|"reads measurements"| node_scd41
node_sensor -->|"reads offsets"| node_settings
node_main -->|"renders readings"| node_dashboard
node_dashboard -->|"uses fonts"| node_fonts
node_dashboard -->|"draws dashboard"| node_display
node_occupant -->|"touch controls"| node_main
node_web -->|"saves configuration"| node_settings
node_web -->|"applies timezone"| node_timezone
node_provision -->|"loads network name"| node_settings
node_provision -->|"starts station"| node_wifi
node_mqtt -->|"reads credentials"| node_settings
node_mqtt -->|"publishes readings"| node_broker

click node_main "https://github.com/jef-sure/esp32-co2-station/blob/main/main/main.c"
click node_sensor "https://github.com/jef-sure/esp32-co2-station/blob/main/main/main.c"
click node_dashboard "https://github.com/jef-sure/esp32-co2-station/blob/main/main/main.c"
click node_fonts "https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_fonts.c"
click node_settings "https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_settings.c"
click node_web "https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_webserver.c"
click node_provision "https://github.com/jef-sure/esp32-co2-station/blob/main/main/provisioning.c"
click node_mqtt "https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_mqtt.c"
click node_timezone "https://github.com/jef-sure/esp32-co2-station/blob/main/main/tzones.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_sensor,node_dashboard,node_fonts toneBlue
class node_web,node_provision,node_wifi,node_mqtt toneAmber
class node_settings,node_timezone toneMint
class node_occupant,node_scd41,node_display,node_broker toneIndigo
```

## Components

### Device measurement and display

- [Application loop](https://github.com/jef-sure/esp32-co2-station/blob/main/main/main.c): `main/main.c`
- [SCD41 task](https://github.com/jef-sure/esp32-co2-station/blob/main/main/main.c): `main/main.c`
- [Dashboard rendering](https://github.com/jef-sure/esp32-co2-station/blob/main/main/main.c): `main/main.c`
- [Dashboard fonts](https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_fonts.c): `main/app_fonts.c`

### Network and configuration

- [Configuration server](https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_webserver.c): `main/app_webserver.c`
- [BLE provisioning](https://github.com/jef-sure/esp32-co2-station/blob/main/main/provisioning.c): `main/provisioning.c`
- **Wi-Fi station**
- [MQTT publisher](https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_mqtt.c): `main/app_mqtt.c`

### Persistent settings

- [Settings store](https://github.com/jef-sure/esp32-co2-station/blob/main/main/app_settings.c): `main/app_settings.c`
- [Timezone rules](https://github.com/jef-sure/esp32-co2-station/blob/main/main/tzones.c): `main/tzones.c`

### Other components

- **Occupant**
- **SCD41 sensor**
- **Round display**
- **MQTT broker**

## Connections

- Application loop → SCD41 task: starts task
- SCD41 task → SCD41 sensor: reads measurements
- SCD41 task → Settings store: reads offsets
- Application loop → Dashboard rendering: renders readings
- Dashboard rendering → Dashboard fonts: uses fonts
- Dashboard rendering → Round display: draws dashboard
- Occupant → Application loop: touch controls
- Configuration server → Settings store: saves configuration
- Configuration server → Timezone rules: applies timezone
- BLE provisioning → Settings store: loads network name
- BLE provisioning → Wi-Fi station: starts station
- MQTT publisher → Settings store: reads credentials
- MQTT publisher → MQTT broker: publishes readings