Support this project: back the crowdfunding to get detailed build instructions, 3D-printable enclosure models, and wiring guides at: https://makerworld.com/en/crowdfunding/159-project-aura-make-the-invisible-visible

Project Aura is an open-source ESP32-S3 air-quality station built for makers who want a polished, reliable device rather than a bare sensor board. It combines a touch-friendly LVGL UI, a local web setup portal, and MQTT with Home Assistant discovery.

This repository contains the firmware source code and configuration needed to flash and customize the device.

Join the community: GitHub Discussions

• Video Demo
• Highlights
• Gallery
• UI Screens
• Web Dashboard
• Network Requirements
• Hardware and BOM
• Assembly and Wiring Notice
• Pin Configuration
• UI Languages
• Firmware Architecture
• Build and Flash
• Configuration
• MQTT + Home Assistant
• Contributing
• AI Assistance
• License and Commercial Use
• Tests
• Repo Layout

Click the image.

• Professional telemetry: PM0.5/PM1/PM2.5/PM4/PM10, CO, CO2, VOC, NOx, temperature, humidity, absolute humidity (AH), pressure, HCHO.
• No soldering required: designed for easy assembly using Grove/QT connectors.
• Smooth LVGL UI with night mode, custom themes, and status indicators.
• Integrated web dashboard at /dashboard with live state, charts, events, settings sync, DAC page, and OTA firmware update.
• Easy setup: Wi-Fi AP onboarding + mDNS access (http://.local).
• Home Assistant ready: automatic MQTT discovery and ready-to-use dashboard code.
• Optional DAC control (GP8403, 0-10V): manual levels/timer plus automatic demand mode from air-quality thresholds.
• Robust Safe Boot: automatic rollback to the last-known-good config after crashes.

Project Aura serves two web experiences from the device:

• Setup portal (AP mode): opening / in AP mode shows the captive Wi-Fi setup flow (/wifi).
• Full dashboard (/dashboard): tabs for Sensors, Charts, Events, Settings, and System.
• Dedicated DAC page (/dac): live status, manual controls, auto mode, and auto-threshold config.
• OTA from dashboard: upload firmware .bin directly via the web UI.
• Dashboard assets are served locally in both AP and STA modes (no CDN dependency).

Useful API routes used by the dashboard:

• GET /api/state
• GET /api/charts?group=core|gases|pm&window=1h|3h|24h
• GET /api/events
• GET /api/diag (AP setup mode only)
• POST /api/settings
• POST /api/ota

• AP setup mode (http://192.168.4.1) is local-only and works without internet.
• STA mode dashboard (http://.local/dashboard or http:///dashboard) requires the client and Aura to be in the same L2/L3 network path.
• If mDNS (.local) is blocked on your network, use direct IP from the device screen or router DHCP table.
• Avoid guest networks, client isolation, or VLAN rules that block peer-to-peer LAN traffic.
• Required local traffic:
  • HTTP: TCP 80 to Aura
  • mDNS: UDP 5353 multicast (only for .local hostname discovery)
• During OTA, keep one active client tab/session to reduce transfer failures.

Quick diagnostics for support:

• GET /api/state should return live JSON with network.mode, network.ip, and sensor payload.
• GET /api/diag (available in AP setup mode) shows Wi-Fi state, IP/hostname, heap, OTA busy state, and recent warnings/errors.

Project Aura is designed around high-quality components to ensure accuracy. If you are sourcing parts yourself, look for these specific modules:

Affiliate note: the Waveshare board link above is an affiliate link and helps support Project Aura at no extra cost.

Sensor note: the SFA30 is fully supported and widely available. Support for the successor model (SFA40) is on the roadmap. CO note: the SEN0466 is optional. If not detected at boot, CO is marked unavailable and PM1 telemetry remains active. Note: SEN66 gas indices (VOC/NOx) require about 5 minutes of warmup for reliable readings; the UI shows WARMUP during this period.

Recommended retailers: Mouser, DigiKey, LCSC, Adafruit, Seeed Studio, Waveshare.

Please pay close attention to the cabling. The pin order on the board is custom and requires modification of standard off-the-shelf cables (pin swapping).

Backers: please refer to the comprehensive Build Guide included in your reward for the exact wiring diagram and a trouble-free assembly.

DIY: verify pinouts against the pin table below before powering on to avoid damaging components.

Display and touch are integrated on the board; no external wiring is needed for them. For DAC control, analog output is generated on the GP8403 module (VOUT0), not on a direct ESP32 pin.

Project Aura speaks your language. You can switch languages in the Settings menu:

• English
• Deutsch
• Espanol
• Francais
• Italiano
• Portugues BR
• Nederlands
• Simplified Chinese

Data flow and responsibilities are intentionally split into small managers:

Core modules live in src/core/ and orchestrate startup (AppInit, BoardInit). Feature managers are in src/modules/, UI in src/ui/, and web pages in src/web/.

Prerequisites: PlatformIO CLI or VSCode + PlatformIO extension. Built with Arduino ESP32 core 3.1.1 (ESP-IDF 5.3.x).

1. Wi-Fi setup: On first boot, the device creates a hotspot: Aura-XXXXXX-AP (fallback: ProjectAura-Setup). Connect to it and open http://192.168.4.1 to configure Wi-Fi credentials.
2. Web portal: After saving Wi-Fi, wait about 15 seconds for AP -> STA transition. Then access the device at http://.local/ (default hostname format: aura-XXXXXX, for example aura-1a2b3c.local) or by IP. Do not keep using http://192.168.4.1 after STA connection; that address is AP-setup only. In STA mode, / opens the dashboard. In AP mode, / opens setup and /dashboard opens the offline dashboard.
3. Home Assistant: MQTT discovery is enabled by default. The device appears in HA via MQTT integration automatically. A ready-to-use dashboard YAML is available at docs/home_assistant/dashboard.yaml. Setup guide: docs/home_assistant/README.md.

Optional compile-time defaults belong in include/secrets.h, which is ignored by git. Copy and edit:

• State topic: /state
• Availability topic: /status
• Commands: /command/* (night_mode, alert_blink, backlight, restart)
• Home Assistant discovery: homeassistant/*/config
• Discovery payload includes dedicated sensors for CO (co) and PM0.5 (pm05).

MQTT stays idle until configured and enabled.

Contributions are welcome! Please read CONTRIBUTING.md for details on the process for submitting pull requests and the Contributor License Agreement (CLA).

Found a bug? Open an Issue: https://github.com/21cncstudio/project_aura/issues Have a question? Ask in Discussions: https://github.com/21cncstudio/project_aura/discussions

Parts of this project are developed with AI-assisted workflows. Primary coding assistance is provided by GPT-5 Codex in a local developer workspace.

• Firmware in this repository is licensed under GPL-3.0-or-later (see LICENSE).
• Commercial use is allowed under GPL. If you distribute firmware (including in devices), you must provide the Corresponding Source under GPL.
• If you need to sell devices while keeping firmware modifications proprietary, obtain a Commercial License (see COMMERCIAL_LICENSE_SUMMARY.md).
• Enclosure models and the PDF build guide are not in this repository; they are available to backers on MakerWorld under separate terms.
• Trademark and branding use is covered by TRADEMARKS.md.

See TESTING.md for native host tests and scripts/run_tests.ps1.

• src/core/ boot, init, reliability
• src/modules/ sensors, storage, network, MQTT, time
• src/ui/ LVGL screens, assets, controllers
• src/web/ HTML templates and handlers
• test/ native tests and mocks