From Fedora Project Wiki
Line 74: Line 74:
Prefix # means exceuted as root, $ exceuted as user hass.
Prefix # means exceuted as root, $ exceuted as user hass.


=== Server with Python package installer ===
=== Python virtual environment and package installation ===


Installation with pip sometimes compiles Python-modules, hence development packages are needed for runtime environment.
Installation with pip sometimes compiles Python-modules, hence development packages are needed for runtime environment.
Line 104: Line 104:
  # chown hass:hass /etc/authbind/byport/{80,443}
  # chown hass:hass /etc/authbind/byport/{80,443}


=== Shell ===
=== HA remote shell ===


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

Revision as of 18:58, 7 August 2023

Home Assistant (HASS) is a localized, open source home automation server system that doesn't depend on any external cloud service nor network connections, thou it can use them. It has a web as well mobile device (iPhone, Android, tablets) user interfaces for different use cases. However, there is no native GUI user interface (X11, Wayland, Qt/GTK) for embedded local displays. It's written in Python and it has wide home automation hardware support, called integrations.

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 who need them.

Hardware

Since the whole idea is to have localized home automation system, it 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 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.

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.

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.

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.

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 requirements are announced in release notes. Current required Python versions:

Home Assistant Python
2023.7 3.10
2023.8 3.11

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

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.

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.

Prefix # means exceuted as root, $ exceuted as user hass.

Python virtual environment and package installation

Installation with pip sometimes compiles Python-modules, hence development packages are needed for runtime environment. 

# dnf install -y python3.10 python3.10-devel python3-pip openssl authbind gcc

Python package name is homeassistant. 

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

Python virtual environment and pip package installation: 

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

Since version 2023.5 and onwards the voice modules need the following modules (instructions): 

$ pip install piper piper-tools
$ TMPDIR=/var/tmp pip --no-cache-dir install --upgrade openai-whisper


Authbind configuration: 

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

HA 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
ExecStart=/usr/bin/authbind --deep /srv/hass/bin/hass -c "/home/hass/.homeassistant"
RestartForceExitStatus=100

[Install]
WantedBy=multi-user.target

# chkconfig hass on
# service hass start


SELinux

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
# service hass restart

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 requirement has to be satisfied: 

# dnf install -y python3.11 python3.11-devel

Versioning different virtual environments into own direcotories 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.11 
# cd /srv/hass-py3.11
# chown hass:hass hass-py3.11
# su - hass
$ cd /srv/hass-py3.11
$ python3.11 -m venv .
$ source bin/activate
(hass-py3.11) $ pip install homeassistant homeassistant-cli
Collecting homeassistant
  Downloading homeassistant-2023.8.0-py3-none-any.whl (28.1 MB)
     |████████████████████████████████| 28.1 MB 85 kB/s
  ....

Optional voice packages: 

(hass-py3.11) $ pip install piper piper-tools
(hass-py3.11) $ TMPDIR=/var/tmp pip --no-cache-dir install --upgrade openai-whisper

And finishing up: 

(hass-py3.11) $ exit
# mv hass hass-py3.10
# ln -s hass-py3.11 hass
# service hass restart

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

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

default_config:

http:
  server_port: 80

User interfaces

Console

System running HASS-instance (processes, database etc) does not have any user interface.

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

  • Apple iPhone and tablet client in Apple Store.

Desktop

Currently a real Linux desktop widgets and integration is still missing.

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.

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 to share common state and data.

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.

External links

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