Native AirGradient integration with HomeAssistant

With the release of HomeAssistant 2024.6.0, a new native Integration for AirGradient is included:
Airgradient - Home Assistant (

This works with the stock firmware and imports all sensor readings. (Except for the boot number that is reported to the Dashboard app, and I plan to put in a request for)


Thanks @MallocArray for being quicker than us in announcing it :wink:

We are still testing it somewhat and want to make sure the new firmware is flashed on the devices by default before making a big splash.

If people want to test it, they can use 3.1.1 firmware and the monitor should be auto discovered.

In case any issues, please let us know.

1 Like

Well, can report it working. Have the integration linked since last night and haven’t encountered a bug so far.

That’s fantastic news, but as I mentioned previously I’m seriously struggling to understand what firmware I have now and what to download.

I believe my two devices are an I-1DIY (DIY_PRO_V4_2) and an O-1PP (DIY AirGradient Outdoor), neither of which seem to be mentioned in the latest 3.1.1 firmware.

Update I’ve attempted to install the firmware on my DIY Pro and although it enters config mode fine, it never shows up as a UART port on the PC so it doesn’t appear to be flashable at all. :man_shrugging: (and yes I’ve tried multiple cables that all work fine with other USB devices)

I am loving the native Home Assistant integration!

For the next release, could you integrate with the Air Quality Building Block Integration? This computes a number of derivative values such as AQI which would be super useful to have on my Home Assistant dashboard.

The Pro model you have doesn’t support the 3.x firmware as it has an older chip and isn’t included as supported with the new firmware. As to why it doesn’t show up as UART, with the older boards based on ESP8266, only power is connected to the chip through the USB port available externally. To flash that chip, you have to open the case and connect to the USB port directly on the D1 Mini (ESP8266). This is one of the big advantages of the newer board, where the externally accessible USB port connects both data and power to the internal chip

Your Outdoor unit should be based on the newer ESP32-C3 chip (Unless it is the very very early outdoor model) so it should be supported by the 3.1.1 firmware and the USB port should recognize it.

Please open an issue on this on our GitHub repo. Thanks!

Thank you so much! This is awesome. I’ve got a bunch of the pre-assembled One’s. I’ve been using them local with Home Assistant for several months now using a firmware someone in the forums linked when I installed them months ago. I took one and reflashed it with the latest 3.1.1 firmware as posted above, dumped my ESPHome device, and re-added it under the AirGradient integration. Here’s my feedback.

  1. The old ESPHome firmware let me turn off the lights at night and dim the screen. This is a must before I reflash the bedroom units for me.

  2. I no longer have a way to force a recalibration. I’m not sure how big of a deal this is though. I’ve got a whole-house-fan, so on nice days I’ll turn off the AC/Heat and within 30 min my house is whatever air is outside. I read that the devices should be recalibrated from time to time so it’s usually when I’ve got the big fan on that I’ll do a recalibrations. (If I’m wrong about this, please correct me :grin: )

  3. The 2.5 AQI is gone. Not a big deal for me, but worth mentioning.

  4. Uptime is gone. This is trivial. In fact, I only ever looked at it because it was there. :laughing:

  5. it would be nice to have the min/max values as well as each of the “levels” that change the LED color bar within Home Assistant to make it easier to trigger things like - turn on the air filter. I’ve got values I’ve manually set, but it would be nice to match the device.

Thanks again! This is amazing!

The version now is the first release for HA with the primary focus to get the data into HA.

Works continue to add local configuration (eg LED bar, manual calibration etc).

So you can expect these features to all come alive in the next few HA releases.


For most of the items you mentioned, now that you are running the stock firmware 3.1.1, the configurations you are looking for are in the AirGradient Dashboard.

From the page, click the three bars menu button in the upper left, then select Place, then “LED & Display” to configure a Night Mode that will turn off/dim the display and LED bar

To initiate a CO2 calibration, from the main Dashboard page, click the three dots button to the far right of a device under the Admin column, and select Edit Location. Check the box to “Request CO2 Calibration” and the command will be sent to the device

Uptime isn’t directly in the Dashboard site, but if you go to the Menu>Hardware page you will be able to see the “Current Boot Count” value go up. There is a bug in the current 3.1.1 firmware so this isn’t working, but I believe it will be included in the next version

To see the LED color numbers (or at least the documentation about them) go to Menu>Support>“More About Monitors LEDs” and you can switch between CO2 and PM2.5.

As Achim said, in the future I think the native HA integration will let you change some of these directly from HA, but until then, you still have options available.

I was delighted to discover native Home Assistant integration. It just showed up in HA and asked me to enable it.

Unfortunately the LED dimming doesn’t work. I tried to dim the LED to 0%. The window tells me the value is saved, but the LED are the same intensity as before. I tried daytime and nighttime settings and I rebooted it, but I can’t dim the LEDs anymore.

Can you please post your exact settings so that we can try and reproduce this?

Just as I was planning to flash ESPHome I am really happy to see the native HomeAssistant integration. This seems much easier, and worked right away. So, thank you!

I would look forward to future development which allows turning off the OLED screen as well as the LEDs. I think someone mentioned that this is in the works in a different thread. This would then be really nice for a bedroom at night, to have HomeAssistant control the LED/OLED schedules.

(I have not tried adjusting LED settings via HomeAssistant.)

Are you trying to adjust the LED dimming in HomeAssistant or in the AirGradient Dashboard site?

As far as I know, you have to adjust it in the AirGradient Dashboard at this time.
If you were adjusting it there, but it wasn’t being reflected on your device, in the HomeAssistant configuration for the AirGradient, you may have to change the Control option from Local to Cloud. I had an error appear when I tried to make this change, but not sure if it actually updated and accepted cloud control or not.

1 Like

I was excited to install firmware 3.11 because the lights being on at night also meant I had to keep my sensors out of the bedrooms. It worked great configured from the web app online.

However, the next day I connected them to Home Assistant and I realized that despite poking around at the web app some more the lights wouldn’t turn off anymore. I just discovered the “Configuration source” option and I tried setting it from Local to Cloud. Like @MallocArray I got an error when I did this.

I’ll see tonight if this actually works.

Thanks for the information. I don’t use the web dashboard, nor do I care to. I was just wanting to let everyone know my HA experiences and what is still missing that I care about. :slight_smile:

Thank you all for the HA work! It’s much appreciated!

All the configurations we currently set in the web dashboard will become available as local HA configurations in the next few releases.

Is that accessible on AG web Monitor.

How can I get to it???

Never mind, I found it within ESPHome on my HA.