4. Awair Data Sampling

Overview

The homebridge-awair2 plugin uses the Awair Cloud API to monitor air quality characteristics as well as the Local API to monitor Omni device characteristics for display in HomeKit (reference Table 1 below). The Cloud API and Local API documentation explains the inner workings of the Awair APIs, but for the most part understanding is not necessary to use this plugin.

Data Sampling

When your Awair device is operational, the Awair device samples raw air quality characteristics and device status every 10 seconds. Locally the Awair display is updated. If your Awair is connected to the internet and you have set up your Awair account, the air quality 10 second raw data samples are sent to the Cloud API. This data stream is then used to compute the latest, 5-min avg and 15-min avg which are accessed through the Awair iOS app and by the homebridge-awair2 plugin.

Air Quality characteristics accessed through the Cloud API are:

Sensor	Sensor Description	Units	Units Description	Range
temp	Temperature	°C	degrees Celsius	-40 ~ 185
humid	Humidity	%	relative humidity (RH%)	0 ~ 100
co2	Carbon Dioxide (CO2)	ppm	parts per million	0 ~ 5,000
voc	Total Volatile Organic Chemicals (TVOCs)	ppb	parts per billion	0 ~ 60,000
pm25	Particulate Mass (PM2.5 - Fine Dust)	μg/m³	micrograms per meter cubed	0 ~ 1,000

Note: No personal information is sent to the Cloud API in the data transfer. Reference the Privacy Policy in the Awair iOS app for details.

The Local API accesses the same 10 second raw data as the Cloud API directly from your device through your local intranet (no internet access is required). Air quality values are also available, however, “5-min avg” and “15-min avg” averages are not available. The homebridge-awair2 plugin reads device status for the Omni device characteristic as detailed below. The lux and spl_a values that are returned are the result of sampling at higher different rates on the Omni device to provide an averaged lux value and smoothed spl_a value for the 10 second “raw” data point.

Sensor	Sensor Description	Units	Units Description	Range
battery	Battery charge level	%	Battery charge percentage	0 ~ 100
battery	Battery plugged in	Y/N	Battery charging?	Y/N
light	Ambient light level	lux	Light level	0.96 ~ 64000
sound	Ambient sound level	dBA	Sound Pressure Level, A weighted	48 ~ 90

NOTE: At present, the Local API functionality is only used for Awair Omni device status. Awair R2 and Awair Element both support Local API and functionality may be added in the future. Details for enabling the Local API can be found at on the Local API link provided above.

Operating Details

When the homebridge-awair2 plugin first start up, the Cloud API functionality is used to perform the following:

• The config.json file is checked to see if developer token is available and if there are any changes from default configuration values.
• Your Awair account User Information is read -> Quota limits -> determines polling_interval for Cloud API endpoint sampling.
• Awair devices registered to your Awair account are read -> number of devices -> if device is 'end user' or 'test' device and adds device to device array.
• HomeKit Services are added for Awair devices not on the ignored list (checked via macAddress) according to Awair device type. Services include: AirQualitySensor, TemperatureSensor, HumiditySensor, CarbonDioxideSensor, LightSensor, BatteryService and OccupancySensor.
• Initial air data according to Awair device type is read including: Air Quality, Temperature, Relative Humidity, CO2 Level, VOC Level and PM2.5 Level. If Awair device supports CO2 Level, the CO2 alert level is determined using the config.json values.

... and the Local API functionality is used to perform the following if there is an Omni device present:

• Add BatteryService and determine battery charge level (%), if charging and if low battery is detected.
• Add OccupancySensor service and determine ambient sound pressure level (dBA) -> minimum level used to set quiet room level -> sets upper level for no occupancy and minimum level for occupancy.
• Add LightSensor service and determine ambient light level (lux).

Once initialization is complete:

• A timer loop according to polling_interval collects endpoint air quality data using the Cloud API functionality. Omni battery status is also checked using Local API functionality.
• A second 30-second timer loop checks Omni occupancy status using the Local API functionality.

---

Table 1: Awair Characteristics Monitored by Device