Homebridge-airthings NPM

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

Login to the Airthings Dashboard
Navigate to Integrations, then API, then Request API Client
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.