Home Assistant - vincios/rpi-setup GitHub Wiki

• Install Python 3

• Follow the official guide

  ⚠️ After Create an account part and before Create the virtual environment part of the guide, it may be necessary install Rust. In this case, switch to homeassistant user and install Rust

  ⚠️ For first launch use hass -v and wait until log scroll stops.

• If necessary, uninstall Rust

• Create the service

Adapted from here.

⚠️ Run these steps as raspi user!

1. Create systemd service

   $ sudo nano -w /etc/systemd/system/[email protected]

2. Paste following text

   [Unit]
   Description=Home Assistant
   After=network-online.target
   
   [Service]
   Type=simple
   User=%i
   WorkingDirectory=/home/%i/.homeassistant
   ExecStart=/srv/homeassistant/bin/hass -c "/home/%i/.homeassistant"
   RestartForceExitStatus=100
   
   [Install]
   WantedBy=multi-user.target

3. Restart Systemd and load new service

   $ sudo systemctl --system daemon-reload
   $ sudo systemctl enable home-assistant@homeassistant
   $ sudo systemctl start home-assistant@homeassistant

4. Add these lines to bash_aliases

   alias ha-start="sudo systemctl start home-assistant@homeassistant"
   alias ha-stop="sudo systemctl stop home-assistant@homeassistant"
   alias ha-restart="sudo systemctl restart home-assistant@homeassistant"
   alias ha-restartlog="sudo systemctl restart home-assistant@homeassistant && sudo journalctl -f -u home-assistant@homeassistant"

To do some configuration operations (edit configuration files, updating application, etc.) you have to switch to the homeassistant user using the following command

$ sudo -u homeassistant -H -s

You can also automate this operation adding the command above in the bash_aliases file. Something such as:

alias ha-login="cd /home/homeassistant && sudo -u homeassistant -H -s"

To update to the latest version of Home Assistant Core follow these simple steps:

$ sudo systemctl stop home-assistant@homeassistant
$ sudo -u homeassistant -H -s

If necessary (see disclaimer), install Rust

$ cd /srv/homeassistant
$ source /srv/homeassistant/bin/activate
$ pip3 install --upgrade homeassistant
$ hass -v

Wait until the application fully loads (it can take up to 30 minutes), then close it (Ctrl-C).

$ exit
$ sudo systemctl start home-assistant@homeassistant

If necessary, uninstall Rust

After a Python update, if you want to update the Home Assistant virtual environment, follow these steps.

• Stop service and login as homeassistant user

   $ sudo systemctl stop home-assistant@homeassistant
   $ sudo -u homeassistant -H -s

• Backup .homeassistant folder

   $ mkdir /home/homeassistant/homeassistant-backup
   $ cp /home/homeassistant/.homeassistant/ /home/homeassistant/homeassistant-backup

• Go to the Home Assistant installation folder and make a backup of the old venv

   $ cd /srv/homeassistant/
   $ mkdir old-venv
   $ mv bin old-venv/
   $ mv include old-venv/
   $ mv lib old-venv/
   $ mv pyvenv.cfg old-venv/

• Now, follow the official installation guide to recreate the virtual environment.

  Notes:

  1. Starts from the python3.8 -m venv . command (change the python version according your new version).

  2. If, necessary (see disclaimer), install Rust

  3. Don't forget to run the hass -v command to reinstall the python packages required by the integratons! Remember that this command can took up to 30 minutes, so be patient.

• If necessary, uninstall Rust

• Check that everything works flawlessy and, then, delete the backup

  $ rm -rf /home/homeassistant/homeassistant-backup

You can activate Advanced Mode under user profile page (click on the user's name at the bottom of the left sidebar).

To edit the configuration.yaml file you have to switch to homeassistant user.

You can also allow your default user (e.g. pi, or the equivalent one) to edit, adding it to the homeassistant group

$ sudo usermod -a -G homeassistant pi

⚠️ Change the pi user with your default one

Make also sure that the .homeassistant folder is writable by the group

$ sudo chmod -R g+w /home/homeassistant/.homeassistant

Follow this guide.

1. Follow Annex: Add custom dynamic configuration, use the following configuration:

   ✨ Click to see the code

   http:
   routers:
       homeassistant:
       rule: Host(`hass.{{ env "DUCKDNS_DOMAIN"}}.duckdns.org`)
       service: "homeassistant"
   
       # Enable the TLS encryption
       # Normally, you should not need to edit this section
       tls:
           certResolver: "duckdnsResolver"
           domains:
           - main: "{{ env "DUCKDNS_DOMAIN"}}.duckdns.org"
               sans:
               - "*.{{ env "DUCKDNS_DOMAIN"}}.duckdns.org"
   
   # Service's urls where the request will be forwarded
   services:
       homeassistant:
       loadBalancer:
           servers:
             - url: "http://127.0.0.1:8123"

2. Add the following lines to the configuration.yaml file

   http:
     use_x_forwarded_for: true
     trusted_proxies:
       - 192.168.1.0/24
       - 127.0.0.1
       - ::1
       - fe80::/64
       - fe00::/64
       - fd00::/64

3. Add the external url to the Home Assistant network configuration (Settings > System > Network)

⚠️ This guide is deprecated if you configure Traefik for external access.

 -- ~/dehydrated/certs/cclouds.duckdns.org  
  |-- cert.csr  
  |-- cert.pem  
  |-- chain.pem  
  |-- fullchain.pem    <---- This is your signed certificate  
  |-- privkey.pem    <---- This is your private key  

Follow the official guide.

1. Install Mosquitto

   $ sudo apt update
   $ sudo apt install mosquitto mosquitto-clients

2. Stop service and edit configuration

   $ sudo /etc/init.d/mosquitto stop

3. Add these lines to the configuration file /etc/mosquitto/mosquitto.conf

   listener 1883
   allow_anonymous false
   password_file /etc/mosquitto/passwd
   

   💡 The file should look like this:

   # Place your local configuration in /etc/mosquitto/conf.d/
   #
   # A full description of the configuration file is at
   # /usr/share/doc/mosquitto/examples/mosquitto.conf.example
   
   pid_file /run/mosquitto/mosquitto.pid
   
   persistence true
   persistence_location /var/lib/mosquitto/
   
   log_dest file /var/log/mosquitto/mosquitto.log
   
   listener 1883
   allow_anonymous false
   password_file /etc/mosquitto/passwd
   
   include_dir /etc/mosquitto/conf.d
   

4. Create the password file and the user mqtt_usr. For this purpose, we'll use the mosquitto_passwd tool that execute both operations in a single line

   $ sudo mosquitto_passwd -c /etc/mosquitto/passwd mqtt_usr

   💡 You can also change the user username as you like. In this case remember to change the username also in the rest of this guide

5. The tool will prompt you to set a password. Type it

6. Start the MQTT service

   $ sudo systemctl enable mosquitto
   $ sudo systemctl start mosquitto

• Now the MQTT borker il listening to the 1883 port. We can test it subscribing to a topic with the mosquitto_sub tool

  $ mosquitto_sub -d -u [MQTT_USERNAME] -P [MQTT_PASSWORD] -t [TOPC]

  💡 Change [MQTT_USERNAME], [MQTT_PASSWORD] and [TOPC] as well.

7. Add the MQTT integration to Home Assistant (via the user interface - the yaml configuration is not supported anymore).

To test the configuration we can subscribe to the homeassistant/status topic

$ mosquitto_sub -d -u mqtt_usr -P [MQTT_PASSWORD] -t homeassistant/status

Restart Home Assistant. You should receive a message like this:

Client mosqsub|20681-raspberry received PUBLISH (d0, q0, r0, m0, 'homeassistant/status', ... (6 bytes))
online

Follow these two guides:

• Guide 1
• Guide 2

From these two guides: guide 1, guide 2.

1. Create Create a new project in the Actions on Google console

   • Open the Actions on Google console

   • Name the project Home Assistant and select language and country

   • Click on the Smart Home card, then click the Start Building button

   • Click Name your Smart Home action under Quick Setup to give your Action a name (Home Assistant will appear in the Google Home app as [test] <Action Name>

   • Click on the Overview tab at the top of the page to go back

   • Click Build your Action, then click Add Action(s)

   • Add your Home Assistant URL:

     https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant
     

     in the Fulfillment URL box, replace the [YOUR HOME ASSISTANT URL:PORT] with the domain / IP address and the port under which your Home Assistant is reachable.

   • Click Save

   • Click the three little dots (more) icon in the upper right corner, select Project settings

   • Make note of the Project ID that are listed on the GENERAL tab of the Settings page

2. Setup Account linking

   • Start by going back to the Overview tab

   • Click on Setup account linking under the Quick Setup section

   • If asked, leave options as they default No, I only want to allow account creation on my website and select Next

   • Then if asked, for the Linking type select OAuth and Authorization Code. Click Next

   • Enter the following:

     • Client ID:

       https://oauth-redirect.googleusercontent.com/r/[YOUR_PROJECT_ID]
       

       (Replace [YOUR_PROJECT_ID] with your project ID from above)

     • Client Secret: Anything you like, Home Assistant doesn’t need this field

     • Authorization URL:

       https://[YOUR HOME ASSISTANT URL:PORT]/auth/authorize
       

     • Token URL:

       https://[YOUR HOME ASSISTANT URL:PORT]/auth/token
       

   • In the Configure your client, type email and click Add scope, then type name and click Add scope again

   • Do NOT check Google to transmit clientID and secret via HTTP basic auth header

   • Click Next, then click Save

3. Enter Action Informations

   • Start by going back to the Overview tab

   • Click on Enter information required for the Actions directory under the Get ready for deployment section

   • Compile Description, Images and Contact details paragraphs

   • In the Privacy and consent paragraph, enter https://home-assistant.io in both fields

   • Click Save

4. Configure the Service Account Key

   • In the Google Cloud Platform Console, go to the Create Service account key page

   • At the top left of the page next to “Google Cloud Platform” logo, select your project created in the Actions on Google console. Confirm this by reviewing the project ID and it ensure it matches

   • Click Create Service Account

   • Into Service Account Name insert homeassistant

   • Compile description field

   • Click CREATE

   • From the Role list, select Service Accounts > Service Account Token Creator

   • Click CONTINUE and then DONE

   • In the main page, click on the newly created account

   • Select KEYS tab

   • Click ADD KEY and Create new key

   • Select JSON and click CREATE

   • Save the downloaded file somewhere

5. Enable HomeGraph API

   • Go to the Google HomeGraph API Console

   • At the top left of the page next to “Google Cloud Platform” logo, select your project created in the Actions on Google console. Confirm this by reviewing the project ID and it ensure it matches

   • Click ENABLE

6. Configure Home Assistant

   • Copy the "Service Account Key" file downloaded in previous step into the .homeassistant folder

   • Create a google.yaml file

   • Add the google_assistant integration configuration in this file, following the documentation. This is an example:

     project_id: home-assistant-367e3
     service_account: !include home-assistant-367e3-5b1e0ab2d7a7.json
     report_state: true
     expose_by_default: false
     entity_config:
       switch.switch_cucina:
         name: "Luce Cucina"
         expose: true
         room: Cucina
       light.luce_camera:
         expose: false  # should be optional if expose_by_default is false

     ⚠️ project_id and service_account are required fields. Write, respectively, the project id noted into step 1 and the "Service Account Key" file (downloaded in step 4) filename

   • Include the google.yaml file into the configuration.yaml file

     google_assistant: !include google.yaml

7. Create the Auto Discovery automation (OPTIONAL)

   💡 If you manually expose your entities through the google.yaml file, you could also skip this part and manually start a device synchronization (through the google_assistant.request_sync service or the command “Ok Google, sync my devices”) each time you expose a new entity

   ⚠️ From 2023: add the automation via the user interface and configure it like below.

   To synchronize Home Assistant devices with the Google Home app without unlinking and relinking an account, you have to call the google_assistant.request_sync service (or say "Ok Google, sync my devices") each time you add a new device in Home Assistant that you wish to control via the Google Assistant integration. To avoid this, you can optionally setup an automation to call this service each time Home Assistant starts.

   • Take note of your Home Assistant user id.

     You can find it in Home Assistant under Configuration > Users > [YOUR_USER_NAME] > ID

   • Copy it in a new field into the .homeassistant/secrets.yaml file (call it, for example, google_agent_user_id)

   • Add this at the end of the .homeassistant/automations.yaml file

     - alias: Google Assistant Sync
       trigger:
       - event: start
         platform: homeassistant
       condition: []
       action:
       - service: google_assistant.request_sync
         data:
           agent_user_id: !secret google_agent_user_id

8. Test your action to generate the draft version Test App

   • Open the Actions on Google console and select the Home Assistant project

   • Select the Develop tab at the top of the page, then click Account linking on the left side

   • In the upper right hand corner select the Test button to generate the draft version Test App. If you don’t see this option, go to the Test tab instead, click on the Settings button in the top right below the header, and ensure On device testing is enabled (if it isn’t, enable it).

   • You will be redirected to the Test tab. Write something into the field on top and press Enter. You will see an error on the right. Don't panic, it's normal.

   ⚠️ You might have to repeat this operation after a period of time, likely around 30 days. You will notice it because device sync (service google_assistant.request_sync call) will fail with an 404 error. For more info, see here.

9. Restart Home Assistant

10. Add the action on Google Home App

    • On your phone, open the Google Home app

    • Click on the + button on the top left corner

    • Select Configure device and Compatible with Google

    • Into the services list you will find [test] Home Assistant

    • Login into your account

      💡 If you see an error like "Unsupported devices", probably there are errors in the google.yaml file (like a wrong entity id in the entity_config field)

    • Go back, you should see all your devices

    • Congratulations! Now configure them

11. BONUS: If you want to allow other household users to add this action to theirs accounts and control the devices, follow this guide.

Python cryptography package (required by Home Assistant) requires Rust toolchain to build the package. So, to install or upgrade Home Assistant we have to install Rust. After that, Rust can also safely uninstalled.

In theory, pip should be able to handle this requirement automatically (using a pre-built wheel package). Unfortunately, for now (raspbian ?) pip does't have this wheel, so it tries to build cryptography package from scratch, returning an error error: can't find Rust compiler. So, in a near future, with a new pip version, installing Rust may be not necesary to install/upgrade Home Assistant.

So, sometime, try to make an Home Assistant upgrade without install Rust. If the upgrade command ends successfully, you don't need Rust anymore. Otherwise, install Rust and retry to upgrade.

Rust toolchain installation is very simple via rustup. Simply run this command from homeassistant's user shell:

$ curl https://sh.rustup.rs -sSf | sh

And choose option 1.

⚠️ RUST MUST BE INSTALLED ON THE homeassistant USER!!

After Home Assistant installation/upgrade is done, Rust is no more necessary and can be deleted with this command:

$ rustup self uninstall

See here.

• [Blueprint] Notify Mobile Companion App Devices

• Verify Home Assistant service status

  $ sudo systemctl status home-assistant@homeassistant

• Start Home Assistant service

  $ sudo systemctl start home-assistant@homeassistant

• Stop Home Assistant service

  $ sudo systemctl stop home-assistant@homeassistant

• Restart Home Assistant service

  $ sudo systemctl restart home-assistant@homeassistant

• Disable Home Assistant service autostart

  $ sudo systemctl disable home-assistant@homeassistant

• Read real time Home Assistant systemlog rows

  $sudo tail -f /var/log/syslog | grep hass

• Read Home Assistant log output

  $ sudo journalctl -f -u home-assistant@homeassistant

Because the log can scroll quite quickly, you can select to view only the error lines

``` bash
$ sudo journalctl -f -u home-assistant@homeassistant | grep -i ‘error’
```

• Verify configuration by manual launch

  $ hass --script check_config –h

Here you can find solution to some Home Assistant issues.

Error: ImportError: /lib/arm-linux-gnueabihf/libm.so.6: version 'GLIBC_2.29' not found (required by /srv/homeassistant/lib/python3.9/site-packages/_miniaudio.abi3.so)

From this issue:

1. Switch to homeassistant user

   $ sudo -u homeassistant -H -s

2. cd /srv/homeassistant

3. Activate the virtual environment ("source bin/activate")

4. Recompile miniaudio (It takes a while for the compile to finish!)

   pip install --ignore-installed miniaudio --no-binary :all:
   

5. Restart HA (actually I restarted the server but that might be overkill)

For some reasons, the hass -v command could stop without give some feedback on the error.

In this case, with homeassistant venv activated, try to start homeassistant with following command

$ /srv/homeassistant/bin/hass -v -c /home/homeassistant/.homeassistant

It should show you the error that have stopped the execution. Probabily, the cause is some package that is missing.

If you have an outdated version of SQLite, try to update it with your system package manager (sudo apt update and sudo apt upgrade).

If this doesn't work (package manager says already up to date) you can try a manual upgrade.

From this suggestion, adapted with this additional comment:

0. Make a backup of the .homeassistant folder!

1. Get the download link of the latest SQLite source code form the official page.

   NB: make sure you choose the autoconf version!

2. Download it to a temporary folder and extract

   $ cd /tmp/
   $ wget https://sqlite.org/2022/sqlite-autoconf-3380500.tar.gz
   $ tar -xvf sqlite-autoconf-3380500.tar.gz
   $ cd sqlite-autoconf-3380500/

3. Compile and install

   $ ./configure
   $ make
   $ sudo make install

The last command above (sudo make install) will output the folder where the new libraries have been installed (should be /usr/local/lib). Note it somewhere.

Try now to launch Home Assistant. If the issue still occour, the cause should be the libraries location. From here:

hass still complained. It turned out to be where the libraries were installed. The old libraries were in /usr/lib/arm-linux-gnueabihf/, whereas the new ones were in /usr/local/lib.

So we have to link the new libraries folder (/usr/local/lib or whatever you've noted from steps above) to Home Assistant, using the LD_LIBRARY_PATH environment variable.

$ sudo systemctl stop home-assistant@homeassistant
$ sudo -u homeassistant -H -s
$ cd /srv/homeassistant
$ source /srv/homeassistant/bin/activate
$ export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
$ hass -v

If all is working fine (the log doesn't show errors and HA's logbook works), you have to persist this modification to the HASS systemd service.

0. Login as pi user

1. Stop Home Assistant

   $ sudo systemctl stop [email protected]

2. Edit the service file

   $ sudo nano -w /etc/systemd/system/[email protected]

3. Add this line to the [Service] section (after the User=%i line)

   Environment="LD_LIBRARY_PATH=/usr/local/lib/"
   

4. Save the file and reload Systemd

   $ sudo systemctl --system daemon-reload

5. Start Home Assistant

   $ sudo systemctl start [email protected]