Awair 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-R2/ELEM-/OMNI-/MINT- + the last 6 characters of the MAC

IMG_0160.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-OMNI-12AB34", "AWAIR-MINT-56CD78", "AWAIR-R2-12AB34", or "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.

 

mDNS

2nd Edition and Element (Coming soon: Omni + In-Wall Mount)

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.

 

SNMP

(Coming soon: Omni + In-Wall Mount)

MiB File

 

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; Mint, Omni -  v1.3.0 and below

 

/ (root)

   ├─ air-data/

   │    └─ latest

   └─ settings/

            └─ config/

                     └─ data

 

Mint, Omni - v1.3.1; Surface Mount  - v1.0.1 and above

 

/ (root)

   ├─ air-data/

   │    └─ latest

   └─ settings/

            └─  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


BACnet settings:


/settings/bacnet/ip

configure BACnet settings applicable in Mode 3

 

Have more questions? Submit a request