Connect Airthings devices to Evolo using MQTT

Before You Begin

To get started, you’ll need the following from Airthings:

• Access to an Airthings for Business account with at least one device online

• Airthings Account ID: found in the Airthings Dashboard under Integrations.

• Airthings MQTT Client ID: found when you create an MQTT client in the Airthings Dashboard.

• Airthings Location ID: You can find this in the URL after opening the building in the Airthings Dashboard.
  

  

• Airthings Device ID: found in the URL when you open the device in the Airthings Dashboard.
  

  

1. Create an MQTT client in the Airthings Dashboard

For the Evolo Gateway to connect to Airthings, you must first Create an MQTT client in the Airthings Dashboard. This will provide you with the login credentials and certificates you’ll need for the rest of the setup.

2. Add the Airthings MQTT broker as a device

Once the MQTT client has been created and the certificates have been downloaded, add a new device in Evolo.

Add a new device in Evolo and use mqtt.airthings.com as the hostname.

3. Add an MQTT interface

Then create a new interface with these settings:

Advanced interface settings

Under Advanced Settings, enter the topics that Evolo should subscribe to, and upload the certificates from Airthings.

Click Create once everything is filled in.

4. Add data points that read from MQTT

Once the interface has been created, you can add data points for the values you want to read from Airthings.

In the example interface, we see that Evolo subscribes to all topics under:
95c179d9-1edd-471b-b55b-44b3e76802a8/f3b1b49d-8d3d-4497-b0d4-68ca8a5c9f69/#

To retrieve values, add the Device ID and end with /samples for the device you want to read from.

Example of a complete topic

95c179d9-1edd-471b-b55b-44b3e76802a8/f3b1b49d-8d3d-4497-b0d4-68ca8a5c9f69/devices/123456789/samples

Example of data from Airthings

The payload from Airthings may contain values like these:

{
"serialNumber": "2930046980",
"sampleRecorded": "2023-07-04T11:25:31",
"co2": 456, // carbon dioxide (ppm)
"humidity": 43, // relative humidity (%)
"light": 36, // relative light (%)
"lux": 114, // light (lux)
"radonShortTermAvg": 13,
"temp": 24.33, // temperature (°C)
"voc": 71, // volatile organic compounds (ppb)
"pressure": 99166, // pressure (hPa)
"pm1": 10, // particulate matter 1 µm (µg/m³)
"pm25": 10, // particulate matter 2.5 µm (µg/m³)
"soundLevel": 55, // sound level (dBA)
"pressureDifference": null,
"pm10": null,
}

Test the data point

Once you’ve entered the expression for the value you want to read, you can test the setup using “Read Data Point.” Then click “Create” to finish.

Troubleshooting

I can’t read data from Airthings

Probable cause:
The MQTT client isn’t configured correctly, the topic points to the wrong building or device, or the certificates haven’t been uploaded correctly.

Solution:
Check the Account ID, MQTT Client ID, Location ID, and Device ID. Also verify that the topic is spelled correctly and that TLS and certificate validation are enabled.

The data point is reading the wrong value

Probable cause:
The expression in the JavaScript field refers to the wrong parameter in the message.

Solution:
Check the payload from Airthings and confirm that you are reading the correct field, such as temp, co2, or humidity. Then test using “Read Data Point.”