# lmarzen/esp32-weather-epd architecture

> Architecture diagram of the GitHub repository lmarzen/esp32-weather-epd, 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/lmarzen/esp32-weather-epd
- Repository: https://github.com/lmarzen/esp32-weather-epd

## Overview

This repository implements an ESP32 e-paper weather station. On wake, firmware checks battery state, connects to Wi-Fi, synchronizes time, fetches weather and air-quality data, reads the indoor sensor, renders the display, then schedules deep sleep. Configuration and AQI support provide important product capabilities. The sampled source confirms the main orchestration and network helpers; renderer internals and some configurable display features are represented from the README and tree, so their internal wiring is not inferred.

Main entry points: [`platformio/src/main.cpp`](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp) (Wake cycle), [`platformio/src/client_utils.cpp`](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/client_utils.cpp) (Wi-Fi, time, API client), [`platformio/include/renderer.h`](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/renderer.h) (Weather renderer), [`platformio/include/display_utils.h`](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/display_utils.h) (Display control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Device firmware"]
  node_wake["Wake cycle<br/>[main.cpp]"]
  node_power["Power and sleep<br/>[main.cpp]"]
  node_sensor["Indoor sensor<br/>[main.cpp]"]
  node_preferences[("Persistent preferences<br/>[main.cpp]")]
end

subgraph group_network["Network and data"]
  node_network_client["Wi-Fi, time, API client<br/>[client_utils.cpp]"]
  node_response_data["Weather response models<br/>[api_response.h]"]
end

subgraph group_display["Display and AQI"]
  node_renderer["Weather renderer<br/>[renderer.h]"]
  node_display_utils["Display control<br/>[display_utils.h]"]
  node_aqi["AQI scales<br/>[aqi.c]"]
  node_assets["Fonts and icons"]
end

subgraph group_config["Configuration"]
  node_settings["Device settings<br/>[config.h]"]
end

node_weather_service["OpenWeatherMap"]
node_time_service["NTP time service"]
node_epaper["E-paper panel"]
node_owner(("Device owner"))

node_owner -->|"initiates refresh"| node_wake
node_wake -->|"checks battery; schedules sleep"| node_power
node_wake -->|"reads and updates"| node_preferences
node_wake -->|"requests Wi-Fi, time, and forecasts"| node_network_client
node_network_client -->|"sends API requests"| node_weather_service
node_network_client -->|"synchronizes time"| node_time_service
node_network_client -->|"parses responses"| node_response_data
node_wake -->|"reads indoor conditions"| node_sensor
node_wake -->|"supplies weather and sensor data"| node_renderer
node_renderer -->|"draws display pages"| node_display_utils
node_display_utils -->|"updates panel"| node_epaper
node_renderer -->|"uses visual assets"| node_assets
node_wake -->|"uses configured options"| node_settings
node_aqi -.->|"provides AQI scales"| node_renderer

click node_wake "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp"
click node_power "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp"
click node_sensor "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp"
click node_preferences "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp"
click node_network_client "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/client_utils.cpp"
click node_response_data "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/api_response.h"
click node_renderer "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/renderer.h"
click node_display_utils "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/display_utils.h"
click node_aqi "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/lib/pollutant-concentration-to-aqi/aqi.c"
click node_assets "https://github.com/lmarzen/esp32-weather-epd/tree/main/platformio/lib/esp32-weather-epd-assets"
click node_settings "https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/config.h"

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_wake,node_power,node_sensor,node_preferences toneBlue
class node_network_client,node_response_data toneAmber
class node_renderer,node_display_utils,node_aqi,node_assets toneMint
class node_settings toneRose
class node_weather_service,node_time_service,node_epaper,node_owner toneIndigo
```

## Components

### Device firmware

- [Wake cycle](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp): `platformio/src/main.cpp`
- [Power and sleep](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp): `platformio/src/main.cpp`
- [Indoor sensor](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp): `platformio/src/main.cpp`
- [Persistent preferences](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/main.cpp): `platformio/src/main.cpp`

### Network and data

- [Wi-Fi, time, API client](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/src/client_utils.cpp): `platformio/src/client_utils.cpp`
- [Weather response models](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/api_response.h): `platformio/include/api_response.h`

### Display and AQI

- [Weather renderer](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/renderer.h): `platformio/include/renderer.h`
- [Display control](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/display_utils.h): `platformio/include/display_utils.h`
- [AQI scales](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/lib/pollutant-concentration-to-aqi/aqi.c): `platformio/lib/pollutant-concentration-to-aqi/aqi.c`
- [Fonts and icons](https://github.com/lmarzen/esp32-weather-epd/tree/main/platformio/lib/esp32-weather-epd-assets): `platformio/lib/esp32-weather-epd-assets`

### Configuration

- [Device settings](https://github.com/lmarzen/esp32-weather-epd/blob/main/platformio/include/config.h): `platformio/include/config.h`

### Other components

- **OpenWeatherMap**
- **NTP time service**
- **E-paper panel**
- **Device owner**

## Connections

- Device owner → Wake cycle: initiates refresh
- Wake cycle → Power and sleep: checks battery; schedules sleep
- Wake cycle → Persistent preferences: reads and updates
- Wake cycle → Wi-Fi, time, API client: requests Wi-Fi, time, and forecasts
- Wi-Fi, time, API client → OpenWeatherMap: sends API requests
- Wi-Fi, time, API client → NTP time service: synchronizes time
- Wi-Fi, time, API client → Weather response models: parses responses
- Wake cycle → Indoor sensor: reads indoor conditions
- Wake cycle → Weather renderer: supplies weather and sensor data
- Weather renderer → Display control: draws display pages
- Display control → E-paper panel: updates panel
- Weather renderer → Fonts and icons: uses visual assets
- Wake cycle → Device settings: uses configured options
- AQI scales → Weather renderer: provides AQI scales