Support

Awair Element Local API Feature

Article Summary

This article provides an overview of the Awair Local API feature.

Article Overview

What is the Local API?

The Local API feature allows you to review real-time sensor readings without the need for Wi-Fi. Once activated, your Awair device has the ability to host data on a server that lives on the device. It is like a miniature website with webpages that you can view in your browser (or use software to programmatically retrieve data), but only while you are connected to the same Local Area Network (LAN). The LAN exists behind your router’s firewall, which protects your network from the Wide Area Network (WAN), so this server is secure behind your firewall unless you specifically make it accessible to the internet. The Local API is a miniature website, which serves data from the Awair sensors. This acts as a Cloud API, but all locally (LAN) and on-device instead of requiring an internet (or WAN) connection.

Which Awair products are compatible with the Local API?

Awair 2nd Edition and Awair Element are currently in Beta and can be enabled via the Awair Home app. Other Awair devices, such as Awair 1st Edition, Glow, and Glow C are not supported.

Some Awair devices come with the Local API enabled by default, such as the Enterprise line of products (Awair Omni and Surface / In-Wall Mount).

How do I use the Local API?

To enable the Local API feature use the Awair Home app.

1. Tap Awair+ tab in the lower right-hand corner of the Awair Home App

2. Tap "Awair APIs Beta" in the Awair+ menu

3. Tap "Local API" in the Awair APIs menu

4. Tap "Enable Local API" to enable the feature for your Awair device

5. After you have enabled the Local Sensors feature, look up the device IP address in your router's connected device list either by MAC or hostname. You can find the MAC on the back of your device and the hostname is AWAIR-ELEM- + the last 6 characters of the MAC

IMG_0105.jpg

The easiest way to access and review data through the Local API feature is to find the webpage (see: Discovering your Awair device on the LAN below) and load it into your browser.

For developers and more advanced users, you can use popular technologies such as Python and JavaScript to fetch data and use it in custom programs; or platforms such as Homebridge, Home Assistant, and OpenHAB to use the data in a home automation system.

Please note, remotely troubleshooting is not possible at this time, especially due to the fact that the Local API operates securely behind the network firewall.

If at any time the Local API appears to be disabled, you can use the Device Settings page (shown in Figure 1) to send the "enable" command again to re-enable. There should be no adverse effect of sending the command while it is running.

Discovering your Awair device on the LAN

There are a number of methods and tools that you can use to discover the IP address of your Awair device on your LAN. The IP address usually takes the form of one of these sets of numbers, but can be any group of 4 numbers (0-255) separated by periods "." (e.g. 10.0.1.1, 192.168.1.1, ###.###.###.###)

Terminology

Term

Description

MAC address

A unique identifier is given to each networking interface on a wired or wireless network. 12-character hexadecimal number (A-F & 0-9) on the back of your Awair device that begins with "70886B..."

hostname

A friendly name for identifying a device on a wired or wireless network.

e.g. "AWAIR-ELEM-56CD78"

note: only letters, numbers, and hyphens are in the hostname

DHCP

Dynamic Host Configuration Protocol, which is used by your router to assign IP addresses.

Methods

mDNS

This method allows you to discover and connect to your Awair device directly without going into your router settings. If you are on the same network as your Awair device, you can combine hostname + .local to form a URL (e.g. http://awair-elem-56cd78.local) that you can open in a web browser to view the Local API page hosted on your device.

DHCP Assignments

Most routers have a web portal where you can manage settings for your network. There may be a tab or page with DHCP Assignments, and an Awair device’s IP address will appear next to or near its MAC address.

Hostname

In the same router web portal, you may be able to identify the Awair device and its IP address by the device’s hostname (see: hostname under Terminology)

LAN Scanning

Another way to discover the IP address of the Awair device is to download an app for your computer or mobile phone such as LanScan or Fing. After scanning, you can use either method above (MAC or hostname lookup).

Others

There may be other methods and tools available, or you may opt to contact an IT professional for assistance.

DHCP Reservation

It is recommended that you assign a DHCP reservation to your Awair device on the LAN so that it’s IP address does not change sporadically and need to discover the new IP address all over again. However, if you are using mDNS, then this step is not necessary.

The Local API pages

The Local API is organized into a set of webpages or endpoints, which look something like a tree:

2nd Edition, Element - current

/ (root)
   ├─ air-data/
   │  └─ latest
   └─ settings/
      └─ config/
         └─ data

"root"

The "root" page is like the homepage of a website on the internet. This page is hosted on Awair device, so it may not have a fancy URL in the Search Bar of your browser window (see: Discovering your Awair device on the LAN).

This homepage lists a few other pages ( "endpoints") available on your Awair device with a short description and any instructions on how to use special features available on each page.

# Local API

Latest air-data sample:

/air-data/latest
issue a GET request / refresh this page to retrieve the latest air-data samples and the UTC timestamp (ISO8610 formatted) on the internal clock, or supply a timestamp as an optional query parameter (e.g. "?current_time=1970-09-23T17:12:19.630Z")

Device settings:

/settings/data
issue a GET request to retrieve device configuration data

Air Data

The "/air-data/" path is where you will find the sensor values. Currently, the only endpoint provided is "/latest".

Latest

The "/latest" endpoint provides the "raw" sensor values. Values are updated by the Awair device every 10 seconds. However, in order to see the latest values (no history), you must refresh the page (or a new GET request in programmatic terminology).

Note: not all information in the example below may be available for all Awair device types.

{"timestamp":"2020-07-16T22:27:39.568Z","score":86,"dew_point":14.15,"temp":23.57,"humid":55.54,"abs_humid":11.76,"co2":965,"co2_est":1077,"co2_est_baseline":36352,"voc":276,"voc_baseline":37226,"voc_h2_raw":25,"voc_ethanol_raw":34,"pm25":2,"pm10_est":3}

Sensor Key Descriptions

key

description

timestamp

The UTC ISO8610 formatted time that the sample was taken based on the device’s internal clock.

score

Awair Score (0-100)

dew_point

The temperature at which water will condense and form into dew (ºC by default - see: Temperature Units)

temp

Dry bulb temperature (ºC by default - see: Temperature Units)

humid

Relative Humidity (%)

abs_humid

Absolute Humidity (g/m³)

co2

Carbon Dioxide (ppm)

co2_est

Estimated Carbon Dioxide (ppm - calculated by the TVOC sensor)
co2_est_baseline

 

A unitless value that represents the baseline from which the TVOC sensor partially derives its estimated (e)CO₂output.

voc

Total Volatile Organic Compounds (ppb)

voc_baseline

A unitless value that represents the baseline from which the TVOC sensor partially derives its TVOC output.

voc_h2_raw

A unitless value that represents the Hydrogen gas signal from which the TVOC sensor partially derives its TVOC output.

voc_ethanol_raw

A unitless value that represents the Ethanol gas signal from which the TVOC sensor partially derives its TVOC output.

pm25

Particulate matter less than 2.5 microns in diameter (µg/m³)

pm10_est

Estimated particulate matter less than 10 microns in diameter (µg/m³ - calculated by the PM2.5 sensor)

Optional Query Parameters

Current Time

The Awair device has a sense of time internally and checks-in with the Awair timeserver every hour if connected to the internet. In the case that the device has lost its sense of time, whether due to being blocked behind a firewall or some error, then you can optionally supply a Query Parameter in your request or by appending a special string to the end of the URL. The endpoint will then report back a timestamp relative to the time supplied in the Query Parameter for when the sample was taken.

For example:

?current_time=1970-09-23T17:12:19.630Z
Temperature Units

(Coming soon)

For example:

?temp_unit=f

Settings

Configuration

Currently, no settings are available on the on-device server, but the Display Mode, Brightness, etc. can be managed through the Awair Cloud APIs and mobile apps when the device is connected to the internet.

Data

Device Configuration information is available at the ”/settings/config/data” endpoint, which lists out several attributes in a JSON structure.

Note: not all information in the example below may be available for all Awair device types.

{"device_uuid":"awair-element_1","wifi_mac":"70:88:6B:00:00:00","ssid":"Your_AP_Name_Here","ip":"192.168.1.2","netmask":"255.255.255.0","gateway":"192.168.1.1","fw_version":"1.1.4","timezone":"America/Los_Angeles","display":"score","led":{"mode":"sleep","brightness":179},"voc_feature_set":"32"}

 

Have more questions? Submit a request