Homebridge Airthings

A Homebridge plugin for Airthings air quality monitors via the Airthings Consumer API.

Requirements

• Homebridge
• One or more supported Airthings air quality monitors
• At least one Airthings SmartLink Hub (Hub, View Plus, View Pollution, View Radon)

Supported Devices

| Airthings Device | Serial Number | | -------------------------------------------------------------------- | ------------- | | Airthings View Plus | 2960xxxxxx | | Airthings View Pollution | 2980xxxxxx | | Airthings View Radon | 2989xxxxxx | | Airthings Wave Plus | 2930xxxxxx | | Airthings Wave Radon | 2950xxxxxx | | Airthings Wave Mini | 2920xxxxxx |

Note: Airthings Wave devices require an Airthings SmartLink Hub (Hub or View Series device) to continuously push measurement data to the Airthings Cloud.

Configuration

Example accessory config in the Homebridge config.json:

"accessories": [
  {
    "accessory": "Airthings",
    "name": "Living Room Airthings View Plus",
    "clientId": "00000000-0000-0000-0000-000000000000",
    "clientSecret": "11111111-1111-1111-1111-111111111111",
    "serialNumber": "2960123456",
    "co2AirQualityDisabled": false,
    "humidityAirQualityDisabled": false,
    "pm25AirQualityDisabled": false,
    "radonAirQualityDisabled": false,
    "vocAirQualityDisabled": false,
    "co2DetectedThreshold": 1000,
    "radonLeakThreshold": 100,
    "debug": false,
    "refreshInterval": 150,
    "tokenScope": "read:device:current_values"
  }
]

Configuration Details

Field | Description -------------------------------|------------ accessory | (required) Must be "Airthings" name | (required) Name for the device in HomeKit clientId | (required) API Client ID generated in the Airthings Dashboard clientSecret | (required) API Client Secret generated in the Airthings Dashboard serialNumber | (required) Serial number of the device co2AirQualityDisabled | (optional) Disable Carbon Dioxide (CO₂) in Air Quality sensor calculation, default is false humidityAirQualityDisabled | (optional) Disable Humidity in Air Quality sensor calculation. default is false pm25AirQualityDisabled | (optional) Disable Particulate Matter (PM2.5) in Air Quality sensor calculation, default is false radonAirQualityDisabled | (optional) Disable Radon in Air Quality sensor calculation, default is false vocAirQualityDisabled | (optional) Disable VOC in Air Quality sensor calculation, default is false co2DetectedThreshold | (optional) Configure a custom Carbon Dioxide (CO₂) detected threshold, default is 1000 ppm radonLeakThreshold | (optional) Enable a Radon Leak Sensor with a threshold in Bq/m³, see additional notes below, disabled by default debug | (optional) Enable debug logging, disabled by default refreshInterval | (optional) Interval in seconds for refreshing sensor data, default is 150sNote: The Airthings Consumer API has a rate limit of 120 requests per hour tokenScope | (optional, experimental) Configure a custom Airthings API Token Scope, default is read:device:current_values

How to request an Airthings API Client ID & Secret

1. Login to the Airthings Dashboard
2. Navigate to Integrations, then API, then Request API Client
3. Create a new API Client with the following configuration:
   • Name: Homebridge
   • Resource Scope: read:device:current_values
   • Access Type: confidential
   • Flow Type: Client Credentials (machine-to-machine)
   • Enable: On

HomeKit Sensors

Air Quality

Air Quality Sensors are supported and implemented using standard Apple-defined services. Air Quality in this plugin is a composite of Radon, Particulate Matter (PM2.5), Volatile Organic Compound (VOC), Carbon Dioxide (CO₂), and Humidity sensors, depending on the sensors supported by your device and your plugin configuration. Air Quality values (Good, Fair, Poor) are based on Airthings-defined thresholds for each sensor.

Sensor | 🟢 Good | 🟠 Fair | 🔴 Poor | ----------------------------------|---------------|------------------------------------|--------------------| Radon | <100 Bq/m³ | ≥100 and <150 Bq/m³ | ≥150 Bq/m³ | Particulate Matter (PM2.5) | <10 μg/m³ | ≥10 and <25 μg/m³ | ≥25 μg/m³ | Volatile Organic Compounds (VOCs) | <250 ppb | ≥250 and <2000 ppb | ≥2000 ppb | Carbon Dioxide (CO₂) | <800 ppm | ≥800 and <1000 ppm | ≥1000 ppm | Humidity | ≥30 and <60 % | ≥25 and <30 % ≥60 and <70 % | <25 % ≥70 % |

Notes:

• Radon measurements are not visible in the Apple Home app, but are visible within some third-party HomeKit apps, including Eve and Home+. See the below section for more details on Radon sensors.
• This plugin converts Volatile Organic Compound (VOC) measurements from ppb (units Airthings devices report) to µg/m³ (units expected by Apple HomeKit).

Radon

Radon Sensors are not natively supported by Apple HomeKit. However, by default, Radon is used as a factor in the Air Quality Sensor (see above).

This HomeBridge plugin optionally supports a Radon Sensor by implementing a Leak Sensor, which is a standard Apple-defined HomeKit service. To enable this, specify a value for the optional radonLeakThreshold configuration property. Note this value is in Bq/m³, not pCi/L. This will be the Leak Detected threshold for the sensor in HomeKit, which can be used for Notifications and within Automations. The Radon measurement itself will not be visible in the Apple Home app, but is visible within some third-party HomeKit apps, including Eve and Home+.

Air Pressure

Air Pressure Sensors are implemented using a custom HomeKit service that is supported by some third-party HomeKit apps, including Eve and Home+. Air Pressure Sensors are not natively supported by Apple HomeKit and therefore not visible in the Apple Home app.

Carbon Dioxide (CO₂)

Carbon Dioxide Sensors are supported and implemented using standard Apple-defined services. The Carbon Dioxide Detected threshold is ≥1000 ppm by default and customizable via the co2DetectedThreshold configuration property.

Temperature & Humidity

Temperature & Humidity Sensors are supported and implemented using standard Apple-defined services.