Home Assistant¶

Home Assistant is a home automation platform. It is able to track and control all devices at your home and offer a platform for automating control.

References¶

Home Assistant home page
- Raspberry Pi installation
- General installation (may be useful if you are trying to run on other hardware).
GitHub repository
DockerHub

Home Assistant: two versions¶

There are two versions of Home Assistant:

Home Assistant Container; and
Supervised Home Assistant (also known as both "Hass.io" and "Home Assistant Core").

Each version:

provides a web-based management interface on port 8123; and
runs in "host mode" in order to discover devices on your LAN, including devices communicating via multicast traffic.

Home Assistant Container runs as a single Docker container, and doesn't support all the features that Supervised Home Assistant does (such as add-ons). Supervised Home Assistant runs as a collection of Docker containers under its own orchestration.

The only method supported by IOTstack is Home Assistant Container.

To understand why, see about Supervised Home Assistant.

If Home Assistant Container will not do what you want then, basically, you will need two Raspberry Pis:

One running Raspberry Pi OS ("Raspbian") hosting IOTstack; and
Another dedicated to running Home Assistant Operating System.

Installing Home Assistant Container¶

Home Assistant (Container) can be found in the Build Stack menu. Selecting it in this menu results in a service definition being added to:

~/IOTstack/docker-compose.yml

When you choose "Home Assistant", the service definition added to your docker-compose.yml includes the following:

image: ghcr.io/home-assistant/home-assistant:stable
#image: ghcr.io/home-assistant/raspberrypi3-homeassistant:stable
#image: ghcr.io/home-assistant/raspberrypi4-homeassistant:stable

The active image is generic in the sense that it should work on any platform. You may wish to edit your docker-compose.yml to deactivate the generic image in favour of an image tailored to your hardware.

The normal IOTstack commands apply to Home Assistant Container such as:

$ cd ~/IOTstack
$ docker-compose up -d

Using bluetooth from the container¶

In order to be able to use BT & BLE devices from HA integrations, make sure that Bluetooth is enabled:

$ hciconfig
hci0:   Type: Primary  Bus: UART
    BD Address: DC:89:FB:A6:32:4B  ACL MTU: 1021:8  SCO MTU: 64:1
    UP RUNNING 
    RX bytes:2003 acl:0 sco:0 events:159 errors:0
    TX bytes:11583 acl:0 sco:0 commands:159 errors:0

The "UP" in the third line of output indicates that Bluetooth is enabled. If Bluetooth is not enabled, check:

$ grep "^AutoEnable" /etc/bluetooth/main.conf
AutoEnable=true

If AutoEnable is either missing or not set to true, then:

Use sudo to and your favouring text editor to open:
```
/etc/bluetooth/main.conf
```
Find AutoEnable and make it true.

If AutoEnable is missing, it needs to be added to the [Policy] section.
Reboot your Raspberry Pi.
Check that the Bluetooth interface is enabled.

HTTPS with a valid SSL certificate¶

Some HA integrations (e.g google assistant) require your HA API to be accessible via https with a valid certificate. You can configure HA to do this: docs / guide or use a reverse proxy container, as described below.

The linuxserver Secure Web Access Gateway container (swag) (Docker hub docs) will automatically generate a SSL-certificate, update the SSL certificate before it expires and act as a reverse proxy.

First test your HA is working correctly: http://raspberrypi.local:8123/ (assuming your RPi hostname is raspberrypi)
Make sure you have duckdns working.
On your internet router, forward public port 443 to the RPi port 443

Add swag to ~/IOTstack/docker-compose.yml beneath the services:-line:

  swag:
    image: ghcr.io/linuxserver/swag
    cap_add:
      - NET_ADMIN
    environment:
      - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
      - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
      - TZ=Etc/UTC
      - URL=<yourdomain>.duckdns.org
      - SUBDOMAINS=wildcard
      - VALIDATION=duckdns
      - DUCKDNSTOKEN=<token>
      - CERTPROVIDER=zerossl
      - EMAIL=<e-mail> # required when using zerossl
    volumes:
      - ./volumes/swag/config:/config
    ports:
      - 443:443
    restart: unless-stopped

Replace the bracketed values. Do NOT use any "-characters to enclose the values.

Start the swag container, this creates the file to be edited in the next step:
```
$ cd ~/IOTstack
$ docker-compose up -d
```
Check it starts up OK: docker-compose logs -f swag. It will take a minute or two before it finally logs "Server ready".

Enable reverse proxy for raspberrypi.local. homassistant.* is already by default. and fix homeassistant container name ("upstream_app"):

$ cd ~/IOTstack
$ sed -e 's/server_name/server_name *.local/' \
  volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf.sample \
  > volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf

Forward to correct IP when target is a container running in "network_mode: host" (like Home Assistant does):

Note: in order for copy-paste to work properly, the usual $-prompts are omitted

cd ~/IOTstack
cat << 'EOF' | sudo tee volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh
#!/bin/sh
DOCKER_GW=$(ip route | awk 'NR==1 {print $3}')

sed -i -e "s/upstream_app .*/upstream_app ${DOCKER_GW};/" \
   /config/nginx/proxy-confs/homeassistant.subdomain.conf
EOF
sudo chmod u+x volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh

(This needs to be copy-pasted/entered as-is, ignore any "> "-prefixes printed by bash)

(optional) Add reverse proxy password protection if you don't want to rely on the HA login for security, doesn't affect API-access:

$ cd ~/IOTstack
$ sed -i -e 's/#auth_basic/auth_basic/' \
    volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
$ docker-compose exec swag htpasswd -c /config/nginx/.htpasswd anyusername

Add use_x_forwarded_for and trusted_proxies to your homeassistant http config. The configuration file is at volumes/home_assistant/configuration.yaml For a default install the resulting http-section should be:
```
http:
   use_x_forwarded_for: true
   trusted_proxies:
     - 192.168.0.0/16
     - 172.16.0.0/12
     - 10.77.0.0/16
```
Refresh the stack: cd ~/IOTstack && docker-compose stop && docker-compose up -d (again may take 1-3 minutes for swag to start if it recreates certificates)
Test homeassistant is still working correctly: http://raspberrypi.local:8123/ (assuming your RPi hostname is raspberrypi)
Test the reverse proxy https is working correctly: https://raspberrypi.local/ (browser will issue a warning about wrong certificate domain, as the certificate is issued for you duckdns-domain, we are just testing)

Or from the command line in the RPi:
```
$ curl --resolve homeassistant.<yourdomain>.duckdns.org:443:127.0.0.1 \
    https://homeassistant.<yourdomain>.duckdns.org/
```
(output should end in if (!window.latestJS) { }</script></body></html>)
And finally test your router forwards correctly by accessing it from outside your LAN(e.g. using a mobile phone): https://homeassistant.<yourdomain>.duckdns.org/ Now the certificate should work without any warnings.

about Supervised Home Assistant¶

IOTstack used to offer a menu entry leading to a convenience script that could install Supervised Home Assistant. That script stopped working when Home Assistant changed their approach. The script's author made it clear that script's future was bleak so the affordance was removed from IOTstack.

For a time, you could manually install Supervised Home Assistant using their installation instructions for advanced users. Once you got HA working, you could install IOTstack, and the two would (mostly) happily coexist.

The direction being taken by the Home Assistant folks is to supply a ready-to-run image for your Raspberry Pi. They still support the installation instructions for advanced users but the requirements are very specific. In particular:

Debian Linux Debian 11 aka Bullseye (no derivatives)

Raspberry Pi OS is a Debian derivative and it is becoming increasingly clear that the "no derivatives" part of that requirement must be taken literally and seriously. Recent examples of significant incompatibilities include:

introducing a dependency on grub (GRand Unified Bootloader). The Raspberry Pi does not use grub but the change is actually about forcing Control Groups version 1 when the Raspberry Pi uses version 2.
unilaterally starting systemd-resolved. This is a DNS resolver which claims port 53. That means you can't run your own DNS service like PiHole, AdGuardHome or BIND9 as an IOTstack container.

Because of the self-updating nature of Supervised Home Assistant, your Raspberry Pi might be happily running Supervised Home Assistant plus IOTstack one day, and suddenly start misbehaving the next day, simply because Supervised Home Assistant assumed it was in total control of your Raspberry Pi.

If you want Supervised Home Assistant to work, reliably, it really needs to be its own dedicated appliance. If you want IOTstack to work, reliably, it really needs to be kept well away from Supervised Home Assistant. If you want both Supervised Home Assistant and IOTstack, you really need two Raspberry Pis.