Installation of Home Assistant

Lars Jönsson 2025-01-20

Information about how to install Home Assistant on a Raspberry Pi. It is based on the instructions at:

Install Home Assistant

Install image

Install the image according to Install Home Assistant Operating System.

Workaround for headless usage

On some newer Raspberry Pi 4 boards, Home Assistant seems to have a problem to boot without a screen attached to the HDMI connector. To prevent this problem, ensure that the following line is present in the /config.txt file, on the boot partition of the SD card.

hdmi_force_hotplug=1

Normally, the following lines are present in the /config.txt file. Just follow the instruction in the file and uncomment the line.

# uncomment if hdmi display is not detected and composite is being output
#hdmi_force_hotplug=1

Razberry Z-wave (optional)

The Razberry Z-wave board uses the UART that is normally used by Bluetooth. By using a device overlay called miniuart-bt, Bluetooth will use another UART freeing up the UART at /dev/ttyAMAO to be used by the Razberry board. Ensure that the following line is present in the /config.txt file, on the boot partition of the SD card.

dtoverlay=miniuart-bt

The line is normally present in the /config.txt file, but commented-out. Just uncomment the line.

#dtoverlay=miniuart-bt

More information is available at:

• Home Assistant - RAZBERRY BOARD
• Raspberry Pi - config.txt
• Raspberry Pi - UART configuration

Configuration

Using the GUI

The WLAN and IP address can be configured in the GUI during Configuration after startup, but using a USB stick (see below) is a simpler solution.

Using a USB stick

Format a USB stick to FAT32 with the volume name CONFIG.

Wireless LAN WPA/PSK

Create a folder named network in the root of the newly-formatted USB stick.

Within that folder, create a file named my-network without a file extension. Insert the following into the file. Replace MY_SSID with the SSID of the network and MY_WLAN_SECRET_KEY with the secret key.

[connection]
id=my-network
uuid=72111c67-4a5d-4d5c-925e-f8ee26efb3c3
type=802-11-wireless

[802-11-wireless]
mode=infrastructure
ssid=MY_SSID
# Uncomment below if your SSID is not broadcasted
#hidden=true

[802-11-wireless-security]
auth-alg=open
key-mgmt=wpa-psk
psk=MY_WLAN_SECRET_KEY

[ipv4]
method=auto

[ipv6]
addr-gen-mode=stable-privacy
method=auto

Static IP (optional)

Replace the following configuration in the my-network file:

[ipv4]
method=manual
address=192.168.1.111/24;192.168.1.1
dns=8.8.8.8;8.8.4.4;

For address, the value before the semicolon is the IP address and subnet prefix bitlength. The second value (after the semicolon) is the IP address of the local gateway.

First start of the board

• Plug in the SD card into the Raspberry Pi.

• Optionally plug in the configuration USB stick.

• Connect your power supply to the Raspberry Pi.

• The Raspberry Pi will now boot up, connect to the Internet and download the latest version of Home Assistant. This will take about 20 minutes.

• Home Assistant will be available at http://homeassistant.local:8123. If you are running an older Windows version or have a stricter network configuration, you might need to access Home Assistant at http://homeassistant:8123 or http://X.X.X.X:8123 (replace X.X.X.X with your Pi’s IP address).

• If you used a USB stick for configuring the network, you can now remove it.

Configuration after startup

When the installation is ready, you will prompted to create an user account. Create it and log in.

The WLAN and IP address can be setup now if not already configured.

Configure the home location.

Add-ons

The following add-ons are more or less a must, to be able to manage the Home Assistant in a simple way.

• File editor
• Terminal & SSH

The following add-ons are needed to be able to use Tellstick and Zigbee:

• Tellstick
• deCONZ
• Z-Wave JS

The Z-Wave integration built into Home Assistant is deprecated and replaced by the Z-Wave JS add-on. The work is still in progress, but most of the functionality is already implemented and it should be used in all new installations.

File editor add-on

The file editor is used for editing the configuration files. Even though many things can be configured by using the GUI, some things are still configured via files. Everything (or almost everything) configured via the GUI is put into files that can be edited by the File editor.

Install the add-on and start it. Enable Show in sidebar. No configuration is needed for normal use.

Terminal & SSH add-on

Sometimes it is needed to login to the CLI of Home Assistant. This add-on enables login via SSH.

This add-on is only availble if the user is set to Advanced mode.

Install the add-on. Some configuration is necessary. You need enable the port for external access. You can just enter 22 as value or any other value like you want. Enter authorized_keys (preferred) or password. Start the add-on.

Standard SSH access

Login as root to either homeassistant.local or to the IP address (X.X.X.X) of Home Assistant.

ssh root@homeassistant.local

  --- or ---

ssh root@X.X.X.X

Debug SSH access

Sometimes it is vital to access the OS of Home Assistant for debug purposes. More information is available at Debugging the Home Assistant Operating System.

Install the public key to Home Assistant by putting the file on an USB stick that is named CONFIG. The previously used USB stick can be reused. Put the public key in a file named authorized_keys on the root of the USB stick. Connect the USB to the board. Either use SSH CLI command ha os import or reboot the board to update copy the public key to the board.

Port 22222 is used for debug login. Login as root to either homeassistant.local or to the IP address (X.X.X.X) of Home Assistant.

ssh root@homeassistant.local -p 22222

  --- or ---

ssh root@X.X.X.X -p 22222

Tellstick add-on

Install the add-on. All switches that are controlled by Tellstick needs to be configured.

Example:

devices:
  - id: 1
    name: Balkong
    protocol: arctech
    model: 'selflearning-switch:nexa'
    house: '231893'
    unit: '1'

The configuration.yaml file also needs to be updated to include Tellstick:

# Example configuration.yaml entry
tellstick:
    host: core-tellstick
    port: [50800, 50801]

Sensors are auto-detected by Tellstick, but the id of each sensor needs to be added to configuration.yaml.

# Example configuration.yaml entry
sensor:
  - platform: tellstick
    only_named:
      - id: 222
        name: Gästrum
      - id: 117
        name: Balkong
      - id: 213
        name: Sovrum

Use the list-sensors function to get the id of all sensors. It is described in the Service calls section in the add-on documentation of Tellstick.

Self-learning remote controls

The house code and other codes of self-learning remote controls can be retrieved in Home Assistant by connecting directly to the tellstick add-on. It is shorly described in this blog post.

To obtain the codes from the remote control, run the following command in the CLI:

nc core-tellstick 50801

Then you activate the sensor and what comes up looks something like this:

16:TDRawDeviceEvent95:class:command;protocol:arctech;model:selflearning;house:41819134;unit:15;group:0;method:turnon;i1s

There you can read everything you need to enter in the TellStick configuration:

devices:
  - id: 6
    name: [Your name for it]
    protocol: arctech
    model: 'selflearning-switch:nexa'
    house: '41819134'
    unit: '15'

deCONZ add-on

This is used to control a Zigbee network with ConBee II.

Install the add-on and configure it. The device needs to be set and if VNC is used the vnc_password also needs to be set.

device: /dev/ttyACM0
vnc_password: MY-SECRET

When using VNC, the port number have to be set in the Network section of the add-on configuration. It is adviced to use 5900.

By default, Home Assistant has the discovery integration enabled, which automatically discovers this add-on. Navigate to Configuration -> Integrations page after starting this add-on to configure the deCONZ integration.

Z-Wave JS add-on

This add-on replaces the Z-Wave integration included in Home Assistant, which is deprecated. It is based on the Z-Wave JS driver and is the recommended Z-Wave integration for Home Assistant. If you want to migrate from the old Z-Wave, more information is available at Migrating from previous Z-Wave implementations.

Install the add-on and configure it. The device and network_key needs to be set.

device: /dev/ttyAMA0
network_key: MY-NETWORK-KEY

If you are using an already configured Z-Wave network (migrating), the old network key (i.e. 2232666D100F795E5BB17F0A1BB7A146) should be used (see Migrating from previous Z-Wave implementations). Otherwise you need to reset controller and all devices, and set up the network again.

Start the add-on and add the Z-Wave JS integration to Home Assistant, see documentation: https://www.home-assistant.io/integrations/zwave_js

Configure Home Assistant

If you have an old Home Assistant you can copy the configuration files. The easiest way is to use File edit and copy the desired content to the new Home Assistant.

Another way is to restore a snapshot from the old Home Assistant, but it requires that both Raspberry Pi:s are of the same sort and that everything on the old Home Assistant is updated to the latest versions.

Setup of SSL/TLS is covered in a separate topic.