Skip to content

Commit

Permalink
Uploaded read_wave2.py. Aligned script implementations. Added support…
Browse files Browse the repository at this point in the history 
… for Python3. Updated README.
  • Loading branch information
orjangje committed Feb 10, 2020
1 parent a8986b4 commit 1ffada3
Show file tree
Hide file tree
Showing 3 changed files with 372 additions and 302 deletions.
193 changes: 90 additions & 103 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,53 @@
# Airthings Wave Sensor Reader

This is a project to provide users an interface (```read_wave.py```) to read current sensor values from the
[Airthings Wave](https://airthings.com/wave/) devices using a Raspberry Pi 3 Model B over Bluetooth Low Energy (BLE).

Airthings Wave is a smart Radon detector, including sensors for temperature and humidity.
Airthings Wave is a smart Radon detector, including sensors for temperature and humidity measurements.
Additionally, you can simply wave in front of the device to get a visual indication of your radon levels.

This is a project to provide users a starting point (```read_wave.py``` and ```read_wave2.py```) to read current sensor
values from the 1st and 2nd generation [Airthings Wave](https://airthings.com/wave/) devices using a Raspberry Pi 3
Model B over Bluetooth Low Energy (BLE).

**Table of contents**

* [Requirements](#requirements)
* [Setup Raspberry Pi](#setup-Raspberry-pi)
* [Turn on the BLE interface](#turn-on-the-ble-interface)
* [Installing linux and python packages](#installing-linux-and-python-packages)
* [Downloading script](#downloading-script)
* [Usage](#usage)
* [Printing data to the terminal window](#printing-data-to-the-terminal-window)
* [Piping data to a text-file](#piping-data-to-a-text-file)
* [Sensor data description](#sensor-data-description)
* [Contribution](#contribution)
* [Release notes](#release-notes)
- [Airthings Wave Sensor Reader](#airthings-wave-sensor-reader)
- [Requirements](#requirements)
- [Setup Raspberry Pi](#setup-raspberry-pi)
- [Turn on the BLE interface](#turn-on-the-ble-interface)
- [Installing linux and python packages](#installing-linux-and-python-packages)
- [Downloading script](#downloading-script)
- [Usage](#usage)
- [Sensor data description](#sensor-data-description)
- [Contribution](#contribution)
- [Release notes](#release-notes)

# Requirements

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

**List of OS dependencies**

| OS | model/version | Comments |
|-------------|-------------|-------------|
| Raspbian | Raspberry Pi 3 Model B | Used in this project.
| Linux | x86 Debian | Should work according to [bluepy](https://github.com/IanHarvey/bluepy)
| OS | model/version | Comments |
|-------------|------------------------|-----------------------|
| Raspbian | Raspberry Pi 3 Model B | Used in this project. |
| Linux | x86 Debian | Should work according to [bluepy](https://github.com/IanHarvey/bluepy) |


**List of linux/raspberry dependencies**

| package | version | Comments |
|-------------|-------------|-------------|
| python | 2.7 | Tested with python 2.7.13
| python-pip | | pip for python2.7
| git | | To download this project
| libglib2.0-dev | | For bluepy module
| package | version | Comments |
|----------------|-------------|-------------------------------------|
| python | 2.7 or 3 | Tested with python 2.7.13 and 3.7.3 |
| python-pip | | pip for python2.7 |
| python3-pip | | pip3 for python3 |
| git | | To download this project |
| libglib2.0-dev | | For bluepy module |

**List of third-party Python dependencies**

**List of Python dependencies**
| module | version |
|-------------|-------------|
| bluepy | 1.3.0 |

| module | version | Comments |
|-------------|-------------|-------------|
| bluepy | 1.2.0 | Newer versions have not been tested.
| tableprint | 0.8.0 | Newer versions have not been tested.

## Setup Raspberry Pi

Expand All @@ -64,7 +66,7 @@ interface (terminal):
$ ssh [email protected]
```

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

## Turn on the BLE interface

Expand All @@ -74,44 +76,33 @@ In the terminal window on your Raspberry Pi:
pi@raspberrypi:~$ bluetoothctl
[bluetooth]# power on
[bluetooth]# show
[bluetooth]# exit
```

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

## Installing linux and python packages

> **Note:** The ```read_wave.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 2.7:

```
pi@raspberrypi:~$ sudo apt-get install python-pip libglib2.0-dev
pi@raspberrypi:~$ sudo pip2 install bluepy==1.2.0
```

Make sure your Raspberry Pi has git installed

```
pi@raspberrypi:~$ git --version
```

or install git to be able to clone this repo.
Raspbian images usually comes with Python (2 and/or 3) pre-installed.

```
pi@raspberrypi:~$ sudo apt-get install git
pi@raspberrypi:~$ python2 --version
pi@raspberrypi:~$ python3 --version
```

Additionally, the ```read_wave.py``` script depends on the ```tableprint``` module
to print nicely formated sensor data to the Raspberry Pi terminal at run-time.
Install dependencies:

```
pi@raspberrypi:~$ sudo pip2 install tableprint==0.8.0
```bash
pi@raspberrypi:~$ sudo apt-get update && sudo apt-get install libglib2.0-dev git
# For Python 2
pi@raspberrypi:~$ sudo apt-get install python-pip
pi@raspberrypi:~$ sudo pip2 install bluepy==1.3.0
# For python 3
pi@raspberrypi:~$ sudo apt-get install python3-pip
pi@raspberrypi:~$ sudo pip3 install bluepy==1.3.0
```

> **Note:** The ```read_wave.py``` script has been tested with bluepy==1.2.0 and tableprint==0.8.0. You may download the latest versions at your own risk.
## Downloading script

Downloading using git:
Expand All @@ -128,78 +119,74 @@ pi@raspberrypi:~$ wget https://raw.githubusercontent.com/Airthings/wave-reader/m

# Usage

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

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_wave.py``` script is located if you cloned the repo.

The general format for calling the ```read_wave.py``` script is as follows:
The general format for calling the scripts is as follows:

```
read_wave.py SN SAMPLE-PERIOD [pipe > yourfilename.txt]
```bash
# For 1st Gen Wave
sudo python read_wave.py SERIAL_NUMBER SAMPLE_PERIOD [> somefile.txt]
# For 2nd Gen Wave
sudo python read_wave2.py SERIAL_NUMBER SAMPLE_PERIOD [> somefile.txt]
```

where the input arguments are:
After a short delay, the script will print the current sensor values to the
Raspberry Pi terminal window. Optionally, you may pipe the readings to a
text-file using ```> somefile.txt```. Exit the script using ```Ctrl+C```.

| input argument | example | Comments |
|-------------|-------------|-------------|
| SN | 0123456789 | 10-digit number. Can be found under the magnetic backplate of your Airthings Wave Plus.
| SAMPLE-PERIOD | 60 | Read sensor values every 60 seconds. Must be larger than zero.
| pipe | pipe > yourfilename.txt | Optional. Since tableprint is incompatible with piping, we use a third optional input argument "pipe".

> **Note on choosing a sample period:**
Temperature and humidity are updated every time we read the wave.
Radon measurements are updated once every hour.
| Positional input arguments | Type | Description |
|----------------------------|------|--------------|
| SERIAL_NUMBER | Integer | 10-digit number found under the magnetic backplate of your Airthings product.
| SAMPLE_PERIOD | Integer | Time in seconds between reading the current sensor values (excluding the overhead of connecting to target).

## Printing data to the terminal window
| Device | Serial number | Script to use |
|-----------------|-----------------|-----------------------|
| Wave 1st Gen | 2900xxxxxx | read_wave.py |
| Wave 2nd Gen | 2950xxxxxx | read_wave2.py |

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

Example output of a 1st Gen Wave device:
```
pi@raspberrypi:~/wave-reader $ sudo python2 read_waveplus.py SN SAMPLE-PERIOD
Timestamp: 2020-02-10 10:14:32, Humidity: 21.5 %rH, Temperature: 22.8 *C, Radon STA: 36 Bq/m3, Radon LTA: 27 Bq/m3
Timestamp: 2020-02-10 10:20:48, Humidity: 21.5 %rH, Temperature: 22.8 *C, Radon STA: 36 Bq/m3, Radon LTA: 27 Bq/m3
Timestamp: 2020-02-10 10:25:58, Humidity: 21.5 %rH, Temperature: 22.9 *C, Radon STA: 36 Bq/m3, Radon LTA: 27 Bq/m3
Timestamp: 2020-02-10 10:30:10, Humidity: 21.5 %rH, Temperature: 22.9 *C, Radon STA: 36 Bq/m3, Radon LTA: 27 Bq/m3
Timestamp: 2020-02-10 10:35:20, Humidity: 21.5 %rH, Temperature: 22.8 *C, Radon STA: 36 Bq/m3, Radon LTA: 27 Bq/m3
```

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```.

## Piping data to a text-file
> **Note**: The scripts require that your device is advertising. If your device is paired/connected to e.g. a phone, you need to turn off bluetooth on your phone while using the scripts.
If you want to pipe the results to a text-file, you can run the script in the following way:

```
pi@raspberrypi:~/wave-reader $ sudo python2 read_wave.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.
> **Note on choosing a sample period:**
On 1st Gen Wave, temperature and humidity are updated every time we read the wave.
On 2nd Gen Wave, temperature and humidity are updated every 5 minutes.
On both devices, radon measurements are updated once every hour.

Exit the script using ```Ctrl+C```.

# Sensor data description

| sensor | units | Comments |
|-------------|-------------|-------------|
| Datetime | YYYY-MM-DD HH:MM:SS |
| Humidity | %rH |
| Temperature | °C |
| Radon short term average | Bq/m3 | First measurement available 1 hour after inserting batteries
| Radon long term average | Bq/m3 | First measurement available 1 hour after inserting batteries
| sensor | units | Comments |
|-------------------------------|---------------------|----------|
| Datetime | YYYY-MM-DD HH:MM:SS | Only available on 1st Gen Wave
| Humidity | %rH |
| Temperature | °C |
| Radon short term average | Bq/m3 | First measurement available 1 hour after inserting batteries
| Radon long term average | Bq/m3 | First measurement available 1 hour after inserting batteries

# Contribution

Let us know how it went! If you want contribute, you can do so by posting issues or suggest enhancement
[here](https://github.com/Airthings/wave-reader/issues), or you can open a pull request for review
[here](https://github.com/Airthings/wave-reader/pulls).
[here](https://github.com/Airthings/wave-reader/issues).


# Release notes

Release dated 10-Feb-2020

* Added read_wave2.py to support 2nd Gen wave devices
* Added py3 compatibility
* Removed tableprint dependency so all py3 versions can be used
* Removed redundant positional argument ```pipe``` (since tableprint is removed)
* Updated bluepy version dependency from 1.2.0 to 1.3.0

Release dated 14-Dec-2018

* Added SAMPLE-PERIOD as an input argument.
Expand Down
Loading

0 comments on commit 1ffada3

Please sign in to comment.