Airthings

v1.0

The Airthings driver provides centralized environmental monitoring for up to 16 compatible devices associated with one Airthings Consumer API account. Dealer discovery preserves device slots by serial number, while serialized HTTPS requests publish current radon, temperature, humidity, pressure, CO2, VOC, PM1, PM2.5, battery, timestamps, availability, and stale-data feedback.

Sixteen reusable dealer threshold profiles allow every supported device to use a distinct policy when needed and initialize independent, serial-number-specific persistent customer thresholds that survive project uploads, processor restarts, and power cycles. Absolute slider commands, incremental adjustment commands, automatic linked-boundary adjustment, individual sensor classifications, directional low/high threshold alerts, aggregate air-quality feedback, alert summaries, hysteresis, and startup-safe transition events support RTI interfaces and automation without modifying the Airthings application.

The driver also provides metric or imperial units, polling aligned with Airthings cloud schedules and API caching, inventory validation, token renewal, dynamic rate-limit handling, last-valid-value retention, diagnostics, and processor-bound licensing. Sensor availability and cloud frequency remain device-dependent; Airthings Renew control and historical data remain outside this release.

Requirements

An RTI XP processor with Internet access, working DNS, and correct date and time.

An Airthings Consumer API application and its Client ID and Client Secret.

A dealer computer running Integration Designer with Internet access during device discovery.

At least one supported Airthings device associated with an accessible account.

A valid processor-bound driver license after the evaluation period.

Do not enter the ordinary Airthings account email and password. The driver uses API application credentials.

Integration Designer Setup

1. Add the Airthings driver to the RTI project.

2. Open Driver Properties and enter the API Client ID and Client Secret.

3. Select Imperial or Metric under Unit System.

4. Select the driver and run Driver Configuration > Discover Airthings Devices.

5. Review the reference Device Name, Enable Device, and Threshold Profile selections for every discovered slot. Device identity is controlled by Airthings and refreshed through discovery.

6. Do not manually edit Serial Number or Account ID. These fields bind each slot to the correct cloud device.

7. Review polling, stale-data, failure-threshold, and logging properties.

8. Send the project to the processor and allow time for authentication and the initial sensor refresh.

Device Discovery

Discover Airthings Devices runs through the packaged AutoConfig.py on the Integration Designer computer. It authenticates to Airthings, enumerates the devices associated with the configured Consumer API account, and fills up to 16 preallocated device slots.

Existing assignments are matched by serial number before new devices are placed into free slots. API list-order changes therefore cannot exchange one monitor's RTI feedback with another monitor. The authoritative Device Name, Serial Number, Device Type, Account ID, and Supported Sensors are refreshed from Airthings and stored as hidden AutoConfig data because Integration Designer does not support read-only individual ConfigSettings fields. A separate Device Name reference copy is shown in each visible device section.

Run discovery again after adding, removing, or moving an Airthings device; changing API credentials; or when Device Configuration Refresh Recommended is true. Discovery is not required after an ordinary processor reboot, power cycle, or programming upload.

If discovery fails, confirm Internet and DNS access from the dealer computer, verify that the values are API Client credentials, and check the Airthings service. Credentials and access tokens are never printed in the discovery message or log.

Driver Properties

License Key: The processor-bound Buttonwood Technologies license key.

Client ID and Client Secret: Credentials generated for an Airthings API application.

Unit System: Imperial or Metric. This driver setting controls the units requested from the Consumer API independently of the units selected in the Airthings iPhone application or shown by the physical monitor. Every measurement publishes a friendly unit derived from the API response. Imperial pressure is converted from API pascals to inches of mercury; Metric pressure remains in mbar.

Device Name: A discovery-populated dealer reference only. Do not change this field. Editing it does not rename the Airthings device and does not modify driver variables, commands, events, device binding, or other runtime functions. Rename the device in the Airthings application, rerun Discover Airthings Devices, and resend the project.

Enable Device: Includes the discovered device in runtime sensor polling.

Discovered identity: The authoritative Device Name, Serial Number, Device Type, Account ID, Supported Sensors, and device count are maintained by AutoConfig and hidden from Driver Properties. The visible Device Name is only a reference copy because Integration Designer cannot make an individual ConfigSettings field read-only. Change a device name through the Airthings application, rerun Discover Airthings Devices, and resend the project. Read-only identity remains available through RTI system variables.

Threshold Profile: Select Disabled or one of sixteen reusable dealer-default profiles. ConfigSettings dropdowns use stable Threshold Profile 1 through 16 labels because Integration Designer does not resolve configured-name substitution in that surface. The Profile Name is used in runtime feedback and the Set Threshold Profile command. The assigned profile initializes persistent values for the device; ordinary project uploads do not overwrite later customer changes.

Number of Threshold Profiles: Select 0 (None) to disable local threshold classifications and threshold events for every device, or show from one through sixteen reusable dealer profile-editing sections. The default remains one for compatibility. When zero is selected, the per-device Threshold Profile properties are hidden; persistent profile assignments and threshold values are retained. Raising the count later automatically reactivates each retained assignment that falls within the restored count. Supporting sixteen profiles allows every supported Airthings device to have a distinct policy, while profiles may still be shared when rooms have identical requirements. RTI does not support conditions on individual ConfigSettings choices, so when profiles are enabled each device's Threshold Profile dropdown lists profiles 1 through 16; select only a profile enabled by Number of Threshold Profiles.

Threshold Profiles 1 through 16: Each enabled profile has a dealer name and initial boundaries for radon, temperature, humidity, CO2, VOC, PM1, and PM2.5. Profile 1 ships with the current Airthings US application defaults: radon 2.0/4.0 pCi/L, temperature 64.0/77.0 F, humidity 25/30/60/70%, CO2 800/1000 ppm, VOC 250/2000 ppb, and PM1 and PM2.5 10/25 ug/m3. The remaining profiles initially use the same values and may be customized.

Persistent threshold behavior: Values and the runtime-selected profile are stored against the Airthings serial number rather than the slot number. Each threshold and its profile/unit/schema metadata use separate compact keys to remain below the RTI processor's per-value persistence limit. They survive project uploads, processor restarts, and power cycles, and an earlier aggregate JSON representation is migrated when found. DEV-15 normalizes earlier in-range values to the enforced Airthings increment; an earlier persisted value outside the Airthings application range is invalid and is replaced by the selected dealer profile defaults. Property changes are otherwise applied only when Restore Dealer Threshold Defaults is deliberately run. Radon and temperature values are converted when Unit System changes.

Sensor Poll Interval: Select 3, 5, 10, 15, 30, or 60 minutes; default 3 minutes. Values below 3 minutes are not offered because they can repeat the Consumer API's cached response.

Inventory Check Interval: 1 to 168 hours; default 6 hours.

Stale Data Threshold: 2 to 1440 minutes; default 30 minutes. Confirm the customer's update schedule in the Airthings application: use 30 minutes for Frequent Updates (Every 10 minutes) and at least 90 minutes for Longest Battery Life (Every hour) or Bluetooth-dependent updates.

Request Timeout: 5 to 60 seconds; default 15 seconds.

Request Spacing: 250 to 5000 milliseconds; default 500 milliseconds.

Communication Failure Threshold: 1 to 10 consecutive failures; default 3.

Enable Trace: Logs normal startup, warnings, failures, and recovery.

Verbose Trace: Adds complete HTTP requests and responses, queue activity, rate-limit headers, parsing, and variable writes. It includes the Client ID, Client Secret, access tokens, and Authorization headers in clear text. Enable it only during controlled commissioning; restrict access to TraceViewer and securely delete or protect exported logs afterward.

Runtime Operation

The processor authenticates with the OAuth client-credentials flow and refreshes its Bearer token before the API-reported expiration. Credentials and tokens travel through HTTPS. When Verbose Trace is enabled, complete requests and responses, including authentication secrets, are written to TraceViewer by design.

The driver sends one serial-filtered account-level sensor request for all enabled devices in the configured account. Responses are mapped to slots by both account ID and serial number, and adding enabled devices does not add recurring sensor requests.

The runtime is read-only. It does not send the Airthings Renew remote-control PUT request and does not change any Airthings device or account setting.

Failed requests retain the last valid measurements. API Offline becomes true only after the configured consecutive-failure threshold. Data Stale is calculated from the Airthings recorded timestamp, so a successful HTTP request containing old measurements does not falsely imply fresh device data.

Airthings Measurement and Cloud Schedules

The Sensor Poll Interval controls only how often the RTI processor asks the Airthings Consumer API for the latest cloud record. It does not cause an Airthings monitor to take a measurement, update its display, or upload to the cloud. The complete feedback path is: local sensor sample, local device display, scheduled cloud upload, Consumer API cache, driver poll, and RTI variable update. Each stage has its own schedule.

A View Plus samples temperature and humidity approximately every 2.5 minutes; pressure, VOC, and CO2 approximately every 5 minutes; and radon hourly. The physical display uses these local samples and can therefore show a newer value than the Airthings application, web dashboard, Consumer API, and RTI driver. This difference is normal and does not indicate a driver fault.

When a View monitor is powered by USB-C, Airthings automatically uploads sensor data to the cloud approximately every 2.5 minutes. Its PM sensor also samples approximately every 2.5 minutes. The upload interval cannot be adjusted while USB powered, and radon still updates hourly.

When a View monitor is battery operated, Airthings provides two cloud-sync choices: Frequent Updates (Every 10 minutes) and Longest Battery Life (Every hour). Frequent Updates is the recommended schedule for useful RTI air-quality feedback and disables the hourly battery-saving mode; Longest Battery Life extends battery life but deliberately delays cloud, application, API, and RTI updates. The selected battery schedule also controls the PM sampling interval. It does not slow the other physical sensors' local sampling schedules.

To disable the hourly battery-saving mode, sign in to the Airthings web dashboard, open the applicable View monitor, select its settings icon, and change its syncing or sampling interval to Every 10 minutes. This is an Airthings device setting and cannot be changed by this read-only RTI driver. Allow the device's next cloud synchronization to receive the new configuration. Connecting USB-C power instead causes the automatic approximately 2.5-minute upload schedule, but the batteries are not charged by USB power.

Wave Plus, Wave Radon, and Wave Mini monitors connected through Airthings SmartLink to a View or Airthings Hub generally upload non-radon environmental readings every 5 minutes. Radon remains hourly. Wave Mini mold-risk feedback is also hourly.

Wave monitors used only through Bluetooth depend on phone or tablet synchronization. Their cloud records can lag by as much as an hour even after a local Bluetooth synchronization.

Live Consumer API commissioning returned Cache-Control max-age 120 and CloudFront cache-hit responses. Requests within that approximately two-minute cache lifetime can return the identical payload, Last Measurement value, and rate-limit headers. Airthings controls this cache policy and may change it.

Use a 3-minute Sensor Poll Interval for a USB-powered View or responsive automation, 5 minutes for normal environmental monitoring and hub-connected Wave devices, 10 minutes for a battery-powered View using Every 10 minutes, or 60 minutes for a battery-powered View using Every hour. Polling faster than the device upload schedule does not produce newer measurements and only repeats the newest cloud or cached record.

Expected latency is cumulative rather than real-time. A newly displayed local value must wait for the next device upload, may remain behind the Consumer API's cache for approximately two additional minutes, and then waits for the next driver poll. With a battery-operated View on Every 10 minutes, RTI can reasonably trail the physical display by the remainder of that ten-minute upload window plus cache and polling delay. With Every hour selected, RTI can trail by roughly an hour plus cache and polling delay. USB power substantially reduces this cloud-upload component. Radon remains hourly in every power mode.

Last Measurement is the Airthings recorded timestamp and is the authoritative indication of measurement age. Last Driver Update only confirms that RTI processed an API response; it does not prove that Airthings supplied a new sample.

The runtime parses the Airthings ISO recorded value explicitly rather than relying on the RTI JavaScript engine's native ISO string parser. This supports stale-data calculation and new-sample threshold evaluation on the processor.

Refresh All Sensor Data requests the latest API record but can return a cached response. It cannot force the physical monitor to sample or upload immediately.

The default 30-minute Stale Data Threshold is intended for a battery-powered View using Frequent Updates (Every 10 minutes) and also comfortably accommodates USB-powered View and five-minute hub schedules. If the customer selects Longest Battery Life (Every hour), use at least 90 minutes. Also use at least 90 minutes for Bluetooth-dependent cloud updates. Dealers must confirm the customer's Airthings update setting during commissioning; a threshold shorter than the expected upload, cache, and polling path can assert Data Stale even while the device is operating normally.

The remaining defaults do not need to change. The six-hour Inventory Check Interval is independent of sensor freshness and is frequent enough for uncommon device registration, removal, rename, or account-assignment changes. The 15-second Request Timeout accommodates normal cloud and TLS latency. The 500-millisecond Request Spacing serializes queued operations without changing the recurring poll interval. A Communication Failure Threshold of three filters isolated Internet or service errors; with three-minute polling, persistent failure is normally reported after approximately six to nine minutes.

Commands

Refresh All Sensor Data: Queues an immediate sensor refresh for the configured account. Airthings can return a cached response, so this command cannot guarantee a new physical measurement.

Check Device Inventory: Compares current cloud device serials with the discovered configuration. If a difference is found, run Discover Airthings Devices in Integration Designer and resend the project.

Validate Runtime Configuration: Checks credentials, enabled device identity, and duplicate serial assignments without consuming an API request.

Set Threshold Profile: Selects a discovered device and Disabled or one configured dealer profile. Selecting a profile replaces that device's current thresholds with the selected profile's dealer defaults and persistently makes it the active profile. Selecting Disabled stops local classification and threshold events without erasing the numeric values at that time; selecting a profile later intentionally replaces those values with that profile's defaults.

Set Threshold: Selects the device, threshold boundary, and absolute numeric value in one command. Radon, temperature, humidity, PM1, and PM2.5 use the corresponding x10 threshold-variable scale; CO2 and VOC are unscaled. Runtime validation snaps the value to the same increment used by Increase/Decrease, enforces the Airthings application range, and automatically moves conflicting companion boundaries to preserve ordering. The command supports direct programming and sliders when the GUI uses the selected threshold variable as feedback.

Increase Threshold and Decrease Threshold: Select the device and boundary from drop-down lists. Fixed steps are 0.1 pCi/L or the corresponding metric radon step, 0.5 degrees, 1% humidity, 50 ppm CO2, 50 ppb VOC, and 1 ug/m3 for PM1 or PM2.5.

Restore Dealer Threshold Defaults: Replaces one device's persistent customer values with the current assigned profile. Restore All Dealer Threshold Defaults intentionally performs that reset for every enabled threshold device.

Scaled command values: Radon, temperature, humidity, PM1, and PM2.5 use x10 RTI integer scaling, so 20 represents 2.0 and humidity 250 represents 25.0%. CO2 and VOC use unscaled integers. Use the matching threshold variable as slider feedback.

GUI Slider Programming

For each slider, assign the exact device threshold variable to Value. Assign Thresholds > Set Threshold to Command, select that same device and threshold boundary, and set the command's Value parameter to Dynamic > Value. Do not use a measurement variable as threshold feedback.

RTI's Graph Scale uses the raw integer values sent to the command, not the formatted value displayed in the user interface. XP Diagnostics also shows these raw integers. The driver applies display formatting separately: raw 640 displays as 64.0 degrees, raw 250 displays as 25.0%, and raw 20 displays as 2.0 pCi/L.

Disable Automatic Graph Scale and use the following Minimum, Maximum, and Steps values. These are the enforced Airthings application ranges. Steps is the number of equal slider intervals, not the displayed increment. The driver also snaps every dynamic value to the stated increment.

Temperature - Imperial: Minimum 320, Maximum 1040, Steps 144. This provides 32.0 to 104.0 F in 0.5-degree increments.

Temperature - Metric: Minimum 0, Maximum 400, Steps 80. This provides 0.0 to 40.0 C in 0.5-degree increments.

Radon - Imperial: Minimum 0, Maximum 135, Steps 135. This provides 0.0 to 13.5 pCi/L in 0.1-pCi/L increments.

Radon - Metric: Minimum 0, Maximum 5000, Steps 500. This provides 0.0 to 500.0 Bq/m3 in 1-Bq/m3 increments.

Humidity: Minimum 0, Maximum 1000, Steps 100. This provides 0.0 to 100.0% in 1% increments.

CO2: Minimum 400, Maximum 2000, Steps 32. CO2 is unscaled and changes in 50-ppm increments.

VOC: Minimum 0, Maximum 3000, Steps 60. VOC is unscaled and changes in 50-ppb increments.

PM1 and PM2.5: Minimum 0, Maximum 500, Steps 50. This provides 0.0 to 50.0 ug/m3 in 1-ug/m3 increments.

Runtime Set, Increase, and Decrease commands keep every threshold group in order automatically. If a selected boundary reaches or crosses a neighbor, the driver moves the conflicting companion boundary by the normal sensor increment. Humidity changes can cascade across all four ordered boundaries. Near an absolute endpoint, the selected boundary is clamped only as much as necessary to leave one increment between every member of the group.

The linked change is persisted, published, and reevaluated as one transaction. Last Threshold Command Result and TraceViewer identify the effective selected value and every automatically adjusted companion. Values outside the absolute Airthings application range remain rejected. Driver Properties profile defaults cannot move dynamically in Integration Designer and therefore must already be in valid order.

These enforced ranges mirror the Airthings application screens used during driver development. A dealer may choose a narrower Graph Scale when appropriate, but a wider Graph Scale cannot extend the driver's accepted range. Out-of-range values are rejected and the prior threshold is preserved.

Variables

Driver and Communication provides API online/offline, authentication, configured count, refresh recommendation, queue depth, consecutive failures, last successful communication, last error, last request, and HTTP status.

API Rate Limit provides availability, request limit, requests remaining, reset time, and rate-limited state from the service response headers.

Each discovered device category uses its friendly Device Name followed by its stable slot reference, such as Living Room (Airthings Device 01). It provides configured state, name, serial, type, supported sensors, data availability, stale state, last measurement, last driver update, battery, a measurement summary, recognized measurements, and their units.

Decimal readings use RTI integer scaling metadata. Temperature, humidity, radon, PM1, and PM2.5 use one decimal place. Pressure uses two decimal places. For example, Temperature 257 displays as 25.7 and Imperial Pressure 3008 displays as 30.08. Unit feedback uses familiar labels including %, pCi/L, Bq/m3, ug/m3, F, C, mbar, ppm, and ppb.

Last Measurement, Last Driver Update, Last Successful Communication, and Limit Reset retain their ISO 8601 timestamps with an explicit offset for diagnostics and machine use. Each device also provides Last Measurement Date, Last Measurement Time, Last Measurement Time (24), Last Driver Update Date, Last Driver Update Time, and Last Driver Update Time (24). API Rate Limit provides Limit Reset Date, Limit Reset Time, and Limit Reset Time (24). Date uses M/D/YYYY, regular Time uses 12-hour time with AM or PM and seconds, and Time (24) uses HH:MM:SS; examples are 9/13/2026, 10:29:54 AM, and 10:29:54. These display values use the RTI processor's configured local-time offset. Confirm the processor date, time, timezone, and daylight-saving configuration during commissioning.

Last Measurement is the time Airthings recorded the sensor payload and is the timestamp used for freshness and Data Stale evaluation. Last Driver Update is the later time when RTI successfully received and processed that device's API record. Repeated API polls can advance Last Driver Update while Last Measurement remains unchanged because the device has not uploaded again or the API returned a cached record.

Threshold feedback includes all active persistent boundaries; Radon, Temperature, Humidity, CO2, VOC, PM1, and PM2.5 Status; directional Low/High Threshold Active Boolean variables; Overall Air Quality Status; Air Quality Attention Active; Poor Air Quality Active; and Alert Summary. Sensor states are Unavailable, Good, Fair, or Poor. Temperature uses Unavailable, Low, Good, or High.

Temperature Low/High alerts use its two configured boundaries. Humidity Low/High alerts use the outer Poor/Fair boundaries. Radon, CO2, VOC, PM1, and PM2.5 High alerts use their Fair/Poor boundaries. The alert Booleans are intended for GUI indicators, conditional macros, and notification routing.

Overall Air Quality Status is the worst available radon, humidity, CO2, VOC, PM1, or PM2.5 classification. Temperature is independent and does not affect the aggregate. Pressure has no threshold classification.

Events and Initial Synchronization

Driver events report License Expired, API Online, API Offline, Authentication Failed, API Rate Limit Reached, API Rate Limit Recovered, and Device List Change Detected.

Each device provides Data Available, Data Stale, Data Recovered, individual sensor Threshold Status Changed, directional Low/High Threshold Exceeded and Cleared, Overall Air Quality Status Changed, Air Quality Attention Started/Cleared, and Poor Air Quality Started/Cleared events.

Initial authentication, inventory, device measurements, and classifications establish silent baselines.

Programming reloads and processor restarts do not by themselves fire transition events. Threshold evaluation runs only once for each new Airthings recorded timestamp, so cached repeated responses do not retrigger events. A customer threshold command reevaluates the latest valid readings and can cause a genuine transition. Small clearing margins reduce chatter near a boundary.

Rate Limits

Live commissioning currently returns a Consumer API request limit of 120 with a reset approximately one hour later. The same sensor endpoint returned 5000 during an earlier exploratory run. The driver therefore treats the current Consumer API response headers as authoritative and does not hard-code an assumed allowance.

At the 3-minute default, the single supported account issues about 20 recurring sensor requests per hour regardless of whether one or all 16 device slots are enabled. CloudFront cache hits can repeat the original rate-limit headers and may not consume another origin allowance. A manual Refresh All Sensor Data command issues one additional HTTP request but can also be served from cache.

Responses that omit rate-limit headers do not erase the last known allowance. HTTP 429 activates Rate Limited, preserves the request for retry, honors X-RateLimit-Retry-After or standard Retry-After, and retains the last valid feedback. A later successful request clears the state and fires API Rate Limit Recovered.

The default interval leaves substantial capacity for manual operation, discovery, retries, and service-side allowance changes.

Limitations

Cloud feedback is not real-time and can be delayed by device synchronization or the Airthings service.

Available sensors vary by model. A blank unit indicates that the applicable sensor has not returned a supported reading.

Version 1.0 does not provide historical measurements or Airthings Renew control.

Thresholds are local to the RTI driver. They do not read or change the threshold values or notifications in the Airthings application.

Airthings monitors and this driver are not substitutes for certified smoke, fire, carbon-monoxide, or other life-safety equipment. VOC feedback does not identify a specific gas.

The supplied /v1/health route returned HTTP 404 during live development testing, so runtime health is determined from authenticated API operations.

AutoConfig HTTPS must be commissioned in the installed Windows and Integration Designer environment even though the packaged discovery code passed a live Python 3 test.

Developed & Supported By

Buttonwood Technologies, LLC

rti@buttonwoodtechnologies.com

https://www.buttonwoodtechnologies.com

Version History

v1.0: Initial release.

Product Specific Warning

Airthings measurements, classifications, thresholds, and alerts are informational and can be delayed by device sampling, battery-saving schedules, Bluetooth or hub synchronization, cloud upload, API caching, Internet availability, and driver polling. This driver is not certified life-safety, medical, industrial-hygiene, smoke, fire, or carbon-monoxide equipment and must not be used as the sole basis for emergency, evacuation, ventilation, or health decisions. The physical Airthings device and Airthings service remain authoritative for supplied measurements; the dealer must verify units, timestamps, update schedules, stale-data settings, and customer notification expectations.

Third-Party Driver Notice and Disclaimer

This driver is independently developed by Buttonwood Technologies, LLC and is not developed, endorsed, supported, or certified by the manufacturers or service providers with which it interoperates, unless expressly stated otherwise. The driver is provided “AS IS” and “WITH ALL FAULTS,” without warranties of any kind, express or implied, including warranties of merchantability, fitness for a particular purpose, and noninfringement. To the maximum extent permitted by applicable law, Buttonwood Technologies, LLC shall not be liable for indirect, incidental, special, consequential, exemplary, or punitive damages, loss of data, loss of use, service interruption, or lost profits arising from installation or use of the driver. Nothing in this notice excludes or limits liability that cannot lawfully be excluded or limited.