Home Assistant: Difference between revisions
| Line 2: | Line 2: | ||
[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. | ||
NixOS provides native support for [https://www.home-assistant.io/faq/ha-vs-hassio/ Home Assistant Core] and offers integration facilities for most pieces of its comprehensive ecosystem: | |||
* As of the 2024.7.1 release we support roughly 87.6% (1107/1264) of the built-in integrations | |||
* We support [https://github.com/NixOS/nixpkgs/tree/master/pkgs/servers/home-assistant/custom-components custom components] through the <code>[https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customComponents&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customComponents services.home-assistant.customComponents]</code> option | |||
* We support source-built [https://github.com/NixOS/nixpkgs/tree/master/pkgs/servers/home-assistant/custom-lovelace-modules custom lovelace modules] mostly through [https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customLovelaceModules&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customLovelaceModules services.home-assistant.customLovelaceModules] option | |||
* We do not support [https://www.home-assistant.io/addons/ addons], which are used to deploy additional services, that are configurable from Home Assistant on their operating system | |||
** NixOS has native support for various services, that integrate with Home Assistant, e.g. [[Mosquitto]], [[Wyoming]], [[zigbee2mqtt]], [[Z-Wave JS]] | |||
== Support == | == Support == | ||
| Line 11: | Line 19: | ||
== Upstream installation methods == | == Upstream installation methods == | ||
If you intend for Home Assistant to be an end-user configurable experience, as opposed to the declarative configuration experience NixOS offers, then consider these setups. They have the benefit of full upstream support. | |||
=== Virtual machine === | === Virtual machine === | ||
| Line 43: | Line 52: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== | == Native installation == | ||
* There is full support for configuring the through the <code>[https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.config services.home-assistant.config]</code> option. | |||
* This is also the case for the [https://www.home-assistant.io/dashboards/dashboards/#adding-more-dashboards-with-yaml Lovelace YAML configuration] through the [https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.lovelace <code>services.home-assistant.lovelace</code>] option. | |||
** Custom Lovelace modules can be configured through [https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customLovelaceModules&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customLovelaceModules <code>services.home-assistant.customLovelaceModules</code>]. The [https://www.home-assistant.io/dashboards/dashboards/#resources <code>resources</code>] section of your Lovelace configuration will automatically be populated. | |||
* Custom components can be enabled through the [https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customComponents&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customComponents <code>services.home-assistant.customComponents</code>]. | |||
* | |||
* | |||
=== Declarative configuration === | === Declarative configuration === | ||
Set up your home-assistant by configuring the <code>services.home-assistant.config</code> attribute set as if it were your home-assistant [https://www.home-assistant.io/docs/configuration/yaml/ YAML configuration]. The module parses the root and platforms level to automatically discover integrations used and will provide their dependencies to your home-assistant package. | |||
The following is a minimal configuration, that has all the dependencies that are required to complete the initial configuration flow, that creates your first user: | |||
The following is a minimal | |||
<syntaxHighlight lang=nix> | <syntaxHighlight lang=nix> | ||
| Line 79: | Line 83: | ||
</syntaxHighlight> | </syntaxHighlight> | ||
=== Imperative configuration === | |||
Alternatively, If you would like to manage your configuration outside your NixOS configuration, you can set up the module to pass a configuration directory. This kind of setup is useful if you want to gradually migrate your existing configuration over. | |||
Using a custom configuration has the drawback, that we cannot automatically recognize and install component dependencies, and it is unlikely that we will continue to support these kinds of setups going forward.<syntaxhighlight lang="nix"> | |||
{ | |||
services.home-assistant = { | |||
# opt-out from declarative configuration management | |||
config = null; | |||
lovelaceConfig = null; | |||
# configure the path to your config directory | |||
configDir = "/etc/home-assistant"; | |||
# specify list of components required by your configuration | |||
extraComponents = [ | |||
"esphome" | |||
"met" | |||
"radio_browser" | |||
]; | |||
}; | |||
} | |||
</syntaxhighlight> | |||
=== Firewalling === | |||
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. | ||