AirGradient API Binding

Add-on Marketplace Bundles
, ,
1

logo

AirGradient provide open source and open hardware air quality monitors.

This binding reads air quality data from the the AirGradient (https://www.airgradient.com/) API.

This API is documented at Swagger UI

Please check out the README file for documentation on how to use the add-on.

Tested on OpenHAB v4.1.1

Changelog

Version 1.1 (2024-05-19)

  • Support local configuration for firmware version 3.1.1

Version 0.12 (2024-05-17)

  • The version that went into the official repository

Version 0.11 (2024-05-08)

  • Discover model
  • Discover local devices without the need for a bridge (less things)

Version 0.10 (2024-04-29)

  • Background (automatic) detection of sensors
  • Improved efficiency after heavy reviews

Version 0.9 (2024-04-27)

  • Added a “boot” channel which shows number of uploads since last reboot. Strange name, but kept in line with name used in AirGradient as it is often used for troubleshooting.

Version 0.8 (2024-04-27)

  • Changed to system types for temperature and humidity

Version 0.7 (2024-03-09)

  • Supports mDNS autodiscovery on beta devices(*)
  • Support reading and setting LED mode for cloud devices
  • Support triggering CO2 calibration for cloud devices

(*) If firmware is changed to only publish _airgradient service on port 80

Version 0.6

  • Bugfixes for local connections
  • Tested against I-9PSL running beta firmware v3.0.6
  • Updated documentation

Version 0.5

Version 0.4

  • Supports Prometheus format for locally access to air gradients

Version 0.3

  • Supports location discovery
  • Tested with O-1PST
  • Tested with I-9PSL

Version 0.2

  • Tested with many more devices
  • Support rco2
  • Support tvoc
  • Support reading single values (e.g. directly from sensors with firmware with a local web server)

Version 0.1

  • initial release
  • supports the most used data from the AirGradient API
  • tested with O-1PP

Resources

Binaries:
https://github.com/austvik/openhab-addons/releases/download/1.1/org.openhab.binding.airgradient-4.2.0-SNAPSHOT.jar

Source code:

2

How can I change the firmware to publish the _airgradient service?

3

To answer my own question, this is default with firmware 3.0.9 (and probably 3.0.8). :slight_smile:

4

Thank you @austvik for this binding :slight_smile:

Using new firmware (3.4.1) ‘tvoc’ is reported as ‘tvocIndex’ which results in NULL tvoc in binding.

Proposed fix:


     81  
     82    Double tvoc = measure.tvoc;                               
     83 +  if (tvoc == null) {                               
     84 +      tvoc = measure.tvocIndex;                              
     85 +  }                                                            
     86    if (tvoc != null) {                                              
     87        states.put(CHANNEL_TVOC, toQuantityType(tvoc.longValue(), Units.PARTS_PER_BILLION));  
     88    }

Can you check/confirm it?

curl -s 'iot14/measures/current' |jq
{
  "pm01": 9.83,
  "pm02": 21.83,
  "pm10": 22.67,
  "pm01Standard": 9.83,
  "pm02Standard": 21.83,
  "pm10Standard": 22.67,
  "pm003Count": 752.5,
  "pm005Count": 702.83,
  "pm01Count": 145.33,
  "pm02Count": 12.33,
  "pm50Count": 0,
  "pm10Count": 0,
  "pm02Compensated": 12.67,
  "atmp": 22.66,
  "atmpCompensated": 22.66,
  "rhum": 52.43,
  "rhumCompensated": 52.43,
  "rco2": 732,
  "tvocIndex": 403,
  "tvocRaw": 30244.17,
  "noxIndex": 1,
  "noxRaw": 16736.83,
  "boot": 0,
  "bootCount": 0,
  "wifi": -62,
  "ledMode": "co2",
  "serialno": "xxx",
  "firmware": "3.4.1",
  "model": "I-9PSL"
}
5

Many thanks from my side too for the binding.
I would have some newby question to the AirGradient configuration:

I’m using the local web access (currently also pushing it to the cloud, but plan to stop that at one point in time). Do I get it right, that with the local access I need to create a separate API thing for every AirGradient device I use? So, if I have 3 indoor sensors, I will end up with 3 API things + 3 location things?

And in addition I also experienced the issue from @mcheffe AirGradient local device TVOC channel not working about the tvoc always being NULL. I assume that’s the same problem as described by @rdslw above.

6

I have just installed and configured the AirGradient binding & sensors, with the AirGradient model I-9PSL-DE unit, for the first time. I have some notes/suggestions, and a question.

  1. The display for the particulate sensors reads as (example): “4.8E-9 kg/m³”, instead of the more typical (and AirGradient referenced) “4.8 µg/m³”. The graph ranges from 0 to 1 with the plot at 0 in this case. The changes to fix this are to set the parameters:

    Type: “Number”
    Dimension: “Density (kg/m³)” (will stay this way, even with unit as below)

    Metadata:
    Unit: “µg/m³”
    State Description Pattern: “%.0f µg/m³” (no decimal) or “%.1f µg/m³” (one decimal)

    1. The TVOC sensor is meant to display as an index, with 100 being baseline. The default display however reads as (example): “0.0000078%”, with a chart that ranges from 0 to 1. The changes to fix this are to set the parameters:

    Type: “Number”
    Dimension: Empty

    Metadata:
    Unit: Empty
    State Description Pattern: “%.0f” (no decimal) or “%.1f” (one decimal), which results in the display now reading “78”.

    1. There is no channel in teh Thing for NOx, even though it’s on the AirGradient Dashboard and producing a reading. Is this a limitation o is something missing in the binding