feat(mqtt): add opt-in Home Assistant MQTT discovery (#5543)

* feat(mqtt): add opt-in Home Assistant MQTT discovery

Add an MQTT_HOME_ASSISTANT_DISCOVERY env var that, when enabled, makes
VehicleSubscriber publish HA discovery config payloads (one per entity)
to homeassistant/<component>/teslamate_<car_id>/<object_id>/config on
startup, mirroring the manual configuration documented in
website/docs/integrations/home_assistant.md.

* docs: fix malformed environment variables table

Fix the header separator row, which gained an extra column, and the MQTT_HOME_ASSISTANT_DISCOVERY_PREFIX row, which had a trailing empty cell. Addresses review comment on #5543.

* docs: reword MQTT_HOME_ASSISTANT_DISCOVERY_URL wording

MQTT_HOME_ASSISTANT_DISCOVERY_URL is optional; clarify that setting MQTT_HOME_ASSISTANT_DISCOVERY does not require it. Addresses review comment on #5543.

* feat(mqtt): validate MQTT_HOME_ASSISTANT_DISCOVERY_PREFIX

Validate the discovery prefix like MQTT_NAMESPACE: empty values fall back to the default so topics never get a leading '/', and MQTT wildcards are rejected. Addresses review comment on #5543.

* feat(mqtt): clear Home Assistant discovery configs on disable

Call HomeAssistant.clear/3 so retained discovery configs (and the entities in Home Assistant) are removed when discovery is disabled. Addresses review comment on #5543.

* feat(mqtt): clear Home Assistant discovery configs for removed vehicles on startup

* feat(mqtt): make discovery entity IDs match the manual mqtt_sensors.yaml

Prefix the discovery object_id with tesla_ so Home Assistant generates the same
entity IDs as the documented manual configuration (e.g. sensor.tesla_speed
instead of sensor.speed), avoiding broken dashboards and automations on
migration. Drop the _km suffix from the battery range sensors to match the
manual unique_ids. Document that the manual mqtt_sensors.yaml must be removed
before enabling discovery to avoid duplicate unique_id errors. Addresses review
comment on #5543.

* fix(mqtt): use state_class total_increasing for charge_energy_added discovery entity

* feat(mqtt): add charging_state discovery entity

* test(mqtt): use plain ExUnit.Case in home_assistant_test

* feat(mqtt): scope discovery topics and unique_ids by MQTT namespace

* feat(vehicles): add Summary type definition

* docs(mqtt): simplify discovered entities note

* feat(nix): add Home Assistant MQTT discovery options

* fix(mqtt): scope startup discovery cleanup by MQTT namespace

Pass the namespace to HomeAssistant.clear/3 in clear_removed_vehicles/2 so a namespaced instance clears its own discovery topics instead of the un-namespaced ones of a sibling instance sharing the broker.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(test): extract shared drain_discovery_configs helper

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(mqtt): explain startup discovery cleanup timing

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(mqtt): reject MQTT wildcards in MQTT_NAMESPACE

Align with validate_discovery_prefix!: a namespace containing + or # would produce unpublishable state and discovery topics, so fail fast at boot.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: update changelog

---------

Co-authored-by: Jakob Lichterfeld <jakob-lichterfeld@gmx.de>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 Existing charging processes are recomputed once during the upgrade migration: previously empty or zero `charge_energy_used` values (short or mixed AC sessions) gain values, the first start after the upgrade can take a few minutes longer on databases with years of history and slow HW, and charge costs are deliberately not changed retroactively.
 
+### Note for manual Home Assistant configurations
+
+The documented manual [mqtt_sensors.yaml](https://docs.teslamate.org/docs/integrations/home_assistant#mqtt_sensorsyaml-mqtt-section-of-configurationyaml) now uses `state_class: total_increasing` for the `charge_energy_added` sensor (#5543). If you re-sync your manual YAML, Home Assistant will treat the per-charge resets as meter cycles, which changes the long-term statistics behavior (e.g. in the Energy dashboard).
+
 ### New features
 
 - feat: add service mode to webview and reduce log when car is Unlocked at service mode (#5289 - @NirKli)
@@ -14,6 +18,7 @@ Existing charging processes are recomputed once during the upgrade migration: pr
 - feat: link the software update icon to the notateslaapp release notes (#5490 - @NirKli)
 - feat: add fullscreen mode to vehicle summary map (#5495 - @hakong)
 - feat(web): expose VIN in car summary ( #5556 - @Helvio88, @magrathean-uk)
+- feat(mqtt): add opt-in Home Assistant MQTT discovery (#5543 - @brianmay, @JakobLichterfeld)
 
 ### Improvements and bug fixes
 

config/runtime.exs

@@ -12,9 +12,20 @@ defmodule Util do
   def validate_namespace!(""), do: nil
 
   def validate_namespace!(ns) when is_binary(ns) do
-    case String.contains?(ns, "/") do
-      true -> raise "MQTT_NAMESPACE must not contain '/'"
-      false -> ns
+    cond do
+      String.contains?(ns, "/") -> raise "MQTT_NAMESPACE must not contain '/'"
+      String.contains?(ns, ["+", "#"]) -> raise "MQTT_NAMESPACE must not contain MQTT wildcards"
+      true -> ns
+    end
+  end
+
+  def validate_discovery_prefix!(nil), do: nil
+  def validate_discovery_prefix!(""), do: nil
+
+  def validate_discovery_prefix!(prefix) when is_binary(prefix) do
+    case String.contains?(prefix, ["+", "#"]) do
+      true -> raise "MQTT_HOME_ASSISTANT_DISCOVERY_PREFIX must not contain MQTT wildcards"
+      false -> prefix
     end
   end
 
@@ -181,7 +192,11 @@ if System.get_env("DISABLE_MQTT") != "true" or config_env() == :test do
     tls: System.get_env("MQTT_TLS") == "true",
     accept_invalid_certs: System.get_env("MQTT_TLS_ACCEPT_INVALID_CERTS") == "true",
     namespace: System.get_env("MQTT_NAMESPACE") |> Util.validate_namespace!(),
-    ipv6: System.get_env("MQTT_IPV6") == "true"
+    ipv6: System.get_env("MQTT_IPV6") == "true",
+    discovery: System.get_env("MQTT_HOME_ASSISTANT_DISCOVERY") == "true",
+    discovery_base_url: System.get_env("MQTT_HOME_ASSISTANT_DISCOVERY_URL"),
+    discovery_prefix:
+      System.get_env("MQTT_HOME_ASSISTANT_DISCOVERY_PREFIX") |> Util.validate_discovery_prefix!()
 end
 
 if config_env() != :test do

lib/teslamate/mqtt.ex

@@ -16,7 +16,14 @@ defmodule TeslaMate.Mqtt do
     children = [
       {Tortoise311.Connection, connection_config(opts) ++ [client_id: client_id]},
       {Publisher, client_id: client_id},
-      {PubSub, namespace: opts[:namespace]}
+      {PubSub,
+       [
+         namespace: opts[:namespace],
+         discovery: opts[:discovery],
+         discovery_base_url: opts[:discovery_base_url],
+         discovery_prefix: opts[:discovery_prefix]
+       ]
+       |> Enum.reject(fn {_key, value} -> is_nil(value) end)}
     ]
 
     Supervisor.init(children, strategy: :one_for_one)

lib/teslamate/mqtt/pubsub.ex

@@ -1,8 +1,14 @@
 defmodule TeslaMate.Mqtt.PubSub do
   use Supervisor
 
+  require Logger
+
   alias __MODULE__.VehicleSubscriber
+  alias __MODULE__.HomeAssistant
+  alias TeslaMate.Log
+  alias TeslaMate.Mqtt.Publisher
   alias TeslaMate.Vehicles
+  alias TeslaMate.Vehicles.Vehicle.Summary
 
   # API
 
@@ -12,10 +18,48 @@ defmodule TeslaMate.Mqtt.PubSub do
 
   @impl true
   def init(opts) do
+    subscriber_opts =
+      opts
+      |> Keyword.take([:namespace, :discovery, :discovery_base_url, :discovery_prefix])
+
+    vehicles = Vehicles.list()
+
+    if Keyword.get(opts, :discovery, false) do
+      # Runs concurrently with the supervised children starting up, so it may
+      # fire before the MQTT connection is established. Failures are only
+      # logged; since the cleanup is idempotent and repeated on every start,
+      # a missed run is corrected on the next restart.
+      Task.start(fn -> clear_removed_vehicles(vehicles, opts) end)
+    end
+
     children =
-      Vehicles.list()
-      |> Enum.map(&{VehicleSubscriber, Keyword.merge(opts, car_id: &1.car.id)})
+      vehicles
+      |> Enum.map(&{VehicleSubscriber, Keyword.merge(subscriber_opts, car_id: &1.car.id)})
 
     Supervisor.init(children, strategy: :one_for_one)
   end
+
+  @doc """
+  Clears Home Assistant discovery configs for cars that are no longer
+  tracked by a vehicle process, e.g. because they were removed from the
+  Tesla account or because logging was disabled, so their entities are
+  removed from Home Assistant.
+  """
+  @spec clear_removed_vehicles([Summary.t()], keyword()) :: :ok
+  def clear_removed_vehicles(vehicles, opts) do
+    publisher = Keyword.get(opts, :deps_publisher, Publisher)
+    active_ids = Enum.map(vehicles, & &1.car.id)
+    clear_opts = Keyword.take(opts, [:namespace, :discovery_prefix])
+
+    Log.list_cars()
+    |> Enum.reject(&(&1.id in active_ids))
+    |> Enum.each(fn car ->
+      case HomeAssistant.clear(car.id, clear_opts, publisher) do
+        :ok -> :ok
+        {:error, reason} -> Logger.warning("MQTT HA discovery cleanup failed: #{inspect(reason)}")
+      end
+    end)
+
+    :ok
+  end
 end