Know your air. AirCube is a desktop air quality monitor with built-in Home Assistant support over Zigbee. It tracks temperature, humidity, eCO2, TVOC, and AQI -- showing air quality as a single, glanceable LED color and reporting every reading to your smart home.
Works standalone out of the box. Pairs with Home Assistant in minutes. Other platforms are supported through community-contributed extensions.
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 | Range | What It Tells You |
|---|---|---|
| AQI (Air Quality Index) | 0 -- 500 | Overall air quality score, reflected by the LED color |
| eCO2 (equivalent CO2) | 400 -- 65,000 ppm | Estimated CO2 level derived from detected VOCs |
| eTVOC (equivalent Total VOC) | 0 -- 65,000 ppb | Total volatile organic compound concentration |
| Temperature | Room temperature in Celsius | |
| Humidity | 0 -- 100 % | 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. For other hubs, see Community extensions.
AirCube uses the ScioSense ENS161 metal-oxide (MOX) gas sensor paired with the ENS210 temperature and humidity sensor. The ENS161 contains four independent sensor elements and runs all signal processing on-chip -- the firmware reads finished results over I2C, and the ENS210 feeds live temperature and humidity back into the ENS161 for compensation.
eCO2 -- equivalent CO2 (ppm) The ENS161 does not measure CO2 directly. Instead, it detects the volatile organic compounds (VOCs) and hydrogen that humans produce alongside CO2 through breathing and perspiration. Because VOC and CO2 levels rise and fall together in occupied rooms, the sensor converts its VOC readings into an equivalent CO2 value in parts per million. This lets you use familiar CO2 thresholds to judge air quality:
| eCO2 (ppm) | Rating | What it means |
|---|---|---|
| 400 -- 600 | Excellent | Fresh air -- target level |
| 600 -- 800 | Good | Normal indoor air |
| 800 -- 1,000 | Fair | Optional ventilation |
| 1,000 -- 1,500 | Poor | Stale air -- ventilate |
| > 1,500 | Bad | Heavily contaminated -- ventilate now |
A key advantage over a dedicated CO2 sensor is that the ENS161 also detects odors, cooking fumes, and bio-effluents that pure CO2 sensors miss entirely.
eTVOC -- equivalent Total Volatile Organic Compounds (ppb) Thousands of VOCs exist indoors -- from building materials, furniture, cleaning products, paint, cooking, and human metabolism. Many cause headaches, eye irritation, or drowsiness (sometimes called Sick Building Syndrome). The eTVOC reading sums these compounds into a single parts-per-billion value. Higher means more VOCs in the air. A spike after cleaning, cooking, or opening new furniture is normal; sustained high readings mean you should ventilate.
AQI -- Air Quality Index (0 -- 500) AirCube reports the AQI-S index, a relative air quality score defined by ScioSense. It uses the average air quality of the past 24 hours as a baseline reference of 100:
- Below 100 -- air quality is better than the 24-hour average.
- Above 100 -- air quality is worse than the 24-hour average.
- 0 is the best; 500 is the worst.
Because AQI-S is relative, a low number does not guarantee good air in an absolute sense -- it means conditions have improved compared to recent history. For absolute thresholds use the eCO2 or eTVOC values.
The LED maps AQI to color: green for 0--10 (excellent), smoothly shifting through yellow and orange to red at 200+ (poor).
The ENS161 needs about 3 minutes of warm-up in standard mode before readings stabilize. On the very first power-on of a new sensor the initial start-up takes about 1 hour as the sensor conditions itself. Readings during these periods may be inaccurate -- the LED and status flag will indicate when the sensor is ready.
Maintained by StuckAtPrototype: firmware, hardware, desktop app, and the Home Assistant integration documented in HOME_ASSISTANT.md.
Community-contributed: integrations built and shared by the community. They live in this repo and are welcome, but StuckAtPrototype does not test or ship them. They may require extra setup and can break when a vendor updates their platform. See Community extensions.
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 eCO2 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
The integrations below are community-contributed. They are not maintained by StuckAtPrototype and compatibility with vendor hub or app updates is not guaranteed.
Some users run AirCube on a Samsung SmartThings Zigbee hub over Zigbee (no Wi-Fi configuration on the device). The hub must support SmartThings Edge.
By default, the SmartThings app may only show temperature and humidity until you install the community AirCube Zigbee Edge driver from this repository and assign it to the device.
Full setup guide: Connecting AirCube to SmartThings (pairing, SmartThings CLI, driver channel, verification in the app and Advanced Web App).
Troubleshooting: If you only see temperature and humidity, install the AirCube Zigbee Edge driver from smartthings/aircube-zigbee/ and assign it to the device. Details are in SMARTTHINGS.md.
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: eCO2, 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. Community-contributed integrations (see Community extensions) also live in this repository. Everything is 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 |
| Samsung hub integration | Community-contributed: Edge driver, CLI setup (see Community extensions) |
| GitHub Issues | Bug reports and feature requests |
| License | Apache 2.0 |