Home Assistant: Difference between revisions
Add ZHA snippet |
|||
| Line 3: | Line 3: | ||
[https://www.home-assistant.io/ 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. | [https://www.home-assistant.io/ 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. | ||
= | == Support == | ||
Depending on the installation method one of various support channels should be used. | |||
If you rely on the NixOS package and/or module, issues should be reported on the [https://github.com/NixOS/nixpkgs/issues/new/choose nixpkgs Issue tracker] or the [https://matrix.to/#/#homeautomation:nixos.org?via=lossy.network&via=matrix.org&via=kack.it #homeautomation:nixos.org] Matrix room. | |||
Only if you rely on one of the [[Home Assistant#Upstream supported|upstream supported]] deployment methods issues can be directly reported to the upstream project. Make sure to follow their guide on [https://www.home-assistant.io/help/reporting_issues/ reporting issues]. | |||
== Upstream installation methods == | |||
=== Virtual machine === | |||
Home Assistant maintains their own operating system and provides [[QEMU]] (qcow2) and [[Virtualbox]] (vdi) compatible [https://www.home-assistant.io/installation/linux#install-home-assistant-operating-system images]. Home Assistant supports virtualization solutions like [[libvirt]] and [[Incus]], which can host such a virtual machine. | |||
==== Example: ==== | |||
* [https://myme.no/posts/2021-11-25-nixos-home-assistant.html NixOS: Headless Home Assistant VM (myme.no)] using libvirt | |||
=== OCI container === | === OCI container === | ||
Home Assistant also provides a [https://www.home-assistant.io/installation/linux#install-home-assistant-container container image] for OCI compatible runtimes. | |||
==== Example: ==== | |||
The following example configuration uses podman to download and run the <code>home-assistant:stable</code> image. The frontend will be available via HTTP on port <code>tcp/8123</code> in the host network namespace and could be reverse proxied from there. | |||
<syntaxhighlight lang="nix"> | |||
< | |||
{ | { | ||
virtualisation.oci-containers = { | virtualisation.oci-containers = { | ||
| Line 39: | Line 31: | ||
volumes = [ "home-assistant:/config" ]; | volumes = [ "home-assistant:/config" ]; | ||
environment.TZ = "Europe/Berlin"; | environment.TZ = "Europe/Berlin"; | ||
image = "ghcr.io/home-assistant/home-assistant:stable"; | # Note: The image will not be updated on rebuilds, unless the version label changes | ||
image = "ghcr.io/home-assistant/home-assistant:stable"; | |||
extraOptions = [ | extraOptions = [ | ||
"--network=host" | # Use the host network namespace for all sockets | ||
"--device=/dev/ttyACM0:/dev/ttyACM0" | "--network=host" | ||
# Pass devices into the container, so Home Assistant discover and make use of them | |||
"--device=/dev/ttyACM0:/dev/ttyACM0" | |||
]; | ]; | ||
}; | }; | ||
}; | }; | ||
} | } | ||
</ | </syntaxhighlight> | ||
== NixOS Module == | == NixOS Module == | ||
You | You can run Home Assistant from nixpkgs using the NixOS module system at <code>services-home-assistant</code>. As of 2024-07-06 (2024.7.1) we have support for the vast majority of built-in integrations (roughly 87.6%, 1107/1264) as well as support for declarative installation of custom components and lovelace modules. | ||
There are two different ways of running home-assistant using the module system: | |||
* a) Using a fully declarative configuration | * a) Using a fully declarative configuration | ||
* b) | * b) Passing a custom configuration.yml configuration and/or lovelace.yml | ||
Using a custom configuration has the drawback, that we cannot automatically recognize and install component dependencies and it is not clear that we will continue to support these kinds of setups going forward. If you are using such a setup, please speak up in the Home-Automation room on Matrix (<code><nowiki>#homeautomation:nixos.org</nowiki></code>). | Using a custom configuration has the drawback, that we cannot automatically recognize and install component dependencies, and it is not clear that we will continue to support these kinds of setups going forward. If you are using such a setup, please speak up in the Home-Automation room on Matrix (<code><nowiki>#homeautomation:nixos.org</nowiki></code>). | ||
=== Declarative configuration === | === Declarative configuration === | ||
| Line 85: | Line 80: | ||
</syntaxHighlight> | </syntaxHighlight> | ||
If not using a reverse-proxy and you just want unencrypted access on a local network don't forget to update your firewall configuration to expose the port home-assistant is running on. | If not using a reverse-proxy, and you just want unencrypted access on a local network don't forget to update your firewall configuration to expose the port home-assistant is running on. | ||
<syntaxHighlight lang=nix> | <syntaxHighlight lang=nix> | ||
| Line 99: | Line 94: | ||
The appropriate component to load can be looked up in the <code><nowiki>component-packages.nix</nowiki></code> file, that gets auto-generated as part of the packaging process. | The appropriate component to load can be looked up in the <code><nowiki>component-packages.nix</nowiki></code> file, that gets auto-generated as part of the packaging process. | ||
For example we can map the following error to | For example, we can map the following error to | ||
ModuleNotFoundError: No module named 'aioesphomeapi' | ModuleNotFoundError: No module named 'aioesphomeapi' | ||
| Line 262: | Line 257: | ||
Remember to make backups of your database, for Home Assistant is becoming more and more stateful and has moved away from a completely declarative YAML configuration for new and core components. | Remember to make backups of your database, for Home Assistant is becoming more and more stateful and has moved away from a completely declarative YAML configuration for new and core components. | ||
Also note that when | Also note that when overriding the package you may want to disable install checks as they tend to take a long time to complete. | ||
<syntaxHighlight lang=nix> | <syntaxHighlight lang=nix> | ||
| Line 286: | Line 281: | ||
== Updating Zigbee Firmware over the air == | == Updating Zigbee Firmware over the air == | ||
To allow ZHA OTA updates you need to configure the z2m_remote_index setting for | To allow ZHA OTA updates you need to configure the z2m_remote_index setting for ZHA. Before doing any updates, you should read the official integration documentation https://www.home-assistant.io/integrations/zha/#ota-firmware-updates | ||
Before doing any updates, you should read the official integration documentation https://www.home-assistant.io/integrations/zha/#ota-firmware-updates | |||
Before updating a device, you should do some research. Some firmware updates break certain features you might use (e.g. group binding for IKEA devices). Some updates may also require changes to ZHA. In rare cases, you can even brick devices by installing a firmware update. | Before updating a device, you should do some research. Some firmware updates break certain features you might use (e.g., group binding for IKEA devices). Some updates may also require changes to ZHA. In rare cases, you can even brick devices by installing a firmware update. | ||
<syntaxHighlight lang=nix> | <syntaxHighlight lang=nix> | ||
| Line 335: | Line 329: | ||
=== Entity Customization === | === Entity Customization === | ||
You can declaratively define how entities appear in the GUI with respect to their display names (friendly_name) the "show as" (device_class) and the icon displayed (icon). See this page for more documentation and how the | You can declaratively define how entities appear in the GUI with respect to their display names (friendly_name) the "show as" (<code>device_class</code>) and the icon displayed (<code>icon</code>). See this page for more documentation and how the YAML will ultimately be generated: https://www.home-assistant.io/docs/configuration/customizing-devices/. <syntaxhighlight lang="nix"> | ||
config = { | config = { | ||
default_config = {}; | default_config = {}; | ||
| Line 389: | Line 383: | ||
=== Groups / Helpers === | === Groups / Helpers === | ||
You can declaratively define groups rather than setting them up in the GUI, and customize their unique_id, platform, type, and entitiy_id's associated. See https://www.home-assistant.io/integrations/group/ for more documentation. Can be used in conjunction with | You can declaratively define groups rather than setting them up in the GUI, and customize their unique_id, platform, type, and entitiy_id's associated. See https://www.home-assistant.io/integrations/group/ for more documentation. Can be used in conjunction with “Entity Customization” section above for additional flexibility by plugging in the <code>unique_id</code> then changing the <code>friendly_name</code>, <code>icon</code>, <code>device_class</code> etc. | ||
==== Binary Sensor Group ==== | ==== Binary Sensor Group ==== | ||
| Line 410: | Line 404: | ||
==== Sensor Group ==== | ==== Sensor Group ==== | ||
Example of Sensor group using | Example of Sensor group using “min” mode that could be used in an Automation to trigger a Low Battery Alert across all batteries in the group.<syntaxhighlight lang="nix"> | ||
# Sensor Battery Group | # Sensor Battery Group | ||
"sensor" = [ | "sensor" = [ | ||
| Line 546: | Line 540: | ||
} | } | ||
</syntaxhighlight>If you did not create any automations through the UI, Home Assistant will fail loading because the <code>automations.yaml</code> file does not exist yet and it will fail including it. To avoid that, add a systemd tmpfiles.d rule: | </syntaxhighlight>If you did not create any automations through the UI, Home Assistant will fail loading because the <code>automations.yaml</code> file does not exist yet, and it will fail including it. To avoid that, add a systemd tmpfiles.d rule: | ||
<syntaxHighlight lang=nix> | <syntaxHighlight lang=nix> | ||
| Line 558: | Line 552: | ||
Home Assistant does not natively support adding a private CA to the certificate store (see [https://community.home-assistant.io/t/add-private-cas-to-certificate-store/267452 this thread] for more details). | Home Assistant does not natively support adding a private CA to the certificate store (see [https://community.home-assistant.io/t/add-private-cas-to-certificate-store/267452 this thread] for more details). | ||
Home Assistant trusts certificates provided by the certifi python package, which nix overwrites with the cacert package. Using overrides you can append your root CA certificate to the certificates provided by certifi. | Home Assistant trusts certificates provided by the <code>certifi</code> python package, which nix overwrites with the <code>cacert</code> package. Using overrides you can append your root CA certificate to the certificates provided by <code>certifi</code>. | ||
<syntaxHighlight lang=nix> | <syntaxHighlight lang=nix> | ||
| Line 576: | Line 570: | ||
= Example configurations = | = Example configurations = | ||
* [https://github.com/Mic92/dotfiles/tree/master/nixos/eve/modules/home-assistant Mic92's config] | |||
= Misc = | = Misc = | ||