Local Home Assistant Integration for AirGradient devices

Software integrations
#1

I’m working on a Home Assistant integration that enables AirGradient devices running stock firmware to be integrated with HA.

It works by exposing an HTTP endpoint to which the devices can post their measurements (mimicking the dashboard API). New devices are automatically discovered when data arrives.

The only device I can test with is the AirGradient ONE V9, so that’s what’s currently supported. Other devices may work fine but YMMV.

To use this integration you must change the APIROOT variable in the firmware to the URL of your local Home Assistant server (i.e.: http://homeassistant_host:port/)

Instructions can be found on GitHub: GitHub - just-oblivious/airgradient_ha: Local AirGradient integration for Home Assistant. Installation through HACS is recommended to stay up-to-date.

When everything is setup correctly your devices should be discovered automatically:

image

When a device is first seen its measurements are enumerated and sensors are created:

image
image673×730 62.1 KB

There’s still some polishing left to do before this can become a compliant HA integration that conforms to the HA development guidelines (like the missing logo).

I appreciate your feedback on this.

3 Likes
#2

I am interested to try this once it is available. I have been working on an MQTT implementation for AirGradient and setup a broker in Home Assistant to publish the data to. It works but this sounds like it would have bene easier.

#3

ESPHome works extremely well on these devices too, and you get the HA integration for free :slight_smile:

#4

Oh this is nice — so using this, you could have the device both pushing data to AirGradient’s cloud, and to your local HA instance, correct?

Ah, took a glance, it looks like it works by diverting the URL to point at your local Home Assistant install. It would be really cool if there were a way to get ESPHome + AirGradient support (without customizing things so much) so I could use both at the same time.

#5

That is completely possible with this:
MallocArray/airgradient_esphome: ESPHome definition for an AirGradient DIY device to send data to HomeAssistant and AirGradient servers (github.com)

Currently the “Upload to AirGradient Dashboard” is disabled by default, but just a flip of a switch in HomeAssistant to enable it (Assuming you have your ID registered in the AirGradient Dashboard)

1 Like
#6

I’ve been running HA for several years, and recently setup two AirGradients which are working fine to the AirGradient cloud. I’d really like to get them logging locally, but I don’t really understand all the references to ESPhome, does this mean I’m no longer running AirGradient code and instead a custom firmware? And I also need to install ESPhome somewhere as a go-between to HA?

This new integration seems like a much nicer option to “remain stock”, but now I’m unclear if I can send to both without replacing all my firmware anyway?

#7

Yes, you would convert the units to ESPHome firmware (which is ‘custom’ compared to the stock firmware). There is no need to install anything between ESPHome and HA, as HA can connect directly to ESPHome (ESPHome is intended for usage with HA and provides a native API connection).

It is a significant change, and is not for everyone (mostly it’s useful for those of us who are already using ESPHome on other devices).

#8

Thanks for the explanation. I’m in the same boat as jfitzell. Suppose I go the ESPhome route, I do need to install the ESPHome Add-on in HASS, correct? Which in my case would mean a seperate ESPhome Docker, as I’m running HASS in Docker, which does not have the Add-On store.

Personally I’m looking at the MQTT route, as I already have a MQTT broker setup. Hopefully it comes available soon for the Gen 9.

#9

Correct. I run HA in Docker and have another container running ESPHome. I explained it a bit more in this thread:

If you aren’t looking to reconfigure much, you can use the .bin files from the ESPHome integration repo and just install it using the web flasher so you don’t need to install ESPHome right now, you just can’t configure the name of the device, but if this is a first device and an intro to it, then it is a low friction route.

I ended up finding a lot of uses for ESPHome so I have devices acting as IR blasters, controllers for dumb ceiling fan remotes, temperature monitors for air coming in and out of my HVAC, and more. So once you start down the rabbit hole, you may find a lot of things you can do with it.

1 Like
#10

Thanks for your reply, I appreciate it. I’m still a bit confused, pardon for asking but do I still need to run an ESPHome Docker container if I go the .bin file route? Or is it sufficient to just flash the .bin file via web.esphome.io without running the ESPhome Docker container?

Thanks

#11

Not initially. It won’t know about your Wifi network, so after using the .bin file you’ll have to find the hotspot that it creates so you can enter your wifi info and then it will be on your network. Hopefully it is autodetected by HomeAssistant, or you may have to find the IP address to add it to HA if it doesn’t.

Then you should be good to get started, all without ESPHome Docker.

2 Likes
#12

Also it is not necessary to use Docker to use ESPHome to build new/modified firmware images and upload them to devices; while that is a convenient option for many HA users, it’s not the only mehod. The ESPHome software can be directly installed on pretty much any computer you wish and used to manage firmware configurations and files. You won’t have the ‘ESPHome Dashboard’ in your HA console, but that’s not necessary either.

2 Likes
#13

@MallocArray @kpfleming Thanks for the information, I appreciate it :slight_smile:

#14

Sorry for asking, but is there also a possibility to go back to the stock firmware after flashing the ESPHome firmware? Is it just a matter of following these steps: Factory Flashing ?

Thank you

#15

Yes, you can go back to the stock firmware without issue. Not sure how you got to that page in particular, but I would use the specific model pages and use whatever firmware they have listed there, such as:
The AirGradient ONE Air Quality Sensor (Presoldered-Version, PCB Version 9)

1 Like
#16

temperature monitors for air coming in and out of my HVAC

What hardware are you using for this?

#17

I’m using 2 DS18b20 sensors I got off Amazon for cheap, integrated to ESPHome with this:
Dallas Temperature Sensor — ESPHome

1 Like
#18

Thanks @MallocArray , I’m not ignoring you I’ve just been out of control busy lately :slight_smile:

Tbh one thing I’ve really struggled with is which model of AirGradient’s I even have (looking at the instructions hasn’t completely helped and I don’t really want to dismantle them just to read a number on the PCB). This uncertainty makes me very uncomfortable to flash them with anything, official or not. Is there a way I can check definitively what models I have? (I’d thought they would show in the cloud app but it doesn’t seem to know, and after I set one model incorrectly I don’t even seem able to change it back to blank)

#19

There are really only 4 primary models out there (6 if you want to get into the weeds)

Is yours an Indoor or Outdoor model?
If Indoor, did it come in the big white case?
If in the white case, does it have LEDs across the top?

  • If it has the white case and LEDs, it is model I-9PSL-DE or I-9PSL, also known as AirGradient ONE with the v9 board. DE means Display Edition but since there isn’t a non-display edition at this time, it is the same as I-9PSL
  • If it has the white case and no LEDs, it is model I-1DIY in the Dashboard, also known as AirGradient Pro. It came with multiple versions of the motherboard, but aside from one having a button and the other not, I think you are mostly ok. With ESPHome config, there is no difference between the motherboard versions, you just can’t use the physical button on a board without it. There are different AirGradient software versions for the different models you can find on the Documentation page, depending if your board is v4.2, 3.7 or earlier than 3.7. I don’t think they are actively maintaining the software for this version as far as I know Build instructions (airgradient.com)
  • If yours didn’t come with a case at all and you had to 3D print one, then it is model I-1DIY in the Dashboard also known as DIY Basic. ESPHome config is the same despite the board versions and the AirGradient code is the same for all of the Basic boards as far as I know.

Ultimately, I haven’t heard any reports of a board being bricked by doing any firmware, as there is a way to re-flash it even if it didn’t work as expected. So you can go between ESPHome or AirGradient firmware as you please.

#20

Hi @MallocArray sorry for the recent spam, life has been way too busy and I could never work out how to switch my AirGradients to ESPhome. After using the AirGradients for about 8 months now they’ve ticked the box in terms of air quality monitoring but ticked none of the boxes they promised in terms of local logging, MQTT or openness etc.

I was seriously considering binning them, and then Home Assistant announced support in 2024.6 and I’m investigating further (hence the flurry of spam). So… clearly my pre-soldered versions were a dud purchase. I have now tried several things and not sure of the results.

I used the link you shared above to install basic ESPhome and can go to the device webpage that then didn’t allow me to install the BIN file because there wasn’t enough space.

I then used the link above to install the Pro BIN from your github, which appears to have worked successfully, and I can see in the UART logs (and the screen) that it’s working… but I can’t get to the device webpage, nor is it showing in the AirGradient app anymore. (the LCD is also using American measurements instead of Australian which I’m not sure how to change)