NixOS Wiki

Home Assistant: Difference between revisions

← Older edit
VisualWikitext
Hexa (talk | contribs)
62 edits
→Declarative configuration: Update onboarding packages
Hexa (talk | contribs)
62 edits
Update number of support components
 
(15 intermediate revisions by 5 users not shown)
Line 5: Line 5:
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:
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.8.3 release we support roughly 90.4% (1152/1274) of the built-in integrations
* As of the 2025.8.3 release we support over 99% (1350/1363) 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 [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 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
* 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]]
** NixOS has native support for various services, that integrate with Home Assistant, e.g. [[EVCC]], [[Frigate]], [[Mosquitto]], [[Music-Assistant]], [[Wyoming]], [[zigbee2mqtt]], [[Z-Wave JS]]


== Support ==
== Support ==
Line 55: Line 55:
== Native installation ==
== 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.
* There is full support for the YAML configuration 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.
* 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 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.
Line 111: Line 111:


=== Firewalling ===
=== 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.
Home Assistant by default listens on port 8123. It is customary to put services behind a [[Home Assistant#Reverse Proxying with nginx|reverse-proxy]], which allows sharing ports 80/443 (http/https) and offers TLS termination.
 
If you don't plan on using a reverse-proxy, you can allow unencrypted access by opening up the port home-assistant is running on in your firewall. This is not generally recommended, since credentials will be transmitted in plain text and browsers tend to limit certain functionality (e.g. geolocation) to HTTPS.
 
<syntaxhighlight lang="nix">
{
  config,
  ...
}:


<syntaxHighlight lang=nix>
{
{
   networking.firewall.allowedTCPPorts = [ <other ports> 8123 ];
   networking.firewall.allowedTCPPorts = [
    config.services.home-assistant.config.http.server_port
  ];
}
}
</syntaxHighlight>
</syntaxhighlight>


===== First start =====
=== First start ===
On your first start you may see multiple <code><nowiki>ModuleNotFoundError</nowiki></code> in Home Assistants journal log. These are dependencies required to set up devices Home Assistant already discovered on the local network.


On your first start you may see multiple <code><nowiki>ModuleNotFoundError</nowiki></code> in Home Assistants journal log. These are dependencies required to set up devices Home Assistant already found on the network.
The appropriate component to load can be looked up in the <code>[https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/home-assistant/component-packages.nix component-packages.nix]</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
Line 144: Line 152:
     [...]
     [...]
</syntaxHighlight>
</syntaxHighlight>
* https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/home-assistant/component-packages.nix


==== Using components without YAML configuration ====
==== Using components without YAML configuration ====


When a component has no YAML configuration its dependencies can in theory be installed by mentioning the component name in <code><nowiki>services.home-assistant.config.wled = {};</nowiki></code>. This is deprecated, since Home Assistant will usually complain about the config having been migrated into the graphical user interface.
When a component offers no YAML configuration its dependencies could in theory be installed by mentioning its component name in <code><nowiki>services.home-assistant.config.wled = {};</nowiki></code>. This is deprecated, since Home Assistant will usually complain about the config having been migrated into the graphical user interface.


In recent versions of the home-assistant this use case has become more prominent and therefore received a more straightforward implementation, that also ensures that the component is still provided by Home Assistant.
In recent versions of the home-assistant this use case has become more prominent and therefore received a more straightforward implementation, that also ensures that the component is still provided by Home Assistant.
Line 161: Line 167:
</syntaxHighlight>
</syntaxHighlight>


==== Making additional python packages available ====
==== Provide additional Python packages to Home Assistant ====


We control the dependencies we pass into the Home Assistant python environment through module options that make the dependencies available, when their relative component was declaratively mentioned.
We control the dependencies we pass into the Home Assistant python environment through module options that make the dependencies available, when their relative component was declaratively mentioned.
Line 191: Line 197:


Custom components can be found under [https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=home-assistant-custom-lovelace-modules pkgs.home-assistant-custom-lovelace-modules].
Custom components can be found under [https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=home-assistant-custom-lovelace-modules pkgs.home-assistant-custom-lovelace-modules].
=== Reusing existing YAML configuration ===
The module also supports passing it an existing configuration, however that comes with certain drawbacks. For example we cannot automatically detect the components, that your configuration requires. In that scenario you will need to resolve dependencies manually using the packages <code>extraComponents</code> parameter. Also you will be unable to reuse configuration values between parts of your NixOS configuration. A barebones setup to get you started may look like this:
<syntaxHighlight lang=nix>
{
  services.home-assistant = {
    enable = true;
    # Pass the path to the directory where your configuration.yaml
    # resides, /var/lib/hass might be a good location.
    configDir = /var/lib/hass;
    # Override the package to handle dependency management manually
    package = (pkgs.home-assistant.override {
      # https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/home-assistant/component-packages.nix
      extraComponents = [
        "default_config"
        "esphome"
        "met"
      ];
      extraPackages = ps: with ps; [
        # Are you using a database server for your recorder?
        # https://www.home-assistant.io/integrations/recorder/
        #mysqlclient
        #psycopg2
      ];
    })
  };
}
</syntaxHighlight>
You may find the following script helpful. It looks up missing dependencies from the <code>home-assistant.service</code> systemd unit journal: https://gist.github.com/AngryAnt/74c047a2b8438517c822ffdd9663aa57


= Tracking the latest release =  
= Tracking the latest release =  
Line 285: Line 259:


Home Assistant supports PostgreSQL as a database backend for, among other things, its logger and history components. It's a lot more scalable and typically provides faster response times than the SQLite database, that is used by default.
Home Assistant supports PostgreSQL as a database backend for, among other things, its logger and history components. It's a lot more scalable and typically provides faster response times than the SQLite database, that is used by default.
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 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 443: Line 413:
         {
         {
           alias = "Name To Display in Automations List";
           alias = "Name To Display in Automations List";
           trigger = {
           triggers = {
             platform = "state";
             trigger = "state";
             entity_id = "binary_sensor.someid1";
             entity_id = "binary_sensor.someid1";
             to = "off";
             to = "off";
             for = "00:10:00";
             for = "00:10:00";
           };
           };
           condition = {
           conditions = {
             condition = "state";
             condition = "state";
             entity_id = "binary_sensor.someid2";
             entity_id = "binary_sensor.someid2";
             state = "on";
             state = "on";
           };
           };
           action = {
           actions = {
             service = "light.turn_off";
             action = "light.turn_off";
             entity_id = "light.someid";
             entity_id = "light.someid";
           };
           };
Line 465: Line 435:
         {
         {
           alias = "Name in Automations GUI";
           alias = "Name in Automations GUI";
           trigger = {
           triggers = {
             platform = "state";
             trigger = "state";
             entity_id = "binary_sensor.someid";
             entity_id = "binary_sensor.someid";
             to = "on";
             to = "on";
           };
           };
           condition = [
           conditions = [
             {
             {
               condition = "state";
               condition = "state";
Line 482: Line 452:
             }
             }
           ];
           ];
           action = [
           actions = [
             {
             {
               service = "notify.notify";
               action = "notify.notify";
               data = {
               data = {
                 message = "Some Notification";
                 message = "Some Notification";
Line 490: Line 460:
             }
             }
             {
             {
               service = "siren.turn_on";
               action = "siren.turn_on";
               entity_id = "siren.someid";
               entity_id = "siren.someid";
             }
             }
Line 502: Line 472:
         {
         {
           alias = "Some Name";
           alias = "Some Name";
           trigger = {
           triggers = {
             platform = "numeric_state";
             trigger = "numeric_state";
             entity_id = "sensor.batteries";
             entity_id = "sensor.batteries";
             below = "45";
             below = "45";
           };
           };
           action = {
           actions = {
             service = "notify.notify";
             action = "notify.notify";
             data = {
             data = {
               message = "Low Battery Detected";
               message = "Low Battery Detected";
Line 520: Line 490:
         {
         {
           alias = "Object Went Unknown";
           alias = "Object Went Unknown";
           trigger = {
           triggers = {
             platform = "state";
             trigger = "state";
             entity_id = "switch.someid";
             entity_id = "switch.someid";
             to = "unknown";
             to = "unknown";
             for = "00:5:00";
             for = "00:5:00";
           };
           };
           action = {
           actions = {
             service = "notify.notify";
             action = "notify.notify";
             data = {
             data = {
               message = "Object Went Offline";
               message = "Object Went Offline";
Line 540: Line 510:
         {
         {
           alias = "Do Something At Certain Time";
           alias = "Do Something At Certain Time";
           trigger = {
           triggers = {
             platform = "time";
             trigger = "time";
             at = "23:00:00";
             at = "23:00:00";
           };
           };
           action = {
           actions = {
             service = "climate.set_temperature";
             action = "climate.set_temperature";
             entity_id = "climate.thermostat";
             entity_id = "climate.thermostat";
             data = {
             data = {
Line 583: Line 553:
= Example configurations =
= Example configurations =


* [https://github.com/Mic92/dotfiles/tree/master/nixos/eve/modules/home-assistant Mic92's config]
* [https://github.com/Mic92/dotfiles/tree/393539385b0abfc3618e886cd0bf545ac24aeb67/machines/eve/modules/home-assistant Mic92's config]


= Misc =
= Misc =
Retrieved from "https://wiki.nixos.org/wiki/Home_Assistant"