(→Upgrading: upgrade pip first) |
|||
(15 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
'''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 | '''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) 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 [https://www.nabucasa.com/ Nabu Casa Inc] that provides full-time developers and related services for end users. | Home Assistant project was started in 2013 by '''Paulus Schoutsen''' and project is supported by [https://www.nabucasa.com/ Nabu Casa Inc] that provides full-time developers and related services for end users. | ||
== Hardware == | == Hardware == | ||
Since the whole idea is to have localized home automation system, | 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 [[Architectures/ARM|ARM]] and [[Architectures/ARM/Raspberry_Pi|Rasperry Pi]] -boards. Company behind Home Assistant, the [https://www.nabucasa.com/ Nabu Casa] itself sells(?) [https://www.home-assistant.io/green/ Home Assistant green] and [https://www.home-assistant.io/yellow/ 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 [[Home Assistant/Voice|voice]] regocnition and syntehsis features which need more computing power. | HASS has always had CCTV-features which are CPU-intensive and the more powerful Raspis help with those features. During the 2023 they added [[Home Assistant/Voice|voice]] regocnition and syntehsis features which need more computing power. | ||
Line 16: | Line 16: | ||
At the moment looks like the [https://getfedora.org/en/server/ Fedora Server] OS-releases (bare metal or virtual installation) provide all the requirements, the somewhat recent Python versions and slower OS release cycle. | At the moment looks like the [https://getfedora.org/en/server/ 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 [https://www.home-assistant.io/faq/release/ 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. | |||
New requirements are announced in [https://www.home-assistant.io/blog/categories/release-notes/ 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: | 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 [https://www.home-assistant.io/blog/categories/release-notes/ 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: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
Line 81: | Line 83: | ||
Installation with pip sometimes compiles Python-modules, hence development packages are needed for runtime environment. The latest [[#Python versions|Python version]] should be used. | Installation with pip sometimes compiles Python-modules, hence development packages are needed for runtime environment. The latest [[#Python versions|Python version]] should be used. | ||
# dnf install -y python3.12 python3.12-devel python3-pip openssl authbind gcc | # dnf install -y python3.12 python3.12-devel python3-pip openssl authbind gcc gcc-c++ | ||
Line 100: | Line 102: | ||
Next installation steps continue in [[#Configuration|Configuration]] chapter. | Next installation steps continue in [[#Configuration|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 === | === Updating === | ||
Line 110: | Line 115: | ||
$ pip install --upgrade homeassistant | $ pip install --upgrade homeassistant | ||
$ exit | $ exit | ||
# | # systemctl restart hass | ||
For base OS, the standard Fedora upgrade instructions can be followed: | For base OS, the standard Fedora upgrade instructions can be followed: | ||
Line 119: | Line 124: | ||
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. | 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 | First the new Python and other new requirements have to be satisfied: | ||
# dnf install -y python3.12 python3.12-devel | # 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: | 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: | ||
Line 140: | Line 145: | ||
And finishing up: | And finishing up: | ||
(hass-py3.12) $ exit | (hass-py3.12) $ exit | ||
# cd /srv | |||
# systemctl stop hass | |||
# mv hass hass-py3.11 | # mv hass hass-py3.11 | ||
# ln -s hass-py3.12 hass | # 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. | 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. | ||
Line 156: | Line 164: | ||
Common configuration steps for all installation types. | 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 acticity from typical embedded computer using a flash-storage. Selecting a database is done during initial installation as migration from one to another is not supported. | |||
* [https://www.home-assistant.io/docs/backend/database/ database] | |||
* [https://www.home-assistant.io/integrations/recorder/ remote database] | |||
=== Network === | === Network === | ||
Line 210: | Line 223: | ||
Finally after all configuration is finished, a restart is needed: | Finally after all configuration is finished, a restart is needed: | ||
# chkconfig hass on | # chkconfig hass on | ||
# | # systemctl restart hass | ||
=== SELinux === | === SELinux === | ||
== User interfaces == | == User interfaces == | ||
HASS [https://developers.home-assistant.io/docs/architecture/core/ 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 === | === Console === | ||
System running HASS-instance (processes, database etc) does not have any native graphical user interface (X11, Wayland, Qt/GTK) for embedded local displays. | |||
System running HASS-instance (processes, database etc) does not have any user interface. | |||
=== Web === | === Web === | ||
Line 241: | Line 254: | ||
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 [https://www.google.com/search?q=home+assistant+wall+display&tbm=isch have built these] but there is no widely accepted solution for walls yet. | 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 [https://www.google.com/search?q=home+assistant+wall+display&tbm=isch 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. | 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. | ||
Line 266: | Line 277: | ||
* supervisor - management software supervising core daemons. | * supervisor - management software supervising core daemons. | ||
* supervised - type of system that runs core under supervisor. | * supervised - type of system that runs core under supervisor. | ||
* addon - a normal Linux OS-level system daemon/service accessible via HASS settings. | |||
== External links == | == External links == |
Latest revision as of 09:21, 12 June 2024
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) 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.
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:
- Home assistant vs Home Assistant Core
- HA OS vs Supervised
- What features core users are missing?
- manual supervised installation
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 acticity from typical embedded computer using a flash-storage. 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/.home-assistant/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 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
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.
- github.com - Hass Desktop Receiver provides notifications and sensor and dpms-switch to desktop.
- Discussion about native KDE widgets in Hass forum.
- System bridge integration running in desktop and exposing its information to Hass.
- KDE Connect integration request.
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
- Home Assistant/Development
- Home Assistant/Voice features in detail
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
- home-assistant.io home page.
- home-assistant project in GitHub.
- github.com - Paulus Schoutsen personal page
- Home Assistant - Release notes
- home-assistant.io - manual installation instructions
- home-assistant.io - Core integrations database to check if own hardware is supported
- Installation base statistics
- wikipedia.org - Home Assistant
- youtube.com - search: Home Assistant
- youtube.com - search: Home Assistant KNX