Project Aura AQ, an open hardware air quality station on the ESP32-S3

What the firmware is and what you have to build yourself

Project Aura AQ is an open source ESP32-S3 air quality station, and the README is precise about who it is for: makers who want a polished, finished device rather than a temporary sensor prototype. The workflow it describes is that you print the enclosure, install top-tier sensors, flash the firmware from a browser, and end up with a touchscreen air quality monitor with a local web dashboard, OTA updates, MQTT and Home Assistant integration, optional 0-10V ventilation control and no cloud dependency.

This repository holds the firmware source and the configuration needed to flash and customise the device. It was created and is maintained by Volodymyr Papush of 21CNCStudio, and the licence field on the repository says GPL-3.0.

The hardware has two supported display options, the Waveshare ESP32-S3-Touch-LCD-4.3 and the ESP32-S3-Touch-LCD-7.0, and the README states that the 16 MB flash version is mandatory for both. The minimum useful bill of parts is a compatible Waveshare display board, a Sensirion SEN66 sensor and stable 5V/2A USB power, with everything else optional. There are two build paths: the recommended custom Aura PCB, which needs no soldering, and the classic module-based Adafruit, STEMMA QT or Qwiic path.

One structural detail is worth knowing. The repository contains a COMMERCIAL_LICENSE_SUMMARY.md file alongside the GPL-3.0 LICENSE, plus a TRADEMARKS.md, so the project separates the licence of the firmware from the terms attached to commercial use of the name and design.

The platform badges name ESP-IDF 6.1, the ESP32-S3 target and LVGL for the user interface, and a platformio.ini sits in the repository root next to the CMakeLists.txt.

Two firmwares, two screen sizes, and the OTA trap

The firmware section of the README is where the project earns its reputation for honesty, and it is the first thing a new owner should read.

The Aura AQ 4.3 inch and Aura AQ 7 inch use separate firmware builds, and the current stable builds are named explicitly as 1.2.0 - 4.3 and 1.2.0 - 7-dual-i2c. The README asks you to read the v1.2.0 update guide before updating either board. The 4.3 inch model does not need internal sensor rewiring, but its update and USB-C instructions changed too.

Then comes the warning that dominates the section, set in capitals. It says not to update an Aura 7-inch board through OTA, and that updating a 7-inch board without following the complete procedure in the guide will damage the board. The instruction is to use the web installer and complete every 7-inch step in the published order.

The GitHub release for v1.2.0 contains exactly one OTA file, project_aura_4_3_1.2.0_ota_firmware.bin, and it is for the 4.3 inch model only. No 7-inch OTA file is published on GitHub at all. So the failure mode for someone who does not read carefully is concrete: they look for an over-the-air update for their 7-inch board, and the file that looks like it exists does not, while the 4.3 file would be the wrong firmware for their hardware.

For diagnostics there is a per-device page at http://<your-aura-ip>/diag with a Download report option, and the README asks you to save the JSON report before restarting or unplugging the device if a problem is active. That is a reasonable design for a device that is often on a shelf with no screen in front of you.

The releases tell the same story. v1.1.5 shipped in May 2026, a beta build in early September and v1.2.0 on 2026-09-07, with the last push on 2026-10-14.

Getting the first flash on without opening the terminal

The README offers two ways to get firmware onto the device and the browser route is the one it recommends for a first flash.

The web installer is described as letting you install or update Aura AQ from a compatible browser, and the project's own instructions insist that the 7-inch board be updated through it and through every published step. There is also an official website at aura-aq.com with a device page covering features, supported hardware and build paths, and the installer page itself.

Developers can build from source with ESP-IDF 6.1, and the repository root shows the two build systems in play: a CMakeLists.txt for the ESP-IDF path and platformio.ini for the PlatformIO path. There are also two configuration presets, sdkconfig.defaults and sdkconfig.defaults.idf61, with the second clearly named for the newer ESP-IDF release. The partition table is a separate file, partitions_16MB_littlefs.csv, which is consistent with the mandatory 16 MB flash requirement.

The offline behaviour is a genuine design decision rather than an omission. The README states the device works without internet, with AP setup mode and the local dashboard fully offline. The setup path is a Wi-Fi access point onboarding flow, and after that the device is reachable over mDNS at http://<hostname>.local, so no cloud account and no port forwarding are involved.

For assembly, the README points to a full assembly guide video that walks through both build styles, covering I2C cable pin swaps, custom sensor cables, module and PCB connections, enclosure mounting, first boot testing and the 180-degree screen rotation setting for the 7 inch build.

What the sensors report and how the screen and dashboard present it

The telemetry list is broad for a single device. Particulate readings cover PM0.5, PM1, PM2.5, PM4 and PM10. The gas set is CO, CO2, VOC, NOx and HCHO, plus one optional electrochemical gas, with the choice being NH3, SO2, NO2, H2S, O3 or O2. Climate values include temperature, humidity, absolute humidity and pressure.

The SENSIRION SEN66 is the baseline sensor in the minimum bill of parts, which is what provides the particulate, VOC, NOx, HCHO and CO2 numbers in one module. The optional electrochemical sensor is a separate addition for a specific gas the SEN66 does not cover.

The user interface is LVGL, described as smooth, with night mode, custom themes and status indicators. The web dashboard lives at the /dashboard path and provides live state, charts, events, settings synchronisation, a DAC page and the OTA firmware update. Both the display and the dashboard are therefore views of the same device rather than separate products, which is the point of a device with a local network interface.

Home Assistant support is automatic through MQTT discovery, with ready-to-use dashboard YAML. That is the integration most smart home users will actually use, since it removes the need to write templates or an add-on.

Hardware autodetection is also handled, with support for the PCF8523 and DS3231 real time clocks, so the firmware recognises the clock on the board it finds rather than requiring a compile-time selection.

Ventilation control, repository layout and the licence split

The optional DAC feature is the most unusual thing in the project. It uses a GP8403 to produce a 0-10V output, with manual levels and a timer, plus an automatic demand mode driven by air quality thresholds. The DAC Auto mode uses editable Display Threshold zones for CO2, HCHO, CO, VOC and NOx, while the PM zones remain fixed, and every zone maximum is inclusive, so the comparison is value <= threshold.

That inclusion detail is the kind of thing that causes support requests, and the README states it explicitly rather than leaving it to be inferred from the code. The practical use is straightforward: the station can drive a fan or a ventilation damper through an industrial 0-10V input without any additional controller, and it does so based on the readings it already takes.

The repository layout shows a substantial embedded project. There are components/, src/, main/, include/ and tools/ directories, a data/ directory, third_party/ and a dependencies.lock file, an idf/ directory, a ui/ directory, scripts/, docs/ and test/. On the documentation side there is CURRENT_STATE.md, TESTING.md, SECURITY.md, CONTRIBUTING.md, CONTRIBUTORS.md, AGENTS.md and a CLA.md, plus THIRD_PARTY_NOTICES.md for the licences of vendored code and TRADEMARKS.md.

The presence of Core0Executor.h at the root is a small but telling detail. The ESP32-S3 is a dual core chip, and a file at that level handling core zero suggests the firmware makes deliberate use of both cores rather than leaving the second one idle.

On the licence, the repository is GPL-3.0 and the README also carries a section on commercial use and a separate commercial licence summary file, which means the firmware licence and the terms for using the brand in a product are not the same thing.

Editorial conclusion

Adopt Project Aura AQ if you want to build your own finished air quality monitor rather than buy a consumer device, and you are willing to follow the assembly guide and the per-model firmware instructions exactly. Do not update a 7 inch board over the air, because the README states that doing so without the published procedure damages the board. Verify first by flashing through the web installer rather than OTA, checking the /diag page on your device, and confirming that your display board has the 16 MB flash the README lists as mandatory.

Frequently asked questions

Official sources

1. 21cncstudio/project_aura on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases