From Fedora Project Wiki

Revision as of 11:52, 3 November 2024 by Mj41 (talk | contribs) (Fix default config path)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Home Assistant (HASS) is a localized, open source home automation server system. It doesn't depend on any external cloud service nor network connections, even it can use them. It has a web as well mobile device (iPhone, Android, tablets) remote user interfaces for different use cases. It's written in Python and it has wide home automation hardware support, called integrations which provide information and can perform actions based on automations and user interactions. A standard upstream target installation uses Debian Linux distribution, but Home Assistant can be used on Fedora and its deriatives with few limitations.

Home Assistant project was started in 2013 by Paulus Schoutsen and project is supported by Nabu Casa Inc that provides full-time developers and related services for end users.

Hardware

Since the whole idea is to have localized home automation system, Home Assistant typically requires a local hardware to run on. From the beginning the target architechture has been ARM and Rasperry Pi -boards. Company behind Home Assistant, the Nabu Casa itself sells(?) Home Assistant green and Yellow which is a Rasperry Pi with CM4 module.

HASS has always had CCTV-features which are CPU-intensive and the more powerful Raspis help with those features. During the 2023 they added voice regocnition and syntehsis features which need more computing power.

Alternative to bare metal, installation images also include pre-made containers images (KVM or Docker). Provided kvm-virtual machine images do not run on enterprise Linux (requires ARM-arch, now, in 2023) KVM but HASS works fine if manually installed into system that runs inside KVM or similar. Remote virtual environment poses problem how the remote HASS can access local house interfaces like sensors and actuators?

Enterprise Linux vs Fedora

By its nature home automation installations are used for long periods which conflicts with the fast pace of Linux operating system life cycles. HASS is also written with the latest Python features which are not available in enterprise type of Linux variants. There are no premade packages for any Fedora camp distribution. These combined it's hard to install and get running on enterprise Linux and Fedora itself would have to be constantly upgraded.

At the moment looks like the Fedora Server OS-releases (bare metal or virtual installation) provide all the requirements, the somewhat recent Python versions and slower OS release cycle.

Versions

Home Assistant has monthly release interval with minor updates inside a month. Versions have year and month like 2024.5 and minor updates add third digit like 2024.5.2.

HASS Python pip-packages are available in different Python version repositories, but older Python versions have old HASS versions which don't get updated anymore. They install but are years old and should not be used as all the documentation, discussions and integrations have moved on. The correct way to solve this is to change Python, that is a distribution version (enterprsise vs fedora server) with newer Python. This also applies inside inside the distribution release itself, when HASS project moves to new Python version, the used Python virtual environment is tied to some particular Python minor version and its pip only sees the last HASS-release when newer ones are only released to given new python minor repository.

New Python requirements are announced in release notes. Table lists the HASS versions that started using given Python version, the earlier version support is dropped after few releases. Currently required Python versions:

Home Assistant Python
2023.7 3.10
2023.8 3.11
2024.2 3.12

The exact Python version should be used since the required version and Fedora's major version might not be the same.

Installation types

For the newcomers this is confusing and worth of explaning simply as possible.

Project has produced something called core and supervisor. Core contains the actual Home Assistant and can be used without a supervisor. Supervisor is an addition to the core. It maintains core and the surrounding operating system via user interface without need for shell access (configuration and package installations).

System without supervisor has also some functional limitations, mainly when installing additional features to the core. The whole idea of Home Assistant is to integrate hundreds of different eletrical systems and IoT-hardware into one complete system. Only few of them are supported by the core, rest are installed via these additional features.

Managing system services that HASS calls add-ons is not possible through the plain core user interface (Add-ons entry is not visible in Settings menu). However these add-ons like voice processes or other system daemons can be managed via shell session as usual.

Some of the additional features are available through HACS (HA Community Store), some directly from Github service for example.

Majority of installations are OS-type and OS-type containers. For Fedora camp people using familar Fedora or deriative as underlying distribution saves time.

Home Assistant OS

Project provides many pre-made full installation images (from bare metal to the user interface) where a Rasperry Pi native hardware is the reference target. That's very easy installation type if the RasPi is available and the intended platform.

All full installations include Debian Linux and are called just plain Home Assistant or Home Assistant OS which mean operating system + core + superviser regardless where it runs (raspi, virtual machine).

Home Assistant Core

Alternative to pre-made installation images, there are manual installations for operating systems which include core, but not supervisor. For these installations there are few methods available:

  • python-package via pip (system python or venv)
  • git checkout (system python or venv)

In Linux distribution that supports required Python, Home Assistant can be manually installed with Python package installer pip tool. Python package-method is also easy to update with HASS monthly updates.

Manual installation has some limitations, some third-party web-installation methods don't work. While the HACS-itself works fine, HACS custom repository add -functionality does not.

Home Assistant Supervised

Lastly, there is manual supervised installation type that includes core and supervisor but it requires Debian and Docker, which doesn't apply here in Fedora project. It is a manual installation that results the same as pre-installed images provide and has no core's limitations.

Further reading about installation types and their limitations:

Installing core type

These instructions are for the Home Assistant Core -installation type described before, using Python virtual enviroment and Python-package pip-installation method on Fedora Server distribution.

At the moment, there are no premade RPM-packages except the shell tool. Packaging and maintaining those packages would require a lot of work since HASS releases an update in every month.

In the following shell examples, prefix # means exceuted as root, $ exceuted as user hass.

Python virtual environment and packages

Installation with pip sometimes compiles Python-modules, hence development packages are needed for runtime environment. The latest Python version should be used. 

# dnf install -y python3.12 python3.12-devel python3-pip openssl authbind gcc gcc-c++


System needs a role user and some installation directory with ownership and access rights: 

# adduser hass
# mkdir /srv/hass
# chown hass:hass /srv/hass

Python virtual environment and pip package installation (as role user hass), Python package name is homeassistant: 

# su - hass
$ mkdir ~/.homeassistant
$ cd /srv/hass
$ python3.12 -m venv .
$ source /srv/hass/bin/activate
$ pip install homeassistant
$ pip install homeassistant-cli
$ echo >> ~/.bashrc; echo "source /srv/hass/bin/activate" >> ~/.bashrc

Next installation steps continue in Configuration chapter.

Once the system is running, there is an variable that shows is the system running latest HASS-version of PIP-packages or not: 

binary_sensor.python_package_index_pypi_update_available

Updating

HASS is updated monthtly or even more frequently. 

# su - hass
$ cd /srv/hass
$ source ./bin/activate
$ pip install --upgrade pip
$ pip install --upgrade homeassistant
$ exit
# systemctl restart hass

For base OS, the standard Fedora upgrade instructions can be followed:

Upgrading

If HASS-project moves to a new Python minor version, a new virtual environment must be created and used with the old configuration files, which probably reside inside the process role user's home directory (like /home/hass/.homeassistant/). Upgrading is a major change, potential source of problems and backups are recommended before starting.

First the new Python and other new requirements have to be satisfied: 

# dnf install -y python3.12 python3.12-devel gcc-c++

Versioning different virtual environments into own directories and using a symlink pointing to the current one is probably the least laborious way to maintain different versions. An example of new environment creation: 

# mkdir /srv/hass-py3.12 
# cd /srv
# chown hass:hass hass-py3.12
# su - hass
$ cd /srv/hass-py3.12
$ python3.12 -m venv .
$ source bin/activate
(hass-py3.12) $ pip install --upgrade pip
(hass-py3.12) $ pip install homeassistant homeassistant-cli
Collecting homeassistant
  ...
  Downloading homeassistant-2024.2.5-py3-none-any.whl (34.9 MB)
  ...

And finishing up: 

(hass-py3.12) $ exit
# cd /srv
# systemctl stop hass
# mv hass hass-py3.11
# ln -s hass-py3.12 hass
# systemctl start hass
# systemctl status hass

Restarting the service takes time. After restart, Settings -> Integrations and HACS -> Integrations should be checked if there are any updates. Also Notifications may have startup issues, for example outdated Yaml configuration etc.

Installing supervised type

Still unclear would it need porting to Fedora and RPM-based distribution since project relies heavily on Debian.

Configuration

Common configuration steps for all installation types.

Database

Database can be default local SQLite file or networked remote MariaDB / MySQL, Postgresql or SQlite. Remote database adds complexity to a critical automation system but also releases space and write activity from flash-storage typically used in embedded computers. Selecting a database is done during initial installation as migration from one to another is not supported.

Network

By default hass binds to TCP 8123 port, but with authbind it can be set to 80. This must be set in systemd service file as well in HASS configuration where to bind the port number.

Authbind configuration is required to bind below 1023 port numbers: 

# touch /etc/authbind/byport/{80,443}
# chmod 777 /etc/authbind/byport/{80,443}
# chown hass:hass /etc/authbind/byport/{80,443}

Add http service to firewalld: 

# firewall-cmd --list-all
# firewall-cmd --add-service http
# firewall-cmd --add-service=http --permanent

See Control of System Accessibility by firewalld for Fedora firewall instructions.

The main configuration file in hass user home directory is /home/hass/.homeassistant/configuration.yaml and to bind it to 80 port: 

default_config:

http:
  server_port: 80

Network configuration settings include TLS-options if https is needed.

Remote shell

On any Fedora or enterprise type of Linux there is a RPM package: 

# dnf install -y home-assistant-cli


homepage explains the required $HASS_SERVER and $HASS_TOKEN variables.

Systemd

Systemd file /etc/systemd/system/hass.service. It assumes the manual installation directory. 

[Unit]
Description=Home Assistant
After=network-online.target

[Service]
Type=simple
User=hass
WorkingDirectory=/home/hass/.homeassistant
Environment="PATH=/srv/hass/bin:/home/hass/.homeassistant/bin:/usr/sbin:/usr/bin"
ExecStart=/usr/bin/authbind --deep /srv/hass/bin/hass -c "/home/hass/.homeassistant"
RestartForceExitStatus=100

[Install]
WantedBy=multi-user.target


Finally after all configuration is finished, a restart is needed: 

# chkconfig hass on
# systemctl restart hass

SELinux

File labels in /srv/hass must be set for the application to be started by systemd: 

# semanage fcontext -a -t bin_t "/srv/hass/bin(/.*)?"
# restorecon -R /srv/hass

User interfaces

HASS architecture also has a problem, one single home is designed to have one HASS-instance with one database. Multiple user interfaces in web and mobile devices use remote user interface protocol (Websocket, REST) but are not HASS-instances themselves. Two separate instances don't have means (protocol) to communicate and share common state and data.

Console

System running HASS-instance (processes, database etc) does not have any native graphical user interface (X11, Wayland, Qt/GTK) for embedded local displays.

Web

Web interface is in port 8123 by default which is blocked by the firewalld service. Instructions above show how to relocate the port into 80.

Mobile devices

Mobile device client is called as companion app and installed from device application store.

  • Apple iPhone and tablet client in Apple Store.
  • Android play store
  • Apple iOS app got Carplay support for vehicles in early 2024.

Desktop

Currently there is no desktop application, system is used remotely with web browser. It would make sense to have desktop widgets and integration (KDE, GNOME, Windows, macOS) but there is none.

Wall displays

Home being a closed multiuser environment where everyone has access to mostly everything, it makes sense to have wall mounted displays to interact with the house. People have built these but there is no widely accepted solution for walls yet.

Even that wall displays might have ARM-computers built in and it makes it tempting to install Home Assistant to them, they need to run some other OS with web browser or mobile application - not the Home Assistant instance.

Security

If the system is connected to the Internet, it should be secured properly to prevent unauthorized use.

Project has a page for it, but it's not nearly enough:

See also

Terminology

  • Home Assistant - project name and a complete system running Home Assistant OS.
  • Home Assistant OS - complete system installed from pre-made installation images: os + core + supervisor.
  • Home Assistant core - same as core, a system without supervisor.
  • HASS - abbreviation of Home ASSistant.
  • HAOS - abbreviation of Home Assistant Operating System.
  • hassio - old name that was changed to Home Assistant OS (hass.io).
  • core - base daemon software without supervisor.
  • supervisor - management software supervising core daemons.
  • supervised - type of system that runs core under supervisor.
  • addon - a normal Linux OS-level system daemon/service accessible via HASS settings.

External links

Retrieved from "https://fedoraproject.org/w/index.php?title=Home_Assistant&oldid=723655"