AirThings Beacon

One of the issues we encountered when using the AirThings Wave Plus device is that the communication range between the sensor and hub is limited and thus interferes with our ability to set up multiple devices across multiple locations without the use of one hub per sensor. To get around this issue, we found that some people had programmed a Raspberry Pi (RPi) micro-computer to connect to and ping AirThings sensors via Bluetooth (BLE) to measure the indoor air quality (IAQ). These data would then be stored on the RPi. We can then SSH into the RPi beacons and pull the data since these devices will all be on campus and thus have IoT connectivity. This solution alleviates two issues:

1. The need for excessive hubs which are costly
2. The need for the AirThings business and their API which is challenging to use (based on our team's expertise) and has another small cost associated with it.

The following steps walkthrough the setup of what we are calling the "AirThings Beacon" so that our team and others may learn how to properly configure these devices.

Configuration

RPi Setup

The first step is setting up the RPi: getting the OS, configuring WiFi, and installing the necessary Python libraries.

SD Card

1. On your machine, download the Raspberry Pi OS Lite from this site. The latest 32-bit version works or you can also use the legacy 32-bit version.

2. Insert the SD card into your machine and flash the SD card. We recommend using Balena Etcher to do this.

3. Once completed, remove the SD card from your machine and insert into the RPi SD card slot.

WiFi on the RPi

There are many resources out there about configuring the WiFi on RPi -- all of which are perfectly fine to use. However, for our purposes, we have to connect the devices to UT's IoT network which requires a few extra steps.

Configuring Localisation Options

Keyboard

1. In this order attach an HDMI cable, a keyboard, and then power cable to the RPi.

2. After the RPi has finished booting up for the first time, we will need to configure some of the localisation settings to make our lives easier. Start by entering:

sudo raspi-config

which should pull up a window that looks similar to this but might be slightly different depending on the RPi and the OS version.

3. Using the arrow keys scroll down to Localisation Options and press enter

4. The keyboard needs to be corrected since when you press the shift+" you will get the @ character usually. Scroll down to Change Keyboard Layout and press enter. There should be a short pause as the RPi loads.

5. Choose the option for the "Generic 104-key PC" (should be the option directly above the one the RPi defaults to)

6. Choose "OTHER"

7. Choose "English (US)"

8. Choose "English (US)"

9. Press enter twice for the next two options: AltGr (default for the keyboard) and Compose Key (no compose key).

WLAN Country

1. The WLAN country code needs to be configured so that the WiFi is not blocked and we can access the WLAN0 MAC address. Use the arrow keys and scroll down to Localisation Options again and press enter.

2. Scroll down to the bottom option that should be something like "Change Wi-fi country" and press enter.

3. Scroll down or press the u key and select "US United States" and select "Yes" when prompted to confirm the change.

4. Back at the raspy-config menu, hit the right arrow key twice to move the cursor to finish and press enter. If prompted to reboot, select "Yes". If not, type

sudo reboot

at the main prompt to reboot the device.

Adding Device to IoT Network

Once the RPi is back online, we have to add it to the IoT Network. We need to get the devices MAC address but their are multiple so make sure you use the correct one to register the device.

1. On the RPi, type

ifconfig

2. A bit of information should pop up now that looks like the image below. Make sure to copy down the MAC address "wlan0" heading and not any other heading (see below).

3. On your machine, head over to www.network.utexas.edu and log in with the lab's credentials (contact Hagen Fritz @hagenfritz@utexas.edu for these).

4. Once in, select "Register Wireless Device".

5. In the top prompt, enter the MAC address you copied down earlier.

6. For the "Device Description", use "airthings-beacon-<last_four_of_AirThing_Serial_No>" replacing <last_four_of_AirThing_Serial_No> with the corresponding AirThings serial number which can be found by looking at the registered devices on your AirThings dashboard:

7. Once registered, the device's password will appear which should be a combination of 20 numbers. Keep this password on hand.

8. Back on the RPi, edit the WiFi credentials by typing

sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

9. In the file, enter in the WiFi credentials following the example below. The WiFi password from the UT network includes spaces so the 20-long string is easier to read, but these spaces should not be included.

10. Double-check you entered the password correctly, included opening and closing double quotes, and that the file has the line country=US near the top. Now press ctrl+x, then y to save, and return to keep the same filename.

11. Do a sudo reboot from the terminal and wait for the RPi to cycle through the booting process. If you successfully configured the WiFi, you should see "My IP address: xxx.xx.xxx" as one of the last entries of the boot process. To double-check if you are connected to WiFi, type

ping google.com

and you should get periodic updates as the RPi pings the site. Type ctrl+c to stop this process.

Downloading the Repo and Necessary Libraries

Install Git, Clone, and Install Libraries

1. On the RPi, install git with

sudo apt install git

2. Clone the AirThings WavePlus Beacon repo in the home directory with

git clone https://github.com/intelligent-environments-lab/airthings-waveplus-beacon.git

3. Check that the repo was successfully cloned by typing ls and look for the directory "airthings-waveplus-beacon" directory

4. Move into the newly created directory with

cd airthings-waveplus-beacon

and run the install shell script with

sh install.sh

Configuring the VPN

We have a VPN service that we use which allows us to easily connect to the devices. The primary libraries have already been downloaded, we just have to link the device to our account.

1. Generate a one-time or multiple-use authorization key from the settings page on Tailscale. We have a dedicated Tailscale account for this project under the email iel.bomp@gmail.com. A multiple-use key has already been generated and can be provided to you by Hagen or simply use a single-use key.

2. Type the following command to get Tailscale running on the RPi:

sudo tailscale up --authkey <authorization_key_from_tailscale>

replacing <authorization_key_from_tailscale> with a one-time or multiple-use authorization key (see point below for more information).

3. Confirm connection on the RPi on the machines page for Tailscale.

4. Click the three dots to the right to rename the device with the same name used when connecting to the UT IoT network: "airthings-beacon-<last_four_of_AirThing_Serial_No>" replacing <last_four_of_AirThing_Serial_No> with the corresponding AirThings serial number which can be found by looking at the registered devices on your AirThings dashboard.

5. Click the three dots again and select the option to "Disable key expiry".

7. You should now be able to access the AirThings Beacon with a static IP address!

Additional Configuration Settings

Some last touches to set up the RPi

Enable SSH

We won't be able to get into the devices unless you enable SSH through another

sudo raspi-config

Again, this will pull up the following window.

This time, choose 3 Interface Options followed by P2 SSH. You will be prompted if you would like to enable SSH, which you should choose the option for yes.

Scheduled Reboot

After a while, the RPi starts to get tired so we program in a daily reboot at 23:59 through the crontab. Start by editing crontab by:

sudo crontab -e

The first time you do this, the RPi will prompt you with which editor you would like to use. We suggest nano since this is the simplest interface. Once editing, add the following line to the bottom of the file:

59 23 * * * /sbin/shutdown -r now

More explanation for this line can be found here, but we are telling the RPi to reboot at 23:59 each day.

WavePlus Reader Software

Next is to configure the software to read from the correct AirThings device.

Setup Save Directory

Before running the software, we need to include a new directory. At the home directory type:

sudo mkdir DATA

which will create the DATA directory where the software will attempt to save the measured data.

Installing and Updating Service File

The steps for doing this are provided in the readme file of the airthings-waveplus-beacon repository.

Testing

Lastly, we need to test that the RPi and AirThings sensor are playing nicely.