This is a fork of https://github.com/Airthings/waveplus-reader to provide users an interface (read_waveplus.py) to read current sensor values from the Airthings Wave Plus devices using a Raspberry Pi 3 Model B over Bluetooth Low Energy (BLE) and export values for Prometheus scraping.

Airthings Wave Plus is a smart IAQ monitor with Radon detection, including sensors for temperature, air pressure, humidity, TVOCs and CO2.

Table of contents

• Airthings Wave Plus Sensor Reader
• Requirements
  • Setup Raspberry Pi
  • Turn on the BLE interface
  • Installing linux and python packages
  • Downloading script
• Usage
  • Printing data to the terminal window
  • Piping data to a text-file
• Sensor data description
• Contribution
• Release notes

The following tables shows a compact overview of dependencies for this project.

List of OS dependencies

List of linux/raspberry dependencies

List of Python dependencies

The first step is to setup the Raspberry Pi with Raspbian. An installation guide for Raspbian can be found on the Raspberry Pi website. In short: download the Raspbian image and write it to a micro SD card.

To continue, you need access to the Raspberry Pi using either a monitor and keyboard, or by connecting through WiFi or ethernet from another computer. The latter option does not require an external screen or keyboard and is called “headless” setup. To access a headless setup, you must first activate SSH on the Pi. This can be done by creating a file named ssh in the boot partition of the SD card. Connect to the Pi using SSH from a command line interface (terminal):

$ ssh pi@raspberrypi.local

The default password for the “pi” user is “raspberry”.

In the terminal window on your Raspberry Pi:

pi@raspberrypi:~$ bluetoothctl
[bluetooth]# power on
[bluetooth]# show

After issuing the command show, a list of bluetooth settings will be printed to the Raspberry Pi terminal window. Look for Powered: yes.

Note: The read_waveplus.py script is only compatible with Python2.7.

The next step is to install the bluepy Python library for talking to the BLE stack. For the current released version for Python 3.9:

pi@raspberrypi:~$ sudo apt-get install python3-pip libglib2.0-dev
pi@raspberrypi:~$ sudo pip2 install bluepy==1.3.0

Make sure your Raspberry Pi has git installed

pi@raspberrypi:~$ git --version

or install git to be able to clone this repo.

pi@raspberrypi:~$ sudo apt-get install git

Additionally, the read_waveplus.py script depends on the tableprint module to print nicely formated sensor data to the Raspberry Pi terminal at run-time.

pi@raspberrypi:~$ sudo pip install tableprint==0.9.1 prometheus-client

Note: The read_waveplus.py script has been tested with bluepy==1.230 and tableprint==0.9.1. You may download the latest versions at your own risk.

Downloading using git:

pi@raspberrypi:~$ sudo git clone https://github.com/sweeneyb/waveplus-reader.git

Downloading using wget:

pi@raspberrypi:~$ wget https://raw.githubusercontent.com/sweeneyb/waveplus-reader/master/read_waveplus.py

To read the sensor data from the Airthings Wave Plus using the read_waveplus.py script, you need the 10-digit serial number of the device. This can be found under the magnetic backplate of your Airthings Wave Plus.

If your device is paired and connected to e.g. a phone, you may need to turn off bluetooth on your phone while using this script.

cd into the directory where the read_waveplus.py script is located if you cloned the repo.

The general format for calling the read_waveplus.py script is as follows:

read_waveplus.py SN SAMPLE-PERIOD [pipe > yourfilename.txt]

where the input arguments are:

Note on choosing a sample period: Except for the radon measurements, the Wave Plus updates its current sensor values once every 5 minutes. Radon measurements are updated once every hour.

By default, the read_waveplus.py script will print the current sensor values to the Rasberry Pi terminal. Run the Python script in the following way:

pi@raspberrypi:~/waveplus-reader $ sudo python2 read_waveplus.py SN SAMPLE-PERIOD

where you change SN with the 10-digit serial number, and change SAMPLE-PERIOD to a numerical value of your choice.

After a short delay, the script will print the current sensor values to the Raspberry Pi terminal window. Exit the script using Ctrl+C.

If you want to pipe the results to a text-file, you can run the script in the following way:

pi@raspberrypi:~/waveplus-reader $ sudo python2 read_waveplus.py SN SAMPLE-PERIOD pipe > yourfilename.txt

where you change SN with the 10-digit serial number, and change SAMPLE-PERIOD to a numerical value of your choice.

Exit the script using Ctrl+C.

Prometheus data is exported as a gauge for all documented sensors below. It is exposed via a web server on port 8080. Among the other standard python metrics you can safely ignore, it should look something like

# HELP humidity Humidity measured in %rH
# TYPE humidity gauge
humidity 44.0
# HELP radon_short_term Short term radon levels in Bq/m3
# TYPE radon_short_term gauge
radon_short_term 54.0
# HELP radon_long_term Long term radon levels in Bq/m3
# TYPE radon_long_term gauge
radon_long_term 106.0
# HELP temperature Temp in Celcius
# TYPE temperature gauge
temperature 18.82
# HELP pressure Atmospheric pressure in hPa
# TYPE pressure gauge
pressure 983.88
# HELP CO2 Carbon Dioxide levels in parts per million
# TYPE CO2 gauge
CO2 473.0
# HELP voc Volatile organic compound levels in parts per billion
# TYPE voc gauge
voc 91.0

Let us know how it went! If you want contribute, you can do so by posting issues or suggest enhancement here, or you can open a pull request for review here.

Release dated 04-Dec-2020

• [bug] Fixed missing little-endian specifier.

Release dated 14-Jan-2019

• [bug] Fixed issue (#4)

Release dated 14-Dec-2018

• Added SAMPLE-PERIOD as an input argument.

Initial release 12-Dec-2018