https://www.home-assistant.io/, the docs https://www.home-assistant.io/docs/ and the forum https://community.home-assistant.io/
When having dedicated Raspberry device for Home Assistant follow guides as https://www.home-assistant.io/installation/raspberrypi/ and get directly a Raspberry Home Assistant SD card image. Using this way the Home Assistant Operating System gets installed.
If the Raspberry is serving primary for other purposes than Home Assistant or if it is already there and running Home Assistant can be installed in a container https://www.home-assistant.io/installation/
Install in a virtual environment as virtual box will get the Home Assistant Operating System as well but requires a complete additional system installation. Install Home assistant in a container makes use of the running system and kernel and is therefore less resource depending.
See https://www.home-assistant.io/installation/raspberrypi-other. There are different container solutions but the guide focuses on docker. Docker must be first installed
see https://docs.docker.com/engine/install/debian/. This is done by adding the docker repository.
# Add Docker's official GPG key: sudo apt-get update sudo apt-get install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc # Add the repository to Apt sources: echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update
then install docker sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Then run the hello world container sudo docker run hello-world the command looks for the hello world container on the raspberry and if not found it down loads it from the docker hub.
To have docker running as none root,
newgrp docker inform the system that the docker group has changed
Add the user to the docker group so it can connect to docker sudo usermod -aG docker $USER
Logout and login again and run docker run hello-world
To run it decide the values for:
TZ=<time zone>
Path where the home assistant docker configuration goes.
Then create this directory sudo mkdir -p /opt/docker/homeassistant
Give permission for the local user
sudo chown -R $(id -u):$(id -g) /opt/docker/homeassistant
docker run -d --name homeassistant --privileged --restart=unless-stopped -e TZ=Europe/Zurich -v /opt/docker/homeassistant:/config -v /run/dbus:/run/dbus:ro --network=host ghcr.io/home-assistant/home-assistant:stable
If successful docker starts and since home-assistant docker container is not on the local machine it gets downloaded from docker hub and this takes a while.
--network=host makes that the local machines IP address can be used and not the docker one showed by sudo ifconfig
The above docker command installs and runs homeassistant but to have this done automatically next startup a systemd file needs to be created: sudo touch /etc/systemd/system/homeassistant.service
[Unit] Description=Home Assistant Container Requires=docker.service After=docker.service [Service] Type=oneshot RemainAfterExit=yes WorkingDirectory=/opt/docker/homeassistant ExecStart=/usr/bin/docker run -d --name homeassistant --privileged --restart=unless-stopped -e TZ=Europe/Zurich -v /opt/docker/homeassistant:/config -v /run/dbus:/run/dbus:ro --network=host ghcr.io/home-assistant/home-assistant:stable ExecStop=/usr/bin/docker stop -t 60 homeassistant ExecStopPost=/usr/bin/docker rm -f homeassistant [Install] WantedBy=multi-user.target
docker ps -a check if docker still runs homeassistant
docker stop homeassistant stop it
docker rm homeassistant remove temporary files
sudo systemctl daemon-reload make the system aware of the new service
sudo systemctl enable homeassistant.service tell it to start it automatically next boot
sudo systemctl start homeassistant.service start it manually
sudo systemctl status homeassistant.service check its status
sudo journalctl -u homeassistant.service -f check its log
to update homeassistant
Stop the service sudo systemctl stop homeassistant.service
get the update docker pull ghcr.io/home-assistant/home-assistant:stable it will also tell if there is an update
docker rm homeassistant remove temporary files
sudo systemctl start homeassistant.service start it again
Once installed, it can be accessed as http://<ip address>:8123
There is also an app available for mobile devices
Some terms to know
Integrations are ways to communicate to devices or protocols
Entity ID are identifiers of states to be exchanged. States are values as on or off, or a numeric value and can be seen as data. State changes can be used in triggers as events to be processed.
Helpers can take their data from everywhere including Home Assistant User Interface. So helpers do not need hardware. Helpers can count
Dashboards can be created holding Cards and the cards hold Entities. There is also the Grid Card that holds other Cards and allows therefore to group Cards.
Scripts are as automations but do not have triggers. Scripts have therefore be used in automations.
Scenes allow to send actions to multiple devices instead of sending actions to multiple times to individual devices
Blueprints are automation templates and scripts to not need ti start from zero
Tags are NFC or QR tags that can be used as triggers
Sensors are entities that provide a value
A switch can provide its value but can also be toggled, it is therefore bi-directional
A light is like a switch but has additional functionality, as brightness and RGB color
/home/homeassistant/.homeassistant hold the data including yaml files
Automations is the logic added to Home Assistant that takes inputs or events and controls outputs or actions. It is what Home Assistant does automatically. Automations have triggers.
Automations can be created and edited via the gui or yaml.
The following example turns on an output of a tasmota device at 8 o'clock:
alias: Tasmota Switch On at 20:00
description: Turn on switch.tasmota2 at 20:00
trigger:
- platform: time
at: "20:00:00"
action:
- service: switch.turn_on
target:
entity_id: switch.tasmota2
data: {}
Or turn it on at sunset:
alias: Tasmota Switch On at sunset
description: Turn on switch.tasmota2 at sunset
trigger:
- platform: sun
event: sunset
offset: "0"
condition: []
action:
- service: switch.turn_on
target:
entity_id: switch.tasmota2
data: {}
mode: single
And a humidity alarm:
alias: Humidity Alarm Bathroom On
description: Humidity is above level
trigger:
- platform: numeric_state
entity_id: sensor.shellyplusuni_a0a3b36865f4_humidity
above: 45
condition: []
action:
- type: turn_on
device_id: f9ecf0bcd602949c51a780527ac19b57
entity_id: switch.shellyplusuni_a0a3b36865f4_switch_0
domain: switch
mode: single
Shelly's https://www.shelly.com/ appear as WLAN servers creating their own network and have ip addresses as http://192.168.33.1
The first step is using a WLAN capable PC and check for available WLAN networks as SSID: Shelly1PMMiniG3-<number> . Then connect to the network. After this open a browser with http://192.168.33.1 and the Shelly's device web page appears
Now configure the WLAN settings so it uses the same network as the home assistant device. A static address can be set to have a defined IP address. Then enable the network to have now the Shelly accessible to home assistant and it stops blinking its red LED. It however stays also in its SSID: Shelly1PMMiniG3-<number> using http://192.168.33.1. Everybody could connect to it, so it is a cyber security issue, set a user name and password and to be more safe disable the shelly's access point feature. This however has the risk that a factory reset might be required in the future, if password or user names will be lost or if the WLAN home network changes.
Enable access point when modifying something on the WLAN home network. If it goes wrong then the Shelly can be accessed otherwise a factory reset is required.
Factory resets could be done by pressing the buttons on the shelly's for longer than 10s or if no button is present by multiple quick power on off cycles.
Since it is now connected to the Internet it is time to check for firmware updates.
The Shelly has lot of functions and features to configure and operate itself without using home assistant. If using home assistant, it needs therefore be taken care that no interference between the home assistant and the local Shelly configuration occurs.
The Shelly and home assistant must communicate themselves using one out of the many protocols available. However both must use and understand the same protocol.
Many Shelly's are directly found by Home Assistant and will be directly integrated in its GUI.
However some Shelly's as Generation 3 are not detected yet and can be used by defining their protocol. One common protocol (not just for Shelly's) is MQTT. If not having Home assistant OS or Supervised then a MQTT broker is missing so sudo apt install mosquitto mosquitto-clients and configure mosquitto.
If it is discovered automatically check the IP address. If the address is a wireguard address then ignore the device and add a OctoPrint device with the local private network address
When adding the OctoPrint device to Home assistant then the OctoPrintes user name needs to be entered and OctoPrint started. OctoPrint then asks to grant the connection.
There are different implementations for webcams in OctoPrint. OctoPrint tries to use them but not to set them up. Therefore the Webcam can use the Home Assistant MJPEG IP Camera Integration using a stream as http://<ip>:8080/stream. The Picture Entity Card can then be used to show the camera stream.
The GUI has its limits for configuration especially when integrations are missing or generic communication protocols are used. In this case the configuration file is usually in /home/homeassistant/.homeassistant/configuration.yaml needs to be edited.
If working in a console work as user homeassistant:
sudo -u homeassistant -H -s
In Home Assistant Gui Developer Tools CHECK CONFIGURATION https://www.home-assistant.io/common-tasks/core/#configuration-check or source /srv/homeassistant/bin/activate and hass --script check_config
For new items a restart is necessary after that modifications need just a YAML reload, click an green tick should appear.
To get a modular configuration configuration.yaml can includes other yaml files. To move out the mqtt stuff in a separate mqtt.yaml file add to configuration.yaml
mqtt: !include mqtt.yaml
then create the mqtt.yaml without repeating mqtt again:
sensor:
- name: "raspi_soc_temperature"
state_topic: "raspi/soc/temperature"
It is assumed that a MQTT broker as mosquitto is running and configured in Home Assistant running.
Test first that MQTT is able to communicate.
Create a script that reads and publishes the raspberries SoC temperature:
#! /bin/bash mosquitto_pub -t "raspi/soc/temperature" -m "$(/usr/bin/vcgencmd measure_temp | sed -E "s/temp=([0-9]+\.[0-9]+).*/\1/")" -u<username>-P<password>
sed is used to just get the numerical value. This script could be added to cron
Check in an other console that subscribing is working:
mosquitto_sub -t "raspi/soc/temperature" -u <username> -P <password>
Now it is time to edit /home/homeassistant/.homeassistant/configuration.yaml
mqtt:
sensor:
- name: "raspi_soc_temperature"
state_topic: "raspi/soc/temperature"
In Home Assistant -> Developer Tools -> CHECK CONFIGURATION and reload the YAML
A new entity sensor.raspi_soc_temperature should now appear and be used as in a gauge card.
The payload might be json instead of single data. For every data structured in Json a separate MQTT entry must be done, some data is nested so the path needs to be included. The entries would look as:
sensor:
- name: "raspi_soc_temperature"
state_topic: "raspi/soc/temperature"
- name: "raspi_manager_battery_soc"
state_topic: "raspi/manager"
value_template: "{{ value_json['battery' ].soc }}"
- name: "raspi_manager_power"
state_topic: "raspi/manager"
value_template: "{{ value_json.power }}"
Shelly Mini1PMG3 is not yet directly supported in Home Assistant and has a rather complicated payload to be turned on. Everything is therefore be packed into payload_on and payload_off
switch:
- name: "mini1pmg3"
command_topic: "shelly1pmminig3-5432044f7414/rpc"
payload_on: '{"id": 1, "src": "hass", "method":"Switch.Set", "params":{"id":0,"on":true}}'
payload_off: '{"id": 1, "src": "hass", "method":"Switch.Set", "params":{"id":0,"on":false}}'
retain: false
There is no state_topic and value_template therefore it works just in the publishing direction. To have mosquitto know the payload in case the Shelly Mini1PMG3 is powered off and will be powered on later retain: true must be set.
To have a switch bidirectional, a state_topic must be added, since the switch status is inside json a value_template is required and since the state data is different from command data, state_on and state_off is defined. To work it well during power on an off retain is set to true:
switch:
- name: "mini1pmg3"
command_topic: "shelly1pmminig3-5432044f7414/rpc"
payload_on: '{"id": 1, "src": "hass", "method":"Switch.Set", "params":{"id":0,"on":true}}'
payload_off: '{"id": 1, "src": "hass", "method":"Switch.Set", "params":{"id":0,"on":false}}'
retain: true
state_topic: "shelly1pmminig3-5432044f7414/status/switch:0"
value_template: "{{ value_json.output }}"
state_on: true
state_off: false