Turn a single-board computer (Raspberry Pi) into a plug-in appliance to bridge your Bluetooth Airthings Wave radon detector to an MQTT broker.

Useful if your radon detector is located too far from your home automation hub, or if you need to use your hub's Bluetooth antenna for something else.

This project creates Docker/balena images based on Alpine Linux that weigh less than 120 MiB on a Raspberry Pi. ⚖️

Alpha decay. Inside your lungs. 😱

Why use the balena ecosystem? All the goodness of Docker, plus security handling, IoT hardware optimized images, read-only rootFS, a build pipeline, a device management interface, and continuous deployment, for free (well, first 10 devices on balenaCloud …or unlimited if you run your own OpenBalena platform).

Of course you could do all of this on your own, but do you really want to micro-manage, keep secure, always perform clean shutdowns, and generally baby something that should really be just plug-in, set-and-forget hardware? 🤔 I surely don't! 😅

Radon-220 decays into Polonium-216 then Lead-212.

🔝

1. Prerequisites
2. balena
   1. Preparation
   2. Installation
   3. Configuration
3. Docker
4. Alternatives
5. Contributing
6. Thanks

🔝

1. At least one Airthings Wave radon detector.
2. Your favourite Internet of Things (IoT) device that offers both Bluetooth Low Energy (BLE) and network access, like the inexpensive Raspberry Pi Zero W.
3. Working access to an MQTT broker, either a public one, your own hosted Mosquitto instance or the Home Assistant addon.
4. (Recommended) A free-tier account on balenaCloud along with a properly set SSH public key into your account.
5. (Recommended) The balena command-line tools. Do read up on their friendly development guidelines.

Let's play! 🤠

🔝

Follow these simple steps to quickly get your app running on a dedicated device using balenaCloud. If you want more control, try the Docker solution instead.

For reference, the balena framework will build the container using the ./Dockerfile.template which employs placeholders so that the correct system architecture is picked for you during installation. Easy!

1. Create a new application on balenaCloud dashboard and select the appropriate IoT hardware.

2. Add a new device to your app. Start with development mode for local testing, or go directly for production mode if you know what you're doing.

3. (Optionally) Configure the downloaded image to give your device a custom hostname instead of the generic balena:

   sudo balena local configure /path/to/downloaded/image.img

4. Burn the image to a disk and boot your IoT device.

Your hardware is ready; it's now time to install the project! ⬇️

🔝

1. Git clone this project's repository:

   git clone git@github.com:renemarc/balena-airthingswave.git

2. Add your balena application as a secondary remote to the cloned repo:

   git remote add balena <username>@git.balena-cloud.com:<username>/<appname>.git

3. Push the code to balenaCloud and wait for it to build and provision your device:

   git push balena master

Great! You are now ready to configure the project. ⬇️

🔝

Either modify the ./config.yaml file with your MQTT and Airthings Wave(s) information, or ideally declare environment variables that will then be automatically replaced in the said configuration file.

I strongly suggest simply using environment variables, either at the whole fleet level, at the single device level, or at a mix of both. Configuration is easier to update this way and if you live in a McMansion you can provision multiple devices with the same codebase. Yay!

MQTT_BROKER   192.168.1.1
MQTT_PORT     1883
MQTT_USERNAME user
MQTT_PASSWORD super-secret-password

WAVES_NAME_1  radon/basement
WAVES_ADDR_1  cc:78:ab:00:00:0a
WAVES_NAME_2  radon/bedroom
WAVES_ADDR_2  cc:78:ab:00:00:0b
WAVES_NAME_3  radon/garage
WAVES_ADDR_3  cc:78:ab:00:00:0c

The Waves names are used as MQTT topic prefixes, so name them however you prefer. If you have more than one Wave that you want to query, do modify the ./config.yaml file to add more entries.

Which MAC address to use? Leave that empty for now and proceed to the first run below. ⬇️

There can be only one controller paired at a time, so do make sure that your Airthings Wave is "forgotten" from your mobile device by opening Airthings' mobile app and unpairing from there.

There should have only been one Highlander movie too…

SSH into your device (only if development mode was selected earlier) or use the balenaCloud app dashboard terminal to find your Wave's MAC address by issuing this command:

python /usr/src/app/find_wave.py

Press Ctrl+C when scanning seems to be done. Take note of the MAC address for the Wave that you want to use, and either modify ./config.yaml or ideally create sets of environment variables for each Wave that you want to use.

Once configured, either git push your changes or restart the device.

If your above parameters are correct, you should be receiving new MQTT messages every hour. Keep an eye on the streaming device logs in the balenaCloud dashboard and use an MQTT client to debug incoming messages.

Want to receive quicker updates? Modify the ./Dockerfile.template and change the CRON_PERIOD argument from hourly to 15min or to something else.

☀️ Good job! 😃

🔝

Want more control or wish to run this container on some multi-purpose shared hardware? Here are some useful steps.

Compared to the balena solution, here the regular ./Dockerfile is used.

1. Fork or clone this project's repository.

2. Edit the ./env.list file to setup your environment variables. See configuration above ⬆️ for details.

3. Build the image:

   For a Raspberry Pi or Zero:

   docker build --tag=airthingswave .

   For everything else, specify the DEVICE_NAME argument with the relevant lowercase machine name from balena base images. For a Raspberry Pi 3 for instance:

   docker build --build-arg DEVICE_NAME=raspberrypi3 \
     --tag=airthingswave .

4. Run the project as an auto-starting container:

   docker run --detach --restart=unless-stopped \
     --env-file=env.list \
     --net=host --cap-add=NET_ADMIN \
     --name=airthingswave \
     airthingswave

   --net=host gives the container access to the host's network devices, including Bluetooth.
   --cap-add=NET_ADMIN gives the container network privileges.

5. Perform the steps outlined in first run above ⬆️ using while inside the container:

   docker exec -it airthingswave bash

6. Should you wish to change the cron job frequency, you can pass the CRON_PERIOD (default: hourly) argument while first building the image:

   docker build --build-arg CRON_PERIOD=15min \
     --tag=airthingswave .

Once ready and working, you can alternatively use this example one-liner to build and run the project:

docker run --detach --restart=unless-stopped \
  --env-file=env.list \
  --net=host --cap-add=NET_ADMIN \
  --name=airthingswave $(docker build --quiet .)

🔝

Other options exist, should you wish to try something else:

• The official Airthings hub: Commercial solution, plug-n-play, supported.
• airthingswave-mqtt by @hpeyerl: The AirthingsWave-to-MQTT module used in this project, also vailable on the Python Package Index.
• Radonwave by @marcelm: Python script that outputs a reading of a given Airthings Wave.
• read_wave.py by Airthings: A simple Python script that demonstrates how to read an Airthings Wave data.

🔝

Want to suggest some Docker improvements? Got some fringe hardware that you used to run this balena/Docker container on and had to tweak some config for it to work? Fork this repo and open a pull request so that all can benefit! 😃

🔝

This Docker container is based on airthingswave-mqtt by Herb Peyerl (@hpeyerl) and the discovery code by Airthings.

🔝

Don't forget to ⭐️ this repo! 😃
_{Assembled with ❤️ in Montréal.}