HASSbian Image for Raspberry Pi


The easiest way to install Home Assistant on your Raspberry Pi is by using HASSbian: a Raspberry Pi image with Home Assistant built-in. The image will install the latest version of Home Assistant on initial boot (~5 minutes).

  1. Download the latest image
  2. Flash the image to an SD card:
  3. Ensure your Raspberry Pi has access to the internet.
  4. Insert SD card to Raspberry Pi and turn it on. Initial installation of Home Assistant will take about 5 minutes.

These instructions are also available as a video.

Home Assistant will now be available by navigating with a browser to http://ip-address-of-pi:8123. The default username is pi and password is raspberry (please change this by running passwd). The Home Assistant configuration is located at /home/homeassistant/.homeassistant/.

The following extras are included on the image:

  • GPIO pins are ready to use.
  • Mosquitto MQTT broker is installed (not activated by default).
  • Bluetooth is ready to use (supported models only, no Bluetooth LE).

Some extra tips:

Technical Details

  • Home Assistant is installed in a virtual Python environment at /src/homeassistant/
  • Home Assistant will be started as a service run by the user homeassistant
  • The configuration is located at /home/homeassistant/.homeassistant

Managing your HASSbian installation

Login to HASSbian on the Raspberry Pi

To login to your Raspberry Pi running HASSbian your going to be using a ssh client. Depending on your platform there are several alternatives for doing this. Linux and Max OS generally have a ssh client installed. Windows users are recommended to download and install the ssh client Putty.

Connect to the Raspberry Pi over ssh. Default user name is pi and password is raspberry.
Linux and Mac OS users execute the following command in a terminal.

$ ssh [email protected]

Windows users start Putty, enter the IP address of the Raspberry Pi in the Host name field and port 22 in the Port field. Then click Open and a terminal window will open. Enter the credentials. Default user name is pi and password is raspberry.

Optionally, starting with Windows 10 anniversary update, you can use the built-in ‘Bash on Windows’ to use SSH if you have enabled Developer mode and have installed the “Windows Subsystem for Linux (beta)” feature.

Start/Stop/Restart Home Assistant on HaSSbian

Log in as the pi account account and execute the following commands:

$ sudo systemctl stop [email protected] 

Replace stop with start or restart to get the desired functionality. To get the current state of the homeassistant.service replace stop with status.

Update Home Assistant on HASSbian

Log in as the pi account and execute the following commands:

$ sudo systemctl stop [email protected] 
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ pip3 install --upgrade homeassistant
$ exit
$ sudo systemctl start [email protected]

This will in order do the following:

  • Stop the Home Assistant service running on HASSbian
  • Open a shell as the homeassistant user running the Homeassistant service and that has ownership over the Home Assistant installation.
  • Change into the virtual Python environment at /src/homeassistant/ containing the Home Assistant installation.
  • Upgrade the Home Assistant installation to the latest release.
  • Exit the shell and return to the pi user.
  • Restart the Home Assistant service.

Manually launch Home Assistant on HASSbian

Log in as the pi account and execute the following commands:

$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ hass

This will start Home Assistant in your shell and output anything that ends up in the log and more into the console. This will fail if the Home Assistant service is already running so don’t forget to stop it first.

Check your configuration on HASSbian

Log in as the pi account and execute the following commands:

$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ hass --script check_config

This will output any errors in your configuration files to console.

Read the Home Assistant log file on HASSbian

Log in as the pi account and execute the following commands:

$ sudo su -s /bin/bash homeassistant
$ cd /home/homeassistant/.homeassistant
$ nano homeassistant.log

This will in order do the following:

  • Open a shell as the homeassistant user.
  • Change directory to the Home Assistant configuration directory.
  • Open the log file in the nano editor.

Optionaly, you can also view the log with journalctl. Log in as the pi account and execute the following commands:

$ sudo journalctl -fu [email protected]

Edit the Home Assistant configuration on HASSbian

Log in as the pi account and execute the following commands:

$ sudo su -s /bin/bash homeassistant
$ cd /home/homeassistant/.homeassistant
$ nano configuration.yaml

This will in order do the following:

  • Open a shell as the homeassistant user.
  • Change directory to the Home Assistant configuration directory.
  • Open the configuration file in the nano editor.

It’s generally recommended that you read the Getting started guide for how to configure Home Assistant.

Upgrade and update HASSbian

HASSbian is based on Raspbian and uses the same repositories. Any changes to Raspbian will be reflected in HASSbian. To update and upgrade system packages and installed software (excluding Home Assistant) do the following. Log in as the pi account and execute the following commands:

$ sudo apt-get update
$ sudo apt-get upgrade

Press Y to confirm that you would like to continue.

USB device permissions

When using some USB devices users have to give dialout permission to the user homeassistant and restart.

$ sudo usermod -a -G dialout homeassistant
$ sudo reboot

Troubleshooting

If you run into any issues, please see the troubleshooting page. It contains solutions to many of the more commonly encountered issues.

In addition to this site, check out these sources for additional help:

Next step: Configuring Home Assistant »