Know your air. AirCube is a desktop air quality monitor with built-in Home Assistant support. It tracks temperature, humidity, CO2, TVOC, and AQI -- showing air quality as a single, glanceable LED color and reporting every reading to your smart home over Zigbee.
Works standalone out of the box. Pairs with Home Assistant in minutes.
Watch the demo (early build -- Home Assistant integration came after this video)
1. Plug it in -- Connect the USB-C cable to any USB port or charger. AirCube powers on automatically.
2. Wait for warm-up -- The air quality sensor needs about 3 minutes to stabilize after power-on. During this time, the LED may not reflect accurate readings.
3. Read the color -- Once warmed up, the LED tells you everything:
| LED Color | Air Quality |
|---|---|
| Green | Good |
| Yellow | Moderate |
| Orange | Poor |
| Red | Bad -- consider ventilating |
The color shifts smoothly as conditions change. No app needed -- just glance at it.
4. Adjust brightness -- Press the button to cycle through brightness levels.
That's it. AirCube works out of the box with no setup, no accounts, and no Wi-Fi.
| Measurement | What It Tells You |
|---|---|
| AQI (Air Quality Index) | Overall air quality score, reflected by the LED color |
| eCO2 | Estimated CO2 in ppm -- rises in stuffy or crowded rooms |
| eTVOC | Volatile organic compounds in ppb -- cleaning products, paint, off-gassing |
| Temperature | Room temperature in Celsius |
| Humidity | Relative humidity percentage |
The LED color is based on the AQI value. To see the individual numbers, connect to a computer or to Home Assistant.
AirCube was designed for Home Assistant. It connects over Zigbee -- no USB cable to your server, no cloud, no Wi-Fi credentials to configure. Plug it in, pair it, and all five sensors show up on your dashboard automatically.
Once connected you can:
- Track air quality over time with built-in history graphs
- Set up automations -- turn on a fan when CO2 gets too high, send a notification when AQI spikes
- Monitor every room -- each AirCube pairs independently, name them however you like
You'll need: a Zigbee coordinator dongle (we recommend the SONOFF ZBDongle-E, ~$13) plugged into your Home Assistant machine.
Works with ZHA (built-in) and Zigbee2MQTT.
Full setup guide: Connecting AirCube to Home Assistant
Plug the AirCube into your computer with a data-capable USB-C cable to see live readings, charts, and history.
Check the Releases page for a ready-to-run Windows .exe -- no install required.
git clone https://github.com/StuckAtPrototype/AirCube.git
cd AirCube/scripts
pip install -r requirements.txt
python aircube_app.py
Select your serial port, click Connect, and you'll see live data.
Tip: There's also a lightweight system tray app (
aircube_tray.py) that shows AQI directly in your Windows taskbar. Right-click the tray icon for options.
New firmware releases add features and fix bugs. Updating takes a couple of minutes with just a browser -- no tools to install.
Firmware Update Guide -- step-by-step instructions.
Latest release: GitHub Releases
| LED | Meaning |
|---|---|
| Steady green | Good air quality (AQI 0--10) |
| Yellow through red | Degrading to poor air quality (AQI 10--200) |
| Flashing blue | Zigbee pairing mode |
| Action | What It Does |
|---|---|
| Short press | Cycle brightness (off, 10%, 30%, 60%, 100%) |
| Hold 3 seconds | Enter Zigbee pairing mode |
LED doesn't turn on
- Make sure the USB-C cable is firmly connected and the power source is active.
- Try a different USB port or charger.
Readings seem wrong right after power-on
- Normal. The air quality sensor needs about 3 minutes to warm up. Readings will stabilize.
Computer doesn't detect AirCube
- Some USB cables are charge-only. Use a cable that supports data.
- Windows users may need to install USB drivers.
- Linux users: add yourself to the
dialoutgroup and re-login.
Home Assistant: CO2, TVOC, or AQI sensors are missing
- The custom quirk or converter isn't loaded yet. See the Home Assistant guide for step-by-step instructions.
Home Assistant: AirCube won't pair
- Make sure permit join is enabled in ZHA or Zigbee2MQTT.
- Hold the button for 3 seconds to enter pairing mode (LED flashes blue).
- Move AirCube closer to the coordinator during pairing.
AirCube is fully open source -- firmware, PCB design, enclosure, desktop software, and Home Assistant integration. Everything is in this repository under the Apache 2.0 license.
Developers and makers: See the Contributing Guide for build instructions, architecture docs, serial protocol reference, and how to submit changes.
| Contributing Guide | Build from source, firmware architecture, serial protocol, how to contribute |
| Firmware Update Guide | Update your AirCube firmware from a browser |
| Home Assistant Guide | ZHA and Zigbee2MQTT setup |
| GitHub Issues | Bug reports and feature requests |
| License | Apache 2.0 |
