# AiRFLOW-Smart Air Purifier

Based on ESP32-S3 intelligent air purifier firmware, it integrates 4.3 inch touch screen, multi-gas sensor, BLDC brushless motor, WiFi distribution network, MQTT(Home Assistant automatic discovery), Web console and OTA firmware upgrade.

## Project Introduction

This project is a complete embedded intelligent air purifier solution. The equipment monitors the concentration of TVOC, CO₂ and formaldehyde in real time through Y01 sensor, and detects the indoor temperature through DS18B20. The data is simultaneously displayed on the local touch screen and the Web console, and is pushed to smart home platforms such as Home Assistant through MQTT to realize linkage.

The fan drive adopts BLDC brushless motor, supports manual speed regulation and**AUTO MODE**-Any gas indicator exceeds the alarm threshold automatically turn on the fan, after reaching the standard delay to turn off. Timing switch machine function built-in Chinese legal holiday adaptation (shift compensation = working days, legal holidays = rest days).

## Feature List

### Air quality monitoring

-Y01 laser sensor: real-time reading TVOC, CO₂, formaldehyde, UART communication

DS18B20 digital temperature sensor: high precision temperature detection, 1-Wire interface-

-The sensor data is automatically recorded every 60 seconds, and the ring buffer can retain up to 720 pieces (12 hours)

-The Web console supports querying historical data and drawing time series charts.

### Touch screen interface (LVGL 9.5)

-800 × 480 horizontal screen display, left icon navigation bar resident, 5 pages one-click switch

-Home page: temperature large font + real-time value + four line charts (temperature/TVOC/CO₂/CHO) + fan speed regulation

-Network page: WiFi connection management + MQTT configuration + device QR code

-The setting page: Chinese and English switching/dark color · bright color · automatic theme/screen brightness/factory reset

-Sound page: key tone/switch tone/reminder tone, each with 6 optional melodies, support audition

-the power page: rest screen/shutdown/time switch machine (support daily/working day/weekend/custom, automatically adapt to Chinese holidays)

### WiFi Distribution Network & Web Console

-The first start-up automatic pop-up window to guide the distribution network

- Web 控制台功能：传感器面板、风扇控制、MQTT 配置、报警阈值设置、LED 调色、定时开关机、**OTA 固件升级**（网页上传 .bin, progress bar + percentage)

### MQTT & Home Assistant

-Auto Discovery: temperature, TVOC, CO₂, CH₂, fan switch/speed, timing status

-Support remote control: fan switch and speed control, screen brightness, LED color and effect, shutdown/wake

-the custom Broker address (including user name/password authentication), web side one-click test connection

### Other

-WS2812 status indicator: normal/alarm/shutdown/WiFi failure/WiFi connection in 5 states each independent RGB color and effect

-PWM audio output (PAM8302 D class amplifier), mute automatically cut off the power supply to eliminate the bottom noise

- factory reset: click the reset button 3 times in a row

-The screen brightness is adjustable, rest the screen after double-click to wake up

## Hardware

| Module | Model | Interface |

| --- | --- | --- |

| MCU | ESP32-S3(16MB Flash, N16R8, on PSPRAM) | - |

| Screen | TK043F1509(NT35 510, 800 × 480) | 8-bit 8080 Parallel |

| Touch | FT5x06 / FT6336(I2C, address 0x 38) | I2C |

| Gas Sensors | Y01 Laser Module (TVOC / CO₂ / CH₂ O) | UART, 9600bps |

| Temperature Sensors | DS18B20 | 1-Wire(GPIO8, 4.7kΩ Pull-up) |

| Motors | 48F704P840 BLDC | LEDC PWM (speed control) + PCNT (speed feedback) |

| Status Light | WS2812-2020 RGB | RMT |

| Speaker | 8Ω 2W + PAM8302 Class D | LEDC PWM(RC Low Pass) |

> **GPIO allocation details** ['Hand/board.h'] (Hand/board.h) 。

> **接线注意事项**: GPIO43/44 is occupied by the internal USB-Serial-JTAG of the ESP32-S3 and is not available; Touching I2C requires 4.7kΩ pull-up; The motor start pin needs 4.7kΩ pull-down; The motor power supply needs 470 µF/25V low ESR electrolytic capacitor decoupling.

## Software Architecture

```

main/

├── main.c entry

├── app_controller.c/h Central controller (initialization, event distribution, WiFi/MQTT/sensor/alarm/power scheduling)

├── board.h All pin definitions + NVS key name

├── event_bus.c/h Lightweight publish-subscribe event bus

├── ui/ LVGL interface layer

│ ├── ui_manager.c/h page management, navigation bar, touch processing, screen rest/shutdown/wake-up animation

│ ├── ui_theme.c/h theme engine (dark/light/automatic sunrise and sunset theme switching)

│ ├── ui_lang.c/h Multi-language Support (Chinese/English)

│ ├── ui_design.h design system (color, spacing, font, flattening assistant)

│ ├── ui_screen_home.c homepage (sensor value + line chart + fan control)

│ ├── ui_screen_network.c Network Configuration (WiFi Scan/MQTT Settings/QR Code)

│ ├── ui_screen_settings.c System Settings (Language/Theme/Brightness/Factory Reset)

│ ├── ui_screen_sound.c Sound Settings (Key/On/Off/Reminder Sound + Melody Selection)

│ ├── ui_screen_power.c power management (information screen/shutdown/time switch machine)

│ ├── ui_boot.c boot animation

│ ├── ui_provision_prompt.c distribution network guide pop-up window

│ ├── ui_apple_anim.c button elastic animation

│-font_cjk_*.c Chinese font (Siyuan bold, 4 font sizes)

│ Felt_melody.c Melody Name Prefix Special Font

├── holiday/China Holiday Query (timor.tech API)

Cloud── assets/ Logo image resources

components/

├── wifi_prov/ WiFi distribution network + HTTP server + full Web console + OTA

├── mqtt_ha/ MQTT client + Home Assistant automatic discovery

├── motor_bldc/ BLDC Brushless Motor Drive

├── sensor_y01/ Y01 Sensor UART Protocol Analysis

├── sensor_ds18b20/        DS18B20 1-Wire 驱动

├── sensor_history/sensor historical data ring buffer

├── speaker/ PWM audio output (melody synthesis + power amplifier control)

├── status_led/ WS2812 RGB LED control (RMT driver)

├── settings/ NVS non-volatile storage read/write encapsulation

├── factory_reset/fast power-on 3 times reset detection

├── touch_ft5x06/Touch I2C communication layer

C── LCD _tk043f1509/ LCD panel driver

```

## Data Flow

```

传感器(Y01/DS18B20) → app_controller → event_bus

                                      ├→ UI 更新（lv_label + chart）

                                      ├→ MQTT 发布（mqtt_ha）

                                      ├→ sensor_history 记录

On → alarm judgment → automatic fan + LED + sound

User Action (Touch Screen/Web/MQTT)→ app_controller → Execute Action + Persistence NVS

```

## Development environment

- **ESP-IDF** v6.0.1

-**LVGL** 9.5 (via`espressif/esp_lvgl_port` 组件集成）

-**Chip** ESP32-S3

-**Build System** CMake + Ninja

## Build & Burn

```bash

# Clone warehouse

git clone <repo-url>

cd airflow-esp32

# Configure the target

idf.py set-target esp32s3

# Compile

idf.py build

# Burn and view logs

idf.py -p COMx flash monitor

```

## Configuration description

-**First power-up**: The device automatically creates a hotspot'AiRFLOW', the mobile phone will pop up the distribution page after connecting

-**MQTT** :Web console "network settings" to configure the Broker address, supported format`mqtt://host:port`

- **OTA 升级**：Web 控制台 → 设置 → 固件升级 → 上传 air_purifier.bin → 自动重启

## License

WITH License

See attachment for firmware, wiring and pcb production documents