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.

sensor:
...
# AirThings Wave Plus
- name: Radon 1day Avg
  state_topic: 'airthings/ID/radon_1day_avg'
  unit_of_measurement: 'Bq/m3'
  force_update: true
- name: Radon Long Term Avg
  state_topic: 'airthings/ID/radon_longterm_avg'
  unit_of_measurement: 'Bq/m3'
  force_update: true
- name: Indoor CO2
  state_topic: 'airthings/ID/co2'
  unit_of_measurement: 'ppm'
  force_update: true
- name: Indoor VOC
  state_topic: 'airthings/ID/voc'
  unit_of_measurement: 'ppm'
  force_update: true

- name: Wave Battery
  device_class: 'battery'
  state_topic: 'airthings/ID/battery'
  force_update: true

- name: Wave Temperature
  state_topic: 'airthings/ID/temperature'
  device_class: 'temperature'
  unit_of_measurement: '°C'
  force_update: true
  # Convert to float, but ignore non numeric values (e.g. 'unknown' when 
  # Home Assistant is restarted
  value_template: '{{ float(value) if is_number(value) }}'
- name: Wave Humidity
  state_topic: 'airthings/ID/humidity'
  device_class: 'humidity'
  unit_of_measurement: '%'
  force_update: true

- name: Wave Pressure
  state_topic: 'airthings/ID/rel_atm_pressure'
  device_class: 'pressure'
  force_update: true
  unit_of_measurement: 'hPa'
  # Adjust raw pressure value per nearest METAR station
  # See https://www.youtube.com/watch?v=Wq-Kb7D8eQ4
  value_template: '{{ int(value) + 44 if is_number(value) }}'

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.