AirGradient : Air Quality Monitoring

Background

I've been suspicious about the air quality in my direct environment, my home office, the basement, my pergola, the living room where I have my wood fire. Since my recent Arduino experience I was thinking at creating a all-in-one device that can monitor the ambient air quality. This was before I discovered AirGradient.

AirGradient

AirGradient, an open-source project, took root in a Thai school just before the onset of the COVID pandemic, spurred by the wildfire crises in the country's northern regions. This initiative remained pertinent even as COVID emerged. You can explore their journey in depth here.

The platform offers two main options for air quality monitoring: a ready-to-use plug 'n play kit or a do-it-yourself (DIY) version with comprehensive instructions. Sales of these kits on their website support their funding for ongoing research and the maintenance of their dashboard hosting.

In this post, I will walk you through assembling the DIY kit, available for purchase here. For those less inclined towards DIY projects, the indoor Pro KIT offers a straightforward alternative: https://www.airgradient.com/indoor/.

Furthermore, AirGradient nurtures a global community of researchers and scientists dedicated to advancing air quality monitoring. Collaborating with experts worldwide, they continually refine their products. For more insights into their research efforts, visit: https://www.airgradient.com/research/.

I came across a very nice video from Jeff Geerling here :


I immediately realized that I've found what I was looking for.

Device Capabilities

This little device is capable of many things !
  • Temp sensor
  • Humidity sensor
  • CO2 sensor
  • PM 2.5 sensor
The temp and humidity sensors are subject to important note. Due to its position on the PCB it might have accuracy issues, indeed the PM 2.5 sensor is producing some heat. We will talk about that later when building the case.

The CO2 sensor is the most expensive in this list. The AliExpress version is the cheapest but still it will cost you around USD 25

The PM 2.5 sensor is measuring the small particles that could have bad impact on your lungs. You need to be careful about the measured values here.

It is based on Arduino and the firmware flashing process is seamless since it is done directly from the Website !

What I love with AirGradient is the full package proposed : hardware of your choice, open source software, Dashboard, alerts, report and ... API !!!! yes again a new API stack to play with.

Building the hardware

  • Step 1 is buying all the parts to assemble the kit. Most of the parts can be easily found on AliExpress for half of the price of the other merchants.
  • Step 2 is ordering the PCB thru any well known players (JLCPCB, PCBWay, ....)
  • Step 3 is where the fun is coming : putting everything together

I decided to manufacture my PCBs in Red, why not ?

I'm not going to go thru all the building steps, they are well documented on the AirGradient website, but here is couple of views of my own build : 


Then, I 3D printed a box I've found on Thingiverse

        

You can also decide to use the AirGradient enclosure with optimization for the temp sensor that can be found here : https://www.airgradient.com/documents/diy/diy_3d_new.zip 

And here is the finished product : 


Flashing the firmware

This step is seamless these days, you can directly flash the WeMos from the AirGradient Web Page. From there, you can choose between  the Fahrenheit or Celsius based measurement. There is nothing else to share on this trivial part.

If you want to dig into the code, you can find it on GitHub here.

Configuring the WiFi

When flashed, simply boot-up the device and look at the wifi information displayed on the screen.

 
Use your phone to point to this WiFi and browse to 192.168.4.1, there you can configure the WiFi to which the device will connect. When done, push on save and restart the device.

The next start will show up the following status : 


During warming up, the device display its serial number, be sure to write it down in a safe place we will use it to register the device. When the boot sequence is completed, the device already shows the values of each sensors.

Registering the device

The next step is registering the device with the AirGradient dashboard. Open this URL : https://app.airgradient.com/dashboard and create an account.

On logged in, go to "Connect Sensors" in the main menu :

Follow the Wizard to add your new device. Select the option "Setup AirGradient ONE Kit without QR Code" to get it done. The rest of the procedure is really self-explanatory. When done, you will be able to see the sensor data on the dashboard.

Here is a sample dashboard view with 2 devices, one outside in my pergola and another one in my office. At this stage, I'm planning to add 2 more.


You can define alerts, change graph resolution, add/remove column ... play with it, it's easy enough.

Using APIs

Yes AirGradient, is a modern platform and offers API access ! From The Web UI, go to Place and choose at the top the Connectivity Settings tab. You will see this window :


Save this API token in a safe place.

Now, in order to test your API scripts, you can go to this link to use the AirGradient Swagger page : https://api.airgradient.com/public/docs/api/v1/


Example : in order to get the various sensor values in my office, I need to know the locationID.

Listing all locations will provide me with more info.


It will list all locations with some more data :

[
  {
    "locationId": 65440,
    "locationName": "Office",
    "pm01": null,
    "pm02": 187,
    "pm10": null,
    "pm003Count": null,
    "atmp": 23.18,
    "rhum": 45,
    "rco2": 961,
    "tvoc": null,
    "wifi": -90,
    "timestamp": "2024-02-09T22:39:23.000Z",
    "ledMode": "co2",
    "ledCo2Threshold1": 1000,
    "ledCo2Threshold2": 2000,
    "ledCo2ThresholdEnd": 4000,
    "serialno": "xxxxx",
    "firmwareVersion": null,
    "tvocIndex": null,
    "noxIndex": null
  },
  [...]

Let's copy the location ID and use it in the next query : 


Here is the result :

{
  "locationId": 65440,
  "locationName": "Office",
  "pm01": null,
  "pm02": 187,
  "pm10": null,
  "pm003Count": null,
  "atmp": 23.19,
  "rhum": 45,
  "rco2": 940,
  "tvoc": null,
  "wifi": -90,
  "timestamp": "2024-02-09T22:43:43.000Z",
  "ledMode": "co2",
  "ledCo2Threshold1": 1000,
  "ledCo2Threshold2": 2000,
  "ledCo2ThresholdEnd": 4000,
  "serialno": "xxxxx",
  "firmwareVersion": null,
  "tvocIndex": null,
  "noxIndex": null
}

Now, a quick php function later, we have already 2 functions !

function agGetSensors($api_key)
{
    $API="/public/api/v1/locations/measures/current?token=".$api_key;

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($curl, CURLOPT_URL, "https://api.airgradient.com".$API);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);
curl_close($curl);

return json_decode($result);
}

function agGetSensorData($api_key,$locationID)
{
    $API="/public/api/v1/locations/".$locationID."/measures/current?token=".$api_key;

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($curl, CURLOPT_URL, "https://api.airgradient.com".$API);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);
curl_close($curl);

return json_decode($result);
}

How cool is this ? ;)

# php agOfficeVal.php

Temperature : 22.81 °C
Humidity : 46%
CO2 : 596 ppm
PM 2.5 : 5 ug/m3

Domoticz Integration

I managed to add a CO2 sensor in Domoticz which is populated by the AirGradient sensor using API calls.
It's very easy as soon as you know how to do it. First, you need to create a virtual sensor type Air Quality.


Next, we need to go to device and check the sensor index number. Now, this is a combination of reading from AirGradient API and writing with the Domoticz API.

Read from AirGradient : 

// -------------------------------------------------------------------
// Function returning AirGradient sensors data for a specific location
// -------------------------------------------------------------------

function agGetSensorData($api_key,$locationID)
{
    $API="/public/api/v1/locations/".$locationID."/measures/current?token=".$api_key;

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl, CURLOPT_URL, "https://api.airgradient.com".$API);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);
curl_close($curl);

return json_decode($result);
}

Write to Domoticz : 

function sendToSensor($domoticzIP,$sensorIDX,$val)
{
    /* API Reference : https://www.domoticz.com/wiki/Domoticz_API/JSON_URL%27s#Electricity_.28instant_and_counter.29
    */

    $API=$domoticzIP;

    $curl = curl_init();
    curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");

    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'Accept: application/json, text/plain, */*',
'Content-Type: application/json;charset=utf-8'
));
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($curl, CURLOPT_URL, "https://".$API."/json.htm?type=command&param=udevice&idx=".$sensorIDX."&nvalue=0&svalue=".$val);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

    $result = curl_exec($curl);
    curl_close($curl);

    if(json_decode($result)->status=="OK") return TRUE;
    else return FALSE;
}

Then, the main code is only two lines ;)

$co2=agGetSensorData($api_key,65440)->rco2;
sendToSensor($domoticzIP,$sencorIDX,$val);

And the result in Domoticz is this : 


Of course, you can do the same for all sensors. At this time I'm using the outside temperature and the CO2 level in my office in Domoticz. Maybe in the future, some other parameters will be used.

AirGradient CEO Interview

In a captivating discussion, Achim Haug, the CEO of AirGradient, unveiled the compelling narrative behind AirGradient’s emergence as a frontrunner in air quality monitoring. This conversation delved into the origins, philosophy, and future direction of the company. Here's an encapsulation of our insightful dialogue:

The Inception of AirGradient
Q: What was the inspiration behind the founding of AirGradient, and when did it commence?

Achim Haug shared that AirGradient's journey began as a grassroots initiative within a school in Northern Thailand, where we tackled the critical challenge of monitoring alarmingly high air pollution levels in classrooms. This period, known as the "burn season," poses significant risks to respiratory health. Collaborating closely with students and educators, we embarked on a mission to shed light on the dire air quality situation. Our approach included constructing air quality monitors, educating on the health repercussions of air pollution, and exploring proactive measures to mitigate air pollution. This foundational experience underscored our commitment to environmental health and community engagement, setting the stage for AirGradient's future endeavors.

Adapting to Changing Health Landscapes
Q: How does the COVID index on your dashboard fit into the current health landscape?

In response to the pandemic, AirGradient introduced a COVID index to aid in monitoring air quality concerning COVID-19 spread. Achim noted that as the world transitions to a post-pandemic era, the index will be replaced with more general air quality indicators, signaling a shift towards comprehensive air quality management.

The Driving Force Behind AirGradient
Q: Could you shed light on the team that propels AirGradient forward?

The team at AirGradient comprises 4 developers, 2 hardware engineers, 2 scientists, and 2 community managers, alongside a vast network of contributors who enhance the platform with their innovations. The company’s forum serves as a testament to the vibrant community engagement and collective effort in advancing air quality monitoring.

Commercial vs. DIY: Bridging the Gap
Q: What distinguishes the DIY kits from the commercial offerings at AirGradient?

Achim Haug clarified that while AirGradient offers both DIY kits and fully assembled monitors, the primary difference lies in the added benefits of test reports and warranties that accompany the fully assembled products. This distinction underscores AirGradient’s commitment to quality and reliability.

The Open Source Paradigm
Q: How does AirGradient integrate open-source principles into its offerings, particularly the commercial products?

Emphasizing the importance of customization, Achim mentioned that both the DIY and commercial versions of their products adhere to an open-source framework. This approach empowers users to modify the software according to their specific needs, fostering a culture of innovation and personalization.

The Model of Sustainability
Q: With the provision of a free dashboard and data retention, how does AirGradient sustain its operations?

Achim Haug indicated that the free services offered by AirGradient are currently funded through hardware sales. However, with rising server costs, there might be a future introduction of fees to maintain the quality and accessibility of their services.

Community Engagement and Expansion
Q: Can you provide insights into the size and composition of AirGradient’s user base?

With over 10,000 users in more than 70 countries, AirGradient has cultivated a broad and engaged community. Achim pointed out that the distinction between DIY and commercial users is less significant than the collective benefit and experience shared among all users, thanks to the open-source nature of their hardware.

Future Prospects
Q: What advancements can the AirGradient community look forward to?

Looking ahead, AirGradient is set on enhancing its dashboard, improving the onboarding process, and expanding educational resources about pollutants. Ongoing research to ensure sensor accuracy remains a cornerstone of their mission to provide reliable air quality data.

Conclusion

AirGradient offers an affordable and precise method for monitoring air quality, a fact I came to appreciate deeply after completing this project. It has become clear that the importance of air quality is often overlooked. With remote work becoming increasingly common, spending lengthy periods in the same space without fresh air can impact your health, cognitive function, and overall productivity. Having installed a device in my office, I now make it a point to open the window for 15-20 minutes every hour. This simple practice effectively reduces CO2 levels in the room and invites fresh air in, significantly enhancing the work environment.


I hope this help !








Comments

What's hot ?

Wallbox : Get The Most Of It (with API)

Mac OS X : Display images in-line with terminal