Monitor Home Air Quality with Home Assistant and balena

This guide illustrates how to run Home Assistant using balena on a Raspberry Pi to create a beautiful dashboard accessible from anywhere in the world. In the case of this project, you can gather data from multiple environmental sensors, including air quality.

We’ll utilize another project we introduced last year called balenaSense which uses MQTT to transfer its air quality readings to other systems. If you don’t have an instance of balenaSense, you can still use this guide as a template for interfacing any device that communicates over MQTT.

If you're unfamiliar with Home Assistant, it's a popular open source home automation system that is often run from low-cost devices like a Raspberry Pi. Here’s how to use balenaSense to push its sensor data to Home Assistant using MQTT.

One of the benefits of using balenaCloud to run Home Assistant is that you will (optionally) have a public URL you can use to access your dashboard from anywhere without having to reconfigure your router or worry about dynamic DNS. Another benefit is that the setup process is completely headless - you do not need to plug a keyboard, mouse or monitor into the Pi nor do you need to find it on your network. The balena platform takes care of pushing all of the code to the device.

The basic system we will be setting up in this guide can be further expanded with wireless light switches, outlets, door locks and other devices. (more about that below.) In addition, we’ll leverage the existing balenaSense project to push its sensor data to Home Assistant using MQTT, a lightweight messaging protocol well suited to communication among connected devices and sensors.

Contents

This is a very detailed guide, so here’s a table of contents for you to navigate to a specific step quickly.

• Getting started (hardware and software requirements)
• Pushing the project code to your devices
• Setting up Home Assistant
• How it works
• Going further

Getting started

Hardware required

Here’s the list of items required for a basic setup:

• Raspberry Pi 3B or greater (A B+ or 4B works great, and less powerful Pis can be used albeit with lower performance)
• A Micro-SD Card (Home Assistant recommends 32 Gb or larger; we recommend Sandisk Extreme Pro SD cards for best results)
• Power supply and cable
• Optional: For connecting wireless devices such as locks and light switches, a Z-Wave gateway such as the Aeotec Z-Stick Gen5

Software required

We’ve placed the balena + Home Assistant project on GitHub which contains all of the software and configuration you’ll need to get started. We’re going to deploy this project on balenaCloud using a free account to push the project and all the software to your Raspberry Pi as well as to provide remote access. Therefore, you’ll need:

• A tool to flash your SD card, such as balenaEtcher
• A free balenaCloud account
• A clone or download of our project from GitHub

Setting up the Raspberry Pi

In your balenaCloud account, create a new application and name it anything you’d like as long as it is unique to your account.

Now add a device - this is where you can pre-fill your WiFi information if you’d like. Once you have downloaded the balenaOS disk image from the dashboard, unzip the image on your local drive and then use Etcher to flash the SD card with that image.

Place the flashed SD card into your Pi and power it up. In about a minute, it should show up on your dashboard with an online status. Your device is now provisioned! Click on the device name to display its information page.

Deploying the software

Once you’ve provisioned, booted, and connected your Raspberry Pi device to your balenaCloud account, you’re ready to push code to the device.

Installing the balena CLI tools on your workstation

BalenaCloud allows us to push application software/code to the Raspberry Pi and other devices fully remotely and over the air. To do this for the first time, there are some minimal software requirements that you need to satisfy on your own workstation (not the Raspberry Pi.)

If you already have (or can setup) npm on your machine, this is most likely the easiest way to get the CLI tools up and running quickly. However, there are also standalone binaries for Windows, macOS and Linux available.

Note: if you've already installed these tools to complete another of our projects, you don't need to do this part again - skip directly to the next step.

The documentation for the CLI tools is the best place to start and covers the installation and setup of both the npm package and the standalone binaries. When you have the CLI installed and working, the first step is to login to balenaCloud by issuing the balena login command:

Once you’ve reached this point, and have a working CLI which has been logged in to your account, you're ready to start pushing code to your Raspberry Pi.

Downloading the project from GitHub

The next step is to download the code for this project from GitHub.

The “Clone or download” button will download a.zip file of the project which you'll need to unzip, but if you're already familiar with Git you can use git clone in the normal way.

Pushing the project code to your Raspberry Pi

Since you have the CLI set up and the latest code downloaded, you can now execute a single command to push that code to balenaCloud which in turn builds the Docker image and handles the process of setting it up and running it on your device.

From within the unzipped project directory, execute balena push <appName>, where is the application name you set earlier in the guide. For example: balena push balena-ha.

If everything worked out correctly, after a few minutes your device information screen in the dashboard should look something like this, showing the services running, one for each of the software components.

When you push the code for the first time, it can take a few minutes to download (dependant on your internet connection speed). After that, only the changes in the container are downloaded so things happen much quicker.

Viewing the dashboard

Hopefully you got your device flashed, connected to your network, and up and running without too much trouble. One of the great benefits of using a free balenaCloud account is that you’re able to use the Public Device URL feature.

Enable this toggle on your device and click the ensuing blue arrow to access your Home Assistant installation.

Setting up Home Assistant

Initially, Home Assistant will walk you through setting up a user account and your location information (note that this information is only stored locally, in keeping with Home Assistant’s privacy-focused mission). Once you click “finish” on the final setup screen, (no need to click “more…”) you should see the main dashboard with the default sensor values being displayed.

Configuring Home Assistant

One of the great features of Home Assistant is that it is highly configurable. While a full dive into configuration is beyond the scope of this guide, we will cover some of the basics. You can find all of the various configuration options along with documentation and examples on the Home Assistant website.

Although much configuration can be accomplished using the Home Assistant UI, we will be making manual changes by editing a file called configuration.yaml. It is a text file in the YAML format that is dependent on proper indentation and syntax. As such, we have included a handy text editor called Hass-Configurator which is available locally and via the public URL (if enabled) on port 8080. Using the example device from the above screenshot, you would browse to http://192.168.1.147:8080 to access the Hass-Configurator. (If the public URL is enabled, you should secure the editor using the customization information below in the “going further” section).

Let’s first use the configuration editor to set up MQTT in Home Assistant. On the Hass-Configurator main page, click the folder icon in the upper left to open a file. By default, the editor will open the shared configuration folder (/hass-config) and display a list of all its files. Select configuration.yaml to open it in the editor. Above the line that reads group: !include groups.yaml we will add the lines:

mqtt:
broker: mqtt

Note that there must be two spaces before the word broker. Your entry should look like this:

Here we are telling Home Assistant to enable MQTT, and providing the hostname of our local MQTT broker container (you could also provide the IP address of the local container or the IP address of any other reachable broker you might want to use. To include a username or password, see the documentation.) The configuration editor has a very handy real-time syntax checker, so if you do not see a green checkbox in the upper right, check your work before saving, paying particular attention to indenting and punctuation. Click the red floppy disk icon at the top to save your changes to the file.

Any time you change the configuration, you should go back to Home Assistant and use its configuration checker to make sure your changes do not contain any errors. First click on your username at the bottom of the left hand menu. Scroll down until you see “Advanced Mode” and enable it. (You only have to enable that one time.) Now click the “configuration” gear icon on the left menu then click “server controls” and then click the “CHECK CONFIG” button.

If any errors are displayed, go back and check your recent changes to the configuration file. If there are no errors, scroll down to “Server management, ” click “RESTART” then click “OK.” In a few seconds Home Assistant will restart and your changes will take effect.

How to integrate Home Assistant with balenaSense

Earlier this year, we introduced the balenaSense project which allows you to monitor nearby air quality using a sensor attached to a Raspberry Pi along with InfluxDB, Grafana, and Docker. Since this is a very complementary feature for a home automation system, let’s see how we can connect a working instance of balenaSense to this project.

You can follow the balenaSense tutorial to create a self-contained air quality monitoring device. Confirm that your balenaSense installation is up and running on the same network as this project.

Note: Although this guide assumes you have balenaSense running on a separate Raspberry Pi, somewhat more advanced users might want to merge the two projects together onto one device. You could take the containers defined in this project’s docker-compose file and with some minor editing add them into balenaSense’s docker-compose file. (You only need one MQTT container in that case.)

Earlier in this gude we enabled our internal MQTT broker, so now we need to tell balenaSense to publish data to it. From the balenaCloud dashboard for your Home Assistant device, copy the IP address to your clipboard using the provided icon.

Now, on your balenaCloud dashboard, navigate to the Pi that is running the balenaSense application.

We’ll add a device variable to provide the location of our broker that we just copied. Once you have selected the balenaSense device, click on the “D(x) Device Variables” button on the left, then the “+ Add variable” button near the top. In the “Add variable” popup, for “NAME” enter TELEGRAF_MQTT_URL_PORT and then paste the IP from your Home Assistant application into the “VALUE” box. Append :1883 after the address which is the port number. In our example, it would read 192.168.1.147:1883. Finally, click “Add” and then balenaSense will restart and begin publishing its sensor data to Home Assistant.

Note: We're assuming here that the IP address of your Home Assistant device will not change. If it does, you will need to redo the steps above. Even better, you can set a static IP on any of your balenaOS devices by following these instructions.

Before we can actually see the sensors in Home Assistant, we need to add them to the configuration.yaml file. You can see the sensors we want to add by opening the file /hass-config/sense.yaml in the configuration editor. Copy the full contents of this file and paste into the bottom of the configuration.yaml file.

Alternatively, you can run a script we prepared to do the copying for you. In the editor, click the gear icon in the upper right and select “Execute shell command.” In the popup box, type /hass-config/sensors.sh and click “Execute.” Almost immediately, you should see “Task completed!” at which point you can click “Close.”

Now if you open configuration.yaml, you’ll see all of the sensors we added at the bottom. Just like with any other change made to the configuration file, go into Home Assistant and check the config then restart as detailed previously. Now when you go to the main overview screen, you should see all of the new balenaSense sensors.

You can add multiple balenaSense instances to Home Assistant. Follow the above instructions for publishing each instance to your Home Assistant device. Then add the additional sensors to the configuration.yaml file under the “sensors:” section.

You can simply copy and paste the existing ones, but we’ll need to make one change. Note how each sensor in the configuration.yaml file has a “state_topic” that looks something like this: state_topic: "balena-sense/+/balena-sense". The plus sign is a wildcard character, so any value can be in its place. Normally balenaSense places the device UUID in that location, but if you have only one balenaSense instance, the UUID doesn’t matter.

If you have more than one instance, you’ll need to replace the plus sign in all of the sensors with the seven-digit UUID of the balenaSense device that is publishing the data. For instance, ”balena-sense/37c36e0/balena-sense" where 37c36e0 is the UUID from a balenaSense device in your balenaCloud dashboard. You’ll also want to make sure the “name” value is unique for each sensor so you can tell them apart.

Home Assistant has a newer customizable UI called “Lovelace.” You can modify the default layout and replace the orange indicators with gauges and graphs by clicking the three vertical dots in the upper right and selecting “Configure UI.” Alternatively, we have provided a pre-built layout you can use for the sensors we added, but in order to activate it you’ll need to add the following to configuration.yaml:

lovelace:
mode: yaml

Here’s what the entries should look like:

You can place the lines anywhere so the exact line numbers are not critical. What is important is that the indentation is correct. Save, check and then restart to see the updated UI. It should look something like this:

To see how we designed this layout, take a look at the ui-lovelace.yaml file. Note that by changing the layout to a custom one, you are now responsible for adding any subsequent new sensors by manually editing the ui-lovelace.yaml file in the /hass-config directory.

If you want Home Assistant to automatically manage the layout, or to use the visual “configure UI” feature again, you’ll need to comment out or delete the lovelace lines we added to the configuration.yaml file.

How it works

The latest version of balenaSense provides the ability to publish its sensor data via MQTT. This project creates a Home Assistant instance that includes an MQTT broker. By providing both balenaSense and Home Assistant with the IP address of our broker, they can share the sensor data with each other as visualized below:

Alternatively, we could just as easily have used the broker contained in balenaSense by setting the device variable TELEGRAF_MQTT_URL_PORT to INTERNAL and placing the balenaSense broker IP address in configuration.yaml:

Going further

Now that you have balenaSense air quality data in Home Assistant, you can use their powerful automations to act on that data. Has the air quality score increased above a particular threshold? Then turn on an air-purifier or similar device. Room temperature too high? Have Home Assistant trigger a fan.

A common item to add to a Home Assistant setup is a Z-Wave gateway such as the Aeotec Z-Stick. This provides the ability to incorporate door locks, light switches, energy meters and many other devices. You can use these instructions for adding Z-Wave via configuration.yaml.

To customize the operation of the Hass Configurator editor, you can set additional device environment variables.Check out this resource for more information.

Get it going and let us know what you think

Once you have the project up and running, experiment with different setups and configurations to suit your needs! As always, if you run into any problems or have any questions or suggestions, reach out to us on the forums, Twitter or Facebook.