Home Assistant

Home Assistant is an open source home automation software that puts local control and privacy first. Powered by a worldwide community of tinkerers and DIY enthusiasts.

Install

Install the home-assistant package. This is installing the core flavor of Home Assistant.

Home Assistant Supervised

Refer to Home Assistant Supervised.

Configuration

Configuration files are stored at /var/lib/hass/. If no configuration exists, a default configuration will be written at startup.

Usage

To start Home Assistant, start/enable home-assistant.service.

The first start may take up to 20 minutes because the required packages will be downloaded and installed.[1] You can see the progress in the logs.

Tip: Follow the first-time update process using journalctl:

# journalctl -fu home-assistant

By default, the web interface is available at http://localhost:8123.

Note: The web interface requires the home-assistant-frontend Python package.

The Backup restore function is not available in the UI. The backup can be restored by extraction of the tar.gz file in the Backup as user hass:

# tar --strip-components=1 -xzf homeassistant.tar.gz -C /var/lib/hass

Using MariaDB

By default, SQLite is used for the recorder/history integration within Home Assistant. A noticeable performance boost is achievable by using MariaDB (especially for larger setups). Home assistant uses SQLAlchemy which means that any backend is supported, like MySQL, MariaDB, PostgreSQL, or MS SQL Server. Here we only discuss MariaDb, for others please refer to the recorder integration documentation.

If not already installed, please refer to MariaDB for installation details.

Install the python-mysqlclient package dependency.

Create a new database, the example below shows a single username per service, with wildcard access to all databases having the username as a prefix e.g.:

$ mysql -u root -p

CREATE USER 'username'@'localhost' IDENTIFIED BY 'some_pass' ;
CREATE DATABASE username;
GRANT ALL PRIVILEGES ON username.* TO 'username'@'localhost';
FLUSH PRIVILEGES;
quit;

Add to your configuration file:

/var/lib/hass/configuration.yaml

recorder:
  db_url: !secret recorder_mariadb_url

Add to your secrets file (if not using a Unix socket, see the recorder integration documentation for alternative URLs):

/var/lib/hass/secrets.yaml

recorder_mariadb_url: "mysql://USER:PASSWORD@localhost/DATABASE?unix_socket=/var/run/mysqld/mysqld.sock&charset=utf8mb4"

Finally, restart the home-assistant.service. The database should now start to populate. For more information refer to the recorder integration documentation.

Using Postgresql

You need to install the python module called psycopg2 into the venv of hass.

You will need to add a systemd drop-in file:

/etc/systemd/system/NetworkManager.service.d/postgresql.conf

[Service]
ExecStartPre=/var/lib/hass/.venv/bin/python -m pip install psycopg2

This will make sure psycopg2 is a module that is always installed.

Troubleshooting

No access to USB devices

In the default installation, the Home Assistant may not have the necessary access to work with some devices, such as a Zigbee USB dongle. This is because such devices are controlled by the uucp system group.

Edit the home-assistant.service and add SupplementaryGroups=uucp to the [Service] section so that the default hass user belongs to the right group.

Then, after a daemon-reload and restart of home-assistant.service it should be up and running.[2]

Bluetooth integration not working

If you are experiencing issues with Bluetooth integration and the below error message appears in your log it is because that the Bluetooth integration connects over dbus and there is an old systemd bug.

Config entry 'Bluetooth' for bluetooth integration not ready yet: DBus connection broken: [Errno 32] Broken pipe; try restarting `bluetooth` and `dbus`; Retrying in background

A solution is to switch to dbus-broker.

Alternatively, add a system user and group hass:

# useradd -U -r -s /usr/bin/nologin hass

and use a drop-in file for home-assistant.service

/etc/systemd/system/home-assistant.service.d/override.conf

[Service]
DynamicUser=false

Note that in some cases, this prevents the service from starting due to a permission issue.

Separately, the Passive BLE Monitor integration requires additional permissions for python to read raw data from the Bluetooth adapter. The integration's documented method of sudo setcap 'cap_net_raw,cap_net_admin+eip' `readlink -f \`which python3\`` is insufficient because the Arch home-assistant package runs python in a virtual environment as a dynamic user. To get around this, add to the service override file:

/etc/systemd/system/home-assistant.service.d/override.conf

[Service]
AmbientCapabilities=CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_RAW

See this user forum discussion for more information.

ModuleNotFoundErrors in logs

If Home Assistant is broken after a system package upgrade, it could be caused by a bad interaction between the system packages and Home Assistant's managed Python libraries. To reset Home Assistant's Python libraries and reinstall them from scratch, delete the modules directory:

# rm -r /var/lib/hass/deps/lib

Then restart home-assistant.service.

If the first restart produces more ModuleNotFoundErrors, it might be necessary to a second restart. Home Assistant will detect that its modules are missing and automatically reinstall them.