[EDGE] PurpleAir Air Quality Edge Driver

[TAustin]

I am making available an Edge driver for air quality measurements, that is based on an original Groovy-based driver.

PurpleAir provides realtime monitoring of air quality. You can use your own sensors, or access the many sensors in your geographic area. A free access key can be obtained from their website.

PurpleAir provides a RESTful API to access their sensors via the internet, but because Edge drivers are normally limited to communicating to the local network only, in order to use this driver, you will need to be running my edgebridge application on an always-on LAN computer (Raspberry Pi, Windows, Linux). This application provides a ‘proxy’ or ‘bridge’ for forwarding the API requests to addresses outside the local network.

Features

• Displays AQI, AQI category, and sensor names
• Average of multiple sensors within a defined latitude/longitude coordinate box, or use a specific sensor by index number
• Automatic periodic updates
• Dynamically change the update interval via automations

Thanks to @bthrock for requesting this driver and testing it.

The driver is available on my shared projects channel now, and more information is available in the github README file.

[maranhao]

TAustin, I presume this works with their newer Touch Indoor Sensor as well. Does your driver allow reporting of the VOCs, or just the AQI? I’d love a local solution for reading VOC, I’m currently using Amazon’s devices, but rely on their Smarthome to flip a virtual switch to accomplish what I want.

[TAustin]

@maranhao

reporting of the VOCs

Hello - Right now, the devices include only the AQI, but as long as the VOC data is included in the API response, there’s no reason I couldn’t add it.

This is what I see in the docs regarding the voc measurement:

voc	Number	
VOC concentration (IAQ) in Bosch static iaq units as per BME680 spec sheet, EXPERIMENTAL. Null if not equipped.

Variations:
voc returns average for channel A and B.
voc_a returns channel A data.
voc_b returns channel B data.

Would you just want the voc or do you care also about the channel A and B data?

[maranhao]

I think having the average is better than the individual channel data. Thanks!

[Dennis]

This sounds cool but I have a couple of questions.
Do you know what data is being returned by voc_a and voc_b? ̶A̶r̶e̶ ̶o̶n̶e̶ ̶o̶f̶ ̶t̶h̶o̶s̶e̶ ̶c̶h̶a̶n̶n̶e̶l̶s̶ ̶b̶e̶i̶n̶g̶ ̶u̶s̶e̶d̶ ̶t̶o̶ ̶r̶e̶t̶u̶r̶n̶ ̶m̶e̶a̶s̶u̶r̶e̶m̶e̶n̶t̶ ̶d̶a̶t̶a̶ ̶f̶o̶r̶ ̶P̶M̶ ̶2̶.̶5̶,̶ ̶a̶n̶d̶ ̶t̶h̶e̶ ̶o̶t̶h̶e̶r̶ ̶f̶o̶r̶ ̶P̶M̶ ̶1̶0̶?̶
Is there a free tier for API calls, or will we be responsible to pay for our API calls?

API Pricing

Edit: ̶P̶a̶r̶t̶i̶c̶l̶e̶ matter is part of AQI measurements, not VOC.
Edit #2: Correct terms are particulate matter, or particle pollution.

[TAustin]

I’ve started to look at the code modifications to add the VOC data. Could you help me out by providing me an example of the response data that includes the VOC value(s), along with the (SmartThings) device settings you use? I’m not entirely clear on if this is coming from sensors within a search box, or from a specific device you have configured, and if the latter, how the data is formatted.

You can direct message me the info. Thanks.

[TAustin]

@Dennis

Is there a free tier for API calls, or will we be responsible to pay for our API calls?

When I signed up, they had just converted over to a points system and I got a million points assigned to my account for free. They get deducted every time I make an API call, so not sure what’s going to happen when I run out…

[Dennis]

@TAustin

When I signed up, they had just converted over to a points system and I got a million points assigned to my account for free. They get deducted every time I make an API call, so not sure what’s going to happen when I run out…

That’s some useful information, thanks for sharing. I guess how long the free point allotment will last all depends on the individual’s call frequency, and after the points are used, we’ll need to buy more.

[maranhao]

I don’t, at the moment have a Purple Air device. I currently use an Amazon device, the behavior of which is limited because it can only interact with SmartThings via a simple binary switch. I use the VOCs to trigger an exhaust fan when they are over a certain threshold. I’d really like to make the trigger more sophisticated, e.g. the VOCs increased by X or more over Y or less minutes, and that is why I asked about VOCs in your driver.

[bthrock (Bob)]

It’s worth noting that with Todd’s driver you have the ability to dynamically change the update interval via automations.

In our area, where smoky skies due to wildfires are part of what we call “summer,” AQI has a significant effect on our HVAC automations, so I use the interval change capability to adjust the update frequency based on changing conditions. For example, if the AQI is elevated or changes rapidly, I increase the frequency of updates. If it drops, the call frequency drops.

Also, it’ll take me years to use 1 million points, and $10 to buy another. I can live with that.

[TAustin]

@maranhao

Touch Indoor Sensor

I really don’t know how the PurpleAir Touch Indoor Air Quality Monitor actually works, so I can’t say 100% for sure if it would work with this driver. The web page says that its data is made available through the “PurpleAir Map”; if that means it looks like any other PurpleAir sensor on their network, then yes, it should work. In my vicinity I found a couple public PurpleAir sensors that are returning VOC data and I’ve already made modifications to my driver to display that in addition to the AQI.

If you get one and we find issues, I’ll be happy to do whatever we need to to make it work, even if that means a separate Edge driver.

Please let me know what you plan to do.

[Dennis]

@bthrock

I use the interval change capability to adjust the update frequency based on changing conditions

That’s a really good idea, rather keeping a constant call frequency. The wildfire smoke is a factor here, too, and I was also looking at the PurpleAir Touch but will hold off until I see if it can be supported by this driver. Until then, my Cube air purifiers is running on Auto.

@bthrock

it’ll take me years to use 1 million points

And you’re right, those million points will last a long time for the majority of us.

[granzy]

Thanks for the advice @TAustin in using this driver.
My API key is in the device settings, and I am doing a “Search for devices” and have put in my lat and log and increased the search box size to 25 as well. But I am getting a 402 error in the Bridge server. when pasting the link from the bridge server into a browser I get the following
{
“api_version” : “V1.0.11-0.0.47”,
“time_stamp” : 1690585572,
“error” : “ApiKeyMissingError”,
“description” : “No API key was found in the request.”
}
What am I doing wrong?

[TAustin]

DM me a screenshot of your device settings screen.

[cog89]

I am having the same exact issue. Did you figure it out?

[TAustin]

It looked like he may need to have followed this procedure to ensure that his assigned points are useable:

Your organization starts with one million points. However, these points are not added to any projects yet. On https://develop.purpleair.com/ home, select the “Projects” tab. Next to the project you want to add points to, select the “Update Project” button. Near the top of this pop-up is your organization’s total number of points. Below that, you can enter the number of points to give to this project. Once that is updated, your API keys will work once more.

More information is available here: New API Dashboard - Announcements - PurpleAir Community.

[cog89]

Worked perfectly!

Appreciate the help as always!

[WindBoarder]

(1) If I am the owner of both outdoor and indoor PurpleAir sensors and I have direct LAN access to the sensors, is there any way to use this driver without going through the external API and spending API points?

(2) How can I add an additional device to monitor a second specific PurpleAir sensor?

[WindBoarder]

I was able to answer my own question (2) about how to add an additional device.
I used vEdge Creator V2.94 to create a virtual air quality sensor and then changed the driver of that device to “PurpleAir AQI v1.0”. After filling in the settings, it now provides me an additional PurpleAir sensor device in SmartThings.

[TAustin]

I don’t know what the direct interface to the devices is. If it replicates the cloud-based API, then it may be possible to get it to work. DM me if you want to discuss further.

Regarding what you did to create a second device, I’m very surprised that would even work! Regardless, giving the ability to create additional PurpleAir devices is a feature I can add, but just never did since no one asked before. But if you are happy with what you have, then that may not be necessary!