AirThings Wave Plus For Radon With MQTT and Home Assistant

The AirThings Wave Plus is a multi-sensor that can show CO2, Volatile Organic Compounds, Radon, Temperature, Humidity, and Pressure. The sensor is meant to be used through a phone app.

However, since it uses Bluetooth Low Energy (BLE), a phone app this is not the only way to use this sensor.

What makes this sensor unique for the DIY crowd is that, as far as radon sensors go, it is the only radon sensor that can be connected to home automation systems without having to signup for an account, and have your data published to a web service.

This article describes how to do this via an MQTT server. You can then connect it to Home Assistant or other home automation systems if you already have MQTT. If you use InfluxDB with Home Assistant, you can use Grafana to see the fluctuations of radon, CO2 and other values over time.

Note that as of December 2022, Home Assistant has native support for the Wave Plus. What makes the MQTT route described in this article better in my case is that it allows me flexibility in naming the sensors, and doing some data transformation as well.

My setup uses Ubuntu 20.04 on a Raspberry Pi 4. Other distributions may be slightly different, but the broad idea is the same.

Configure Bluetooth

First we need to configure the default user to allow access to Bluetooth.

Since I am using Ubuntu, the default user is called ubuntu. This may be different depending on the distribution you are using on your Raspberry Pi.

sudo usermod -a -G bluetooth ubuntu
sudo service dbus restart

Download or Clone The Software

git clone https://github.com/mjmccans/airthings-mqtt-ha.git

Or download the .zip file and extract it, like this

wget https://github.com/mjmccans/airthings-mqtt-ha/archive/refs/heads/master.zip 
unzip master.zip
mv airthings-mqtt-ha-master airthings-mqtt-ha

Install Required Python Packages

By looking at the requirements.txt, we find that we need two Python packages, paho-mqtt and bleak.

These can be installed using pip3.

So first install pip3 like this:

sudo apt install python3-pip

Then install the two packages:

pip3 install --user paho-mqtt
pip3 install --user bleak

Generate And Edit The Configuration

Then change to the directory that has the program, and execute it to generate a configuration file:

cd airthings-mqtt-ha/src
./airthings-mqtt-ha.py

View the generated options.json. The ID value should have your real BLE MAC address.

{
  "devices" : [
    { 
      "mac": "ID",
      "name": "Main"
    }
  ],
  "refresh_interval": 120,
  "retry_count": 10,
  "retry_wait": 3,
  "log_level": "WARNING",
  "mqtt_discovery": false,
  "mqtt_retain": false,
  "mqtt_host": "localhost",
  "mqtt_username": "",
  "mqtt_password": ""
}

The important parts are:

• referesh_interval: 120 seconds looks like a granular enough value that is also not too frequent.
• log_level: set this to WARNING, otherwise there will be a lot of output from the program.

Also set the MQTT username and password if you have them configured.

Create A Startup Script

Then create a shell script to start the daemon in the correct directory:

#!/bin/sh

# AirThings Wave BLE to MQTT bridge

cd $HOME/airthings-mqtt-ha/src

./airthings-mqtt-ha.py &

Place this in a file called /usr/local/bin/airthings.sh, and make it executable:

chmod +x /usr/local/bin/airthings.sh

The easiest way to start this script when the Raspberry Pi is rebooted, is from cron:

crontab -e

Add these lines, then save the file:

# Start AirThings MQTT
@reboot sleep 15; /usr/local/bin/airthings-mqtt.sh 

Run this script manually to start the daemon:

/usr/local/bin/airthings-mqtt.sh

Test The Device and MQTT

Now you should use an MQTT client to subscribe and view that the sensor is sending data to MQTT.

For example, to use my mqttmon.py, I do this:

/usr/local/bin/mqttmon.py localhost airthings/+/+

You may find other MQTT clients here.

Configure Your MQTT Client

The naming of each value that the sensor sends are like

airthings/ID/value

The ID is the Bluetooth ID in options.json.
The value can be one of the following:

• radon_1day_avg: The average of radon over one day, in Becquerel per cubic meter (Bq/m3)
• radon_longterm_avg: The overall average of radon, in Bq/m3
• co2: CO2 level, in parts per million (ppm)
• voc: volatile organic compounds, in ppm
• battery: Battery level, as a percentage
• temperature: Temperature, in celsius
• humidity: Relative humidity, as a percentage
• rel_atm_pressure: Atmospheric pressure, as hepto Pascals (hPA)
• illuminance: Illumination

If you use Home Assistant, here is the section needed.
Note that I have some transformations, such as converting temperature to a float,
and ignoring non numeric values, and adjusting pressure per METAR.

Most importantly, I have some range checks to make sure sane values are being returned.
The reason for this is that when the battery is changed, all sorts of bad values are sent to
Home Assistant.

sensor:
...
  # AirThings Wave Plus
  - name: Wave Battery
    device_class: 'battery'
    state_topic: 'airthings/60:98:66:aa:bb:cc/battery'
    force_update: true

  - name: Radon 1day Avg
    state_topic: 'airthings/60:98:66:aa:bb:cc/radon_1day_avg'
    unit_of_measurement: 'Bq/m3'
    force_update: true

  - name: Radon Long Term Avg
    state_topic: 'airthings/60:98:66:aa:bb:cc/radon_longterm_avg'
    unit_of_measurement: 'Bq/m3'
    force_update: true

  - name: Indoor CO2
    state_topic: 'airthings/60:98:66:aa:bb:cc/co2'
    unit_of_measurement: 'ppm'
    force_update: true
    value_template: >-
      {%- set v = int(value) -%}
      {% if v >= 0 and v <= 3500 %}
      {{ v }}
      {% endif -%}

  - name: Indoor VOC
    state_topic: 'airthings/60:98:66:aa:bb:cc/voc'
    # Actually, it is ppb, but the wrong value was used in InfluxDB
    unit_of_measurement: 'ppm' 
    force_update: true
    value_template: >-
      {%- set v = int(value) -%}
      {% if v >= 0 and v <= 2000 %}
      {{ v }}
      {% endif -%}

  - name: Wave Temperature
    state_topic: 'airthings/60:98:66:aa:bb:cc/temperature'
    device_class: 'temperature'
    unit_of_measurement: '°C'
    force_update: true
    value_template: >-
      {%- set v = float(value) if is_number(value) -%}
      {% if v <= 50 %}
      {{ v }}
      {% endif -%}

  - name: Wave Humidity
    state_topic: 'airthings/60:98:66:aa:bb:cc/humidity'
    device_class: 'humidity'
    unit_of_measurement: '%'
    force_update: true
    value_template: >-
      {%- set v = int(value) -%}
      {% if v >= 0 and v <= 100 %}
      {{ v }}
      {% endif -%}

  - name: Wave Pressure
    state_topic: 'airthings/60:98:66:aa:bb:cc/rel_atm_pressure'
    device_class: 'pressure'
    force_update: true
    unit_of_measurement: 'hPa'
    # Adjust raw pressure value per METAR, by adding 44
    # See https://www.youtube.com/watch?v=Wq-Kb7D8eQ4
    value_template: >-
      {%- set v = int(value) if is_number(value) -%}
      {% if v >= 800 and v <= 1100 %}
      {{ v + 44 }}
      {% endif -%}

Reboot The Raspberry Pi

Now reboot the Raspberry Pi:

sudo shutdown -r now

And make sure that the airthings-mqtt-ha program is running:

$ ps -ef | grep airthings
ubuntu 306246 1 0 Oct27 ? 00:14:37 /usr/bin/python3 ./airthings-mqtt-ha.py

Then test your MQTT client to see that it is receiving data.