@gohai Hey, I just wanted to say thanks a ton for this. I soldered my kit together today and part of the reason I purchased it to begin with was your library and the ability to add it to homekit and create automations (around a vent+fan to let it outside air along with changing my air purifier speed). Haven’t flashed it to my ESP yet but plan to soon, already I’m really happy with the airgradient product. I’ll report back when I get it flashed and confirm whether it’s working well for me!
Just came across this.
I’ve created an extremely basic flask app which takes the data from Airgradient and exposes it via Prometheus exporter.
The idea being that the simple change of APIROOT in the code can be updated and all data is kept in your own hosted systems.
Does this sound useful - if so I can sort out a docker container.
Hi Themis3000,
I’ve uploaded your code to my AirGradient and it is working fine. And I’ve included the code above in my HA configuration.yaml, but I can’t find the data it should be scraping from my AirGradient. What did you do in HA to access the data? HA is new to me. I thought about using the built-in Prometheus and Grafana to view it (like Jeff Geerling) but that has me stumped also. Would appreciate any direction you could offer.
Hi Barman, cool to hear that my code is working fine for you!
After adding that code to your configuration.yaml you should have new “Entities” in ha to reflect each measurement. Here’s how the HA glossary defines an entity: “An entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. Entities have states.”
You can see all available entities in HA by going to settings > Devices & Services > Entities.
If you’d like a convenient way to view an entity state on your dashboard (aka in this case, view the readings of your sensors), go to your dashboard (the overview panel) and enter editing mode by clicking the 3 dots and clicking Edit Dashboard. Click Add Card, then select the Entities panel. In the entities list search for the air gradient entities (should be called something along the lines of sensor.co_ag, sensor.nox_ag, etc.). After saving you should see all the stats nicely on the dashboard now.
Side note: most of the other card options are also for interacting with entities. Try playing around with these! The gauge for example could be a nicer way of displaying readings.
Let me know if you need any help with these steps or if you’re stuck, I’d love to help out however I can.
Thank you for the response. With your help, I’ve done it and now I’m getting consistent data from the sensor (although my NOX sensor keeps reporting just 1 ug/m3 - I’ll try to figure that out later). I’m happy with this, but eventually, I think I’d like to import my Grafana gauges that I created from following Jeff Geerling’s tutorial on using Prometheus and Grafana. If you’ve managed to get data from HA over to Grafana, I’d love to know how. I tried setting up InfluxDB with no success. I’m mostly just an old Fortran programmer (from the 70s) who loves to experiment with new technology. Everything is still complicated, but in new ways. Thanks again. Bart
Do note that the SGP41 reports a VOC and NOX Index value, not an actual measurement of concentration. I also get a value of 1 from the NOX, but that is just saying that you are getting average values, and if it goes up beyond 1, then it is detecting something
SGP41 Datasheet (sensirion.com)
2 Likes
I’m glad it’s working out for you in HA now! I’ve gotten things working in Prometheus, but I haven’t used Grafana before. I can help you on the Prometheus part of things if you’d like.
The code I wrote that you’re running is just a modified version of the offical code airgradient released. What I added was an http server on port 8080 that has the endpoints /metrics (formatted for prometheus) and /metricsjson (this is the endpoint I use for ha). If you go to your web browser and visit http://(your airgradient ip):8080/metrics or /metricsjson you can see the reading data.
Once you get a prometheus instance running you just need to point it at the /metrics endpoint. Here’s the full prometheus.yml config file I use:
scrape_configs:
- job_name: 'airgradient'
metrics_path: /metrics
scrape_interval: 15s
static_configs:
- targets: ['10.0.0.68:8080']
Let me know if you have any questions about how I have prometheus set up or anything. Best of luck!
I have NOT yet integrated mine into home assistant. working on that now. I bought this because I saw posts where people were doing it… but didn’t look closely and now realize that this isn’t quite as smooth as I had hoped! Still looking for a process that I am able to figure out. Themis3000 I haven’t looked closely at your process yet other than your code states it is for the pro kit, and well, I am a basic kind of guy. I am going to explore something, maybe exactly this home-assistant-integration - Arduino Reference I love the idea of sticking with Arduino code rather than Yaml. Sure don’t understand Yaml, but I have been playing with Arduinos for a while know so can stumble my way through that code. Anyway, that is my vote, something that sticks with Arduino code but integrates through maybe this MQT integration.
I finally got it working. Again integrated via MQTT I used the information from here Getting started - ArduinoHA to finally figure out what I was doing. Well that is a strong phrase, fiddled with things enough that it worked. I am sure it is not the most elegant solution. but I have entities that I can now put on my dashboard and build smart actions around the readings. I can post my code here if it useful to anybody. I don’t see how to do the nice clean cool boxes of code that everybody does. Oh boy and if I don’t then that makes this really long. maybe someone can explain that to me.
Are you really tied to the Arduino code, vs just moving to ESPHome that has much easier integration with HomeAssistant?
I just updated my config file for the Pro board that supports all of the sensors, easily shows all of it in HA, plus buttons to manually calibrate the CO2 sensor, enable/disable automatic calibration, and also reports back to the AirGradient dashboard if you want to be able to do both. All you have to do in HA is to accept the ESPHome device and away you go.
airgradient_esphome/airgradient-pro.yaml at main · MallocArray/airgradient_esphome (github.com)
You need understand my level of coding… I am a copy paste see if it works kind of person. In Arduino I have messed with it long enough that I have a pretty good understand of what most of the code is doing so when I need to change something I can change it. I have been messing with Yaml for just a month now maybe and well, it doesn’t make any sense to me. Seems there isn’t half enough information in the code to make what is happening happen. I tried to just change the units on one of my sensors, the elevation sensor coming in from my phone comes in in meters. I could not for the life of me figure out how to simply get that to report in feet. So… ya, I am a little intimidated by Yaml code. That is not to say I am not up for taking someone’s code and copy paste it into my device as long as I am off to the races from there. So, to answer your question in a very long winded way, I’d be happy to give your code a go is it a problem that I have the basic kit and not the pro kit?
Oh looks like your write up answers my question that basic will work. Mine came with a SHT4x though, which was a problem I had early on. but maybe shouldn’t be too much of an issue? I can give it a go. sorry should read to the end, looks like I’d have to remove my screen. I guess I am kind of fond of having it report on it’s screen. So yeah, I have not doubt doing it in Yaml would be great! But I with plenty of examples took me two days and far too many hours in those days to simply figure it out in a code that I kind of sort of understand. So at this point in my expertise, yes, I am so tied to Arduino code, by force more than anything. 
I can give a try with the SHT4x again, as it was awhile ago and mine was a self-sourced part, not one from AirGradient that may have the resistor removed that was causing problems.
I’ll get back to you in a few days
That is nice of you! But I really don’t want to remove my screen. Based off of what I read on your description that is required for the basic kit for this code to work? Again I appreciate it! I do have it working well enough, sounds like yours has some very fancy features compared to what I have done. Hopefully Airgradient will get something put together for a more plug and play integration! Which seems to be the purpose of this initial post in this thread.
At the time, my Basic kit with the sensor I purchased conflicted with the display, but maybe the newer sensors direct from AG will work, so that is what I’m going to give a shot and see if the display works with it.
sounds great! thank you
Looks like you are still using 2 min interval for PMS5003.
I am using “0s” interval and just doing moving average window.
Airgaradinet folks did not recommend stoping fan of PMS5005. Any specific reason you’ve decided not to use short interval?
Another suggestion is to shutdown LCD screen at night. It is too bright in my night stand
Oops, I was misremembering. In my experience with the Basic kit, it was the SGP30 that wasn’t working with the display, which is a TVOC sensor, but the SHT31 sensor for temp and humidity was fine. In the YAML file, to change it to support the SHT41, it would be just changing the line - platform: sht3xd to - platform: sht4x and the rest should be fine.
But I’ll still test with the SGP40 TVOC sensor again and have an updated yaml file in the next few days that matches the Pro version more closely.
Two reasons
- There is/was a flaw in the software serial implementation in ESPHome that caused the device to reboot frequently when the logging output was very chatty, and the PMS5003 reporting every second was differently related to the reboots. By changing the update_interval to 2 minutes, the issue was mostly solved for me. There are other ways to force newer Software Serial versions, plus newer versions of ESPHome, but this worked consistently for me
- The ESPHome documentation specifically called out changing it to 120s or higher to extend sensor life, so it sounded like a good idea at the time: PMSX003 Particulate Matter Sensor — ESPHome
I only saw recently that Achim from AirGradient didn’t recommend changing the interval, but would like to see some tests side by side to confirm. I have 2 Pro kits, one I sourced parts from AliExpress and one direct from AG, and the one from AG does report higher PM2.5 counts in general, but both are using ESPHome with the same update interval, so I know both are getting readings, just not sure if they would get any more accurate if they were reading every second compared to every 120 seconds.
Early when we were just starting with AirGradient we sourced the PM5003 from AliExpress and got very different quality and some of them were showing considerably higher or lower readings.
Since we source them directly from Plantower, we see very very similar data across hundreds of PM sensors. So @MallocArray when you mention that one of the PM sensors you sourced was from AliExpress, this could be the explanation for it.
To verify you could probably swap the PM sensors to confirm if it’s a firmware or hardware issue,