Home Assistant on balena! Why?
- Easy, secure remote access out of the box - no changes to your router required
- Headless deploy process - no hunting for your device
- Run on a minimal OS optimized for containers
- Device dashboard and SSH access via balenaCloud
- Easy to run additional containers/services alongside Home Assistant
Home Assistant is a popular open source home automation system that is often run from low-cost devices like a Raspberry Pi. This project provides a bare-minimum install using balena, along with some examples of how to extend your installation and integrate with other projects such as balenaSense
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)
- 32GB (or larger) Micro-SD Card (we recommend Sandisk Extreme Pro SD cards)
- 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
This repository 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
Running this project is as simple as deploying it to a balenaCloud application, then downloading the OS image from the dashboard and flashing your SD card.
We recommend this button as the de-facto method for deploying new apps on balenaCloud, especially if you are just getting started or want to test out the project. However, if you want to modify the docker-compose or tinker with the code, you'll need to clone this repo and use the balenaCLI to push to your devices. This can be done later if you initially deploy using the button above. Read more.
To access your new Home Assistant instance, browse to the IP address of your device. You can find the device's IP address in your balenaCloud dashboard. Go through the Home Assistant setup process and establish a username and password. To obtain a secure public URL for your Home Assistant instance, simply click the "Public Device URL" switch on your balenaCloud dashboard. You'll then see a link to access your unique device URL.
Our project's docker-compose file creates a persistent volume on your disk/SD card for storing Home Assistant configuration files. These are located in the /config folder.
A text editor called Hass-Configurator is available locally on port 3218. (To access this: http://192.168.1.120:3218 - but substitute the local IP address of your Home Assistant) Using this editor, you can make changes to the Home Assistant configuration file configuration.yaml which is the in the default folder hass-config for Hass-Configurator. (hass-config is mapped to /config)
You can enable MQTT in Home Assistant from the Configuration > Devices & Services > Add Integration button (for "broker" enter mqtt) or by adding the following lines to configuration.yaml:
mqtt:
broker: mqtt
(note that there must be two spaces before the word broker.) 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.) 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. If there are no errors, restart Home Assistant for your changes to take effect.
[Environment variables](environment variable) can be used to configure the configurator. For example, to add basic HTTP authentication, the HC_USERNAME and HC_PASSWORD variables can be specified. The password in plain text or via SHA256 by prepending the hash with {sha256}. For more information on configurator variables visit: https://github.com/danielperna84/hass-configurator/wiki/Configuration
Note that to specify any of these configuration variables as an environment variable they should be prepended with HC_.
To unleash the full power of Home Assistant, you can add the ability to control and automate lights, locks, sensors etc... by adding radio-controlled equipment to your installation. Two of the popular protocols for radio-controlled devices are Zigbee and Z-Wave. These are not compatible systems, so it's best to choose one and stick with it.
To control devices using Z-Wave you'll need a compatible gateway device, as well as one or more Z-Wave lights, switches, outlets, etc... More information about these devices can be found here. To use the Home Assistant recommended Z-Wave JS integration, you'll need to plug your gateway (We used a Aeotec Z-Stick Gen5 for our testing) into the device's USB port, and then add a JS server to your docker-compose similar to this:
zjs:
container_name: zjs
image: kpine/zwave-js-server:latest
restart: unless-stopped
privileged: true
environment:
USB_PATH: "/dev/ttyACM0"
S0_LEGACY_KEY: "27DAB0C1BAD5DABFF74E4B5274E257C3"
volumes:
- zjs:/cache
ports:
- '3000:3000'
You'll also need to add zjs: to the volumes section of the file to use the above example. (More information about this container setup can be found here.) Note that you will need to generate a random S0_LEGACY_KEY and possibly other keys as well - see the linked container documentation. For the USB_PATH: you will need to know the device name for your Z-Wave gateway hardware. /dev/ttyACM0 is a typical value, but you can ssh into the HostOS and run ls /dev to see a list of devices. You may need to compare the list with the gateway plugged in and not plugged in to determine the name.
Once you've updated the docker-compose file, push the updated project to your fleet using the balenaCLI.
To complete the Z-Wave setup, you'll need to use the Home Assistant UI and select configuration > Devices & Services > + add integration > Z-Wave JS. For the URL, enter ws://zjs:3000 and you should receive a "Success!" message.
Like for z-wave, you'll need a gateway device to connect to zigbee devices. Zigbee calls this a co-ordinator. We used a Sonoff Dongle Plus during testing, which we had to flash the firmware on the dongle before it could be used. We found the instructions on the blakadder Compatibility Repository easy to follow. Once the co-ordinator is flashed and ready to use, plug it into a USB port on the device running Home Assistant. Then go into the Home Assistant UI, into the Configuration page, Integrations and add the Zigbee Home Automation integration. Once the integration has installed it should create a dialogue asking you to select your co-ordinator which should be listed. With this selected you can set about putting your zigbee devices into a pairing mode, and clicking Add device on the zigbee integration page.
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.
The balenaSense tutorial also has a section about Home Assistant integration. To summarize:
Using the balenaCloud dashboard, add an MQTT_ADDRESS device variable to your balenaSense project's "sensor" service with a value of your Home Assistant device's IP address. Make sure MQTT is enabled as described above.
Before we can actually see the sensors in Home Assistant, we need to add them to the configuration.yaml file in the "sensor" section. The sensor values from balenaSense will have the MQTT topic of sensors and each value will have a separate name, depending on the type of sensor. For instance, the sensor value names for a bme680 would be: temperature, pressure, humidity and resistance. To get the names of all your available sensor values, look at the names above the values in your balenaSense dashboard.
Using the HASS Configurator, open the configuration.yaml file and add the sensors under the sensor: section. (If that section does not exist, you can add it.) We'll use the Home Assistant mqtt sensor platform and a json value_template syntax as shown in the following example for a bme 680:
sensor:
- platform: mqtt
state_topic: "sensors"
value_template: "{{ value_json.humidity }}"
name: "sense_humidity"
unit_of_measurement: "%"
- platform: mqtt
state_topic: "sensors"
value_template: "{{ value_json.temperature }}"
name: "sense_temperature_c"
unit_of_measurement: "degrees"
- platform: mqtt
state_topic: "sensors"
value_template: "{{ ((float(value_json.temperature) * 9 / 5) + 32) | round(1) }}"
name: "sense_temperature_f"
unit_of_measurement: "degrees"
- platform: mqtt
state_topic: "sensors"
value_template: "{{ value_json.pressure }}"
name: "sense_pressure"
unit_of_measurement: "mbar"
Save the file and restart Home Assistant for the changes to take effect.
If you don't need a full balenaSense installation but want to integrate a sensor directly with Home Assistant, follow our guide for including the sensor block in your project.
Because we're running containers on balenaOS, it's easy to add complementary services to your project by simply adding them to your docker-compose file. Below are a few of our favorites that work well with Home Assistant. Note that to add these services, you'll need to clone and edit this repository then use the balenaCLI to push your updated project to your fleet of devices.
Frigate is a full featured NVR (Network Video Recorder) that integrates nicely with Home Assistant. Check out this repository for an example of Frigate running on balena. You could merge the services of that project's docker-compose (except MQTT because we already included it) with this project, as well as copy over the folders and files.
AppDaemon is an environment for creating Python automations for Home Assistant, but it also includes HADashboard - a beautiful dashboard for Home Assistant that is intended to be displayed on a wall mounted monitor. (HADashboard does not require any Python programming!) To include this functionality, simply add the following to your docker-compose. You can access your dashboards on port 5050 (for instance http://192.168.1.120:5050 - but substitute the local IP address of your Home Assistant)
appdaemon:
container_name: app-daemon
image: acockburn/appdaemon:latest
ports:
- "5050:5050"
volumes:
- config:/conf
restart: always
depends_on:
- homeassistant
Once you have added the above to your docker-compose file, re-push the application using the CLI. Next, you'll need to use the HASS Configurator to edit the appdaemon.yaml file in hass-config. Here is a sample to get you started:
appdaemon:
latitude: 0
longitude: 0
elevation: 30
time_zone: Europe/Berlin
plugins:
HASS:
type: hass
ha_url: http://192.168.1.120
token: <your token>
http:
url: http://192.168.1.120:5050
admin:
api:
hadashboard:
dash_url: http://192.168.1.120:5050
You'll need to substitute the IP address of your device, and create a "Long-Lived Access Token" in Home Assistant by navigating to your profile page, scrolling down, and clicking the "Create Token" button. Use that (very long) value in place of <your token>.
InfluxDB is a comprehensive time-series database and Grafana is a complentary graphing package to build and display dashboards. Home Assistant can be configured to store some or all of its data in InfluxDB. The Grafana dashboards are well suited to displaying chages in sensor and other values over time, as opposed to current values and more binary information displayed by HADashboard. See this repo for an example of incorporating InfluxDB and Grafana into your Home Assistant project using balena. At a minimum, you'll need to add the following lines to your docker-compose file:
influxdb:
image: influxdb:1.8.6
volumes:
- influxdb:/var/lib/influxdb
grafana:
image: grafana/grafana:8.1.2
volumes:
- grafana:/var/lib/grafana
ports:
- 3010:3000/tcp
You'll also need to add these lines to the "volumes:" section:
influxdb:
grafana:
After pushing the updated project to your device using the CLI, you'll need to set up the Influx database and then instruct Home Assistant to use it as outlined here. You can also check out the official integration instructions here for more information. Grafana will then be available on port 3010 and you can start designing your own dashboards. (Note that we re-mapped Grafana from its usual port of 3000 to avoid conflict with Z-Wave JS)
After you log into Grafana, you'll need to set up a data source on which to base your dashboards. When setting up a data source, use http://influxdb:8086 as the HTTP URL and homeassistant as the database name.
Here is an example of merging many of the integrations mentioned above into one docker-compose.yaml file:
version: '2'
volumes:
config:
mosquitto:
influxdb:
grafana:
zjs:
cache:
services:
homeassistant:
build: homeassistant
ports:
- 80:8123
privileged: true
volumes:
- 'config:/config'
restart: always
mqtt:
build: mqtt
ports:
- "1883:1883"
restart: always
volumes:
- mosquitto:/mosquitto/data
hass-configurator:
image: "causticlab/hass-configurator-docker:latest"
restart: always
ports:
- "3218:3218"
volumes:
- 'config:/hass-config'
environment:
- HC_BASEPATH=/hass-config
appdaemon:
container_name: app-daemon
image: acockburn/appdaemon:latest
ports:
- "5050:5050"
volumes:
- config:/conf
restart: always
depends_on:
- homeassistant
influxdb:
image: influxdb:1.8.6
volumes:
- influxdb:/var/lib/influxdb
grafana:
image: grafana/grafana:8.1.2
volumes:
- grafana:/var/lib/grafana
ports:
- 3010:3000/tcp
zjs:
container_name: zjs
image: kpine/zwave-js-server:latest
restart: unless-stopped
privileged: true
environment:
USB_PATH: "/dev/ttyACM0"
S0_LEGACY_KEY: "27DAB0C1BAD5DABFF74E4B5274E257C3"
volumes:
- zjs:/cache
ports:
- '3000:3000'
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.