Integrate Airthings with Niagara 4
This document describes how to integrate Airthings' API into Niagara 4 and collect data from Airthings sensors. The Niagara Framework is a building automation system allowing for integration and control of the technical systems in your building.
Getting started
To start with the integration you will need the following:
- Airthings for Business account and at least one sensor in your account
- An instance of Niagara 4 running on a JACE or a server
- One of the following drivers for your Niagara 4 instance:
Make sure you have all of your devices and software updated to the most recent version before starting with the integration.
Active Framework REST Network
To use the Active Framework REST Network, make sure you have a valid license for the driver on your Niagara 4 instance. You will have to set up an API client in the Airthings Dashboard to access the data, so lets start with that.
Airthings Dashboard Client Setup
Log in to your user account at dashboard.airthings.com and navigate to Integrations. Click on API and then New API client.
Name your API client and add a description if you’d like. Check the “Confidential” box and select “Client credentials” as flow type.
Make sure your API client is enabled and remember to save the client before continuing.
Niagara 4 setup
After a license for Active Framework REST Network is acquired, follow their instructions for downloading and installing the driver.
Adding the REST Network
With the driver installed to the host, add the RestNetwork driver to the station and enter the following settings in the HTTP config:
- hostname: ext-api.airthings.com
- protocol: Https
- method: Get
Creating authorization function
In order to authorize the communication, a valid access token must be provided with every request, so in order to obtain this we will add a device for this purpose.
After the device (Auth) has been added, you will have to make some overriding properties to it’s Http Config because of the endpoint being different then the one used to get data from devices. Right click on the Http Config, select Actions and “Add Overriding Property” to add the following properties:
- hostname: accounts-api.airthings.com
- query: /v1/token
- method: Post
- body: {"grant_type":"client_credentials","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}
Replace YOUR_CLIENT_ID with the client ID provided in the Airthings Dashboard client setup and replace YOUR_CLIENT_SECRET with the secret provided in the Airthings Dashboard client setup.
The token will be stored under “Artifacts” in this device, and it will be used for authenticating the sensor-data requests. Create an artifact here and name it “Airthings_Auth”.
Collecting data from a sensor
In order to get data from a sensor, a new device must be added to the REST Network. Add the following information in the header under Http Config in the new device:
- Name: Authorization
- Value: Bearer ${Airthings_Auth.access_token}
This will make the requests include the token obtained by the Auth-device and getting permission to get sensor data.
Add a query overriding property in the Http Config with the endpoint “/v1/devices/2930013487/latest-samples” where 2930013487 is a sensor S/N that should be replaced with the sensor you would like to collect data from. This sensor has to be registered in the organization where the API client was created in order to get permission to collect data from it.
Finally, add points for the different sensor values. Configure the selector for each sensor according to the JSON-format in the API-documentation to separate the data to different Niagara objects.
