Skip to content

โ˜ข๏ธ Airthings Wave radon detector bridge for single-board computers: a balena and Docker container. ๐Ÿณ

License

Notifications You must be signed in to change notification settings

renemarc/balena-airthingswave

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

21 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

โ˜ข๏ธ
Airthings Wave radon detector bridge
a balena and Docker container ๐Ÿณ

GitHub Release Price AirthingsWave-to-MQTT Version balena.io Code Climate maintainability Maintainer All Contributors PRs Welcome License Tweet

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. ๐ŸŽˆ

Be sure to โญ๏ธ this repo if you find it useful! ๐Ÿ˜ƒ

Radon alpha decay in a diffusion cloud chamber

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! ๐Ÿ˜…

๐Ÿ”

Table of contents ๐Ÿ“‘

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

๐Ÿ”

Prerequisites โœ…

  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 add-on.
  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! ๐Ÿค 

๐Ÿ”

balena ๐Ÿ“ฆ

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!

Preparation ๐Ÿ”

  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! โฌ‡๏ธ

๐Ÿ”

Installation ๐Ÿ’ป

  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. โฌ‡๏ธ

๐Ÿ”

Configuration โš™

Either modify the ./docker/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 ./docker/config.yaml file to add more entries.

Which MAC address to use? Leave that empty for now and proceed to the first run below. โฌ‡๏ธ

First run ๐Ÿƒ

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 can be only one

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 ./docker/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.

Cron job โฒ

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.

Butters awarding himself a sunshine sticker

โ˜€๏ธ Good job! ๐Ÿ˜ƒ

๐Ÿ”

Docker ๐Ÿณ

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.

Containers being moved in a yard

Build and run ๐Ÿ—๏ธ

  1. Fork or clone this project's repository.

  2. Edit the ./docker/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=docker/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=docker/env.list \
  --net=host --cap-add=NET_ADMIN \
  --name=airthingswave $(docker build --quiet .)
Buzz Lightyear saying Containers everywhere!

๐Ÿ”

Alternatives โš›

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

Community projects ๐ŸŒฑ

Official solutions ๐Ÿ‘ฎ

R is for radiophobia: the fear of radiation

๐Ÿ”

Contributors โœจ

Renรฉ-Marc Simard
Renรฉ-Marc Simard

๐Ÿ’ป ๐Ÿ“–
Herb Peyerl
Herb Peyerl

๐Ÿค” ๐Ÿ”Œ
grangemd
grangemd

๐Ÿ›
Robin
Robin

๐Ÿ›

This project follows the all-contributors specification (emoji key available here). Found a bug, want to suggest an idea or share some improvements? Contributions of any kind are welcome! ๐Ÿ˜ƒ

๐Ÿ”

Thanks ๐Ÿ’•

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

Copyright ยฉ 2018, Renรฉ-Marc Simard. Project released under Apache Licence 2.0 with additional notices available here.

๐Ÿ”

Don't forget to โญ๏ธ this repo! ๐Ÿ˜ƒ
Assembled with โค๏ธ in Montrรฉal.

About

โ˜ข๏ธ Airthings Wave radon detector bridge for single-board computers: a balena and Docker container. ๐Ÿณ

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published