feat(mqtt): add Home Assistant MQTT auto-discovery support (#1749)

* feat(mqtt): add Home Assistant MQTT auto-discovery support

Implements Home Assistant MQTT Discovery protocol for automatic device
and sensor registration. This allows BirdNET-Go to automatically appear
in Home Assistant without manual configuration.

Features:
- Bridge device representing the BirdNET-Go instance
- Per-source devices linked via via_device
- Sensors: species, confidence, scientific name, sound level
- LWT (Last Will and Testament) for availability tracking
- OnConnect handler for automatic discovery on reconnection
- Proper cleanup via RemoveDiscovery

Configuration:
- realtime.mqtt.homeassistant.enabled: Enable/disable discovery
- realtime.mqtt.homeassistant.discovery_prefix: Topic prefix (default: homeassistant)
- realtime.mqtt.homeassistant.device_name: Base device name

Closes #1717

* fix(mqtt): address code review feedback

- Extract publishInternal helper to eliminate duplication between
  Publish and PublishWithRetain methods (~100 lines reduced)
- Add RegisterHomeAssistantDiscovery exported method for reconfiguration
- Register HA discovery handler in handleReconfigureMQTT so discovery
  messages are published after MQTT reconnection/reconfiguration

---------

Co-authored-by: tphakala <tphakala@users.noreply.github.com>

Author: tphakala

internal/analysis/control_monitor.go

@@ -260,6 +260,10 @@ func (cm *ControlMonitor) handleReconfigureMQTT() {
 			return
 		}
 
+		// Register Home Assistant discovery handler before connecting
+		// so the OnConnect handler fires on the initial connection
+		cm.proc.RegisterHomeAssistantDiscovery(newClient, settings)
+
 		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 		if err := newClient.Connect(ctx); err != nil {
 			cancel()

internal/analysis/processor/actions.go

@@ -994,9 +994,12 @@ func (a *BirdWeatherAction) Execute(data any) error {
 	return nil
 }
 
+// NoteWithBirdImage wraps a Note with bird image data for MQTT publishing.
+// The SourceID field enables Home Assistant to filter detections by source.
 type NoteWithBirdImage struct {
 	datastore.Note
-	BirdImage imageprovider.BirdImage
+	SourceID  string                  `json:"sourceId"` // Audio source ID for HA filtering
+	BirdImage imageprovider.BirdImage `json:"birdImage"`
 }
 
 // Execute sends the note to the MQTT broker
@@ -1052,8 +1055,12 @@ func (a *MqttAction) Execute(data any) error {
 	// Create a copy of the Note (source is already sanitized in SafeString field)
 	noteCopy := a.Note
 
-	// Wrap note with bird image (using copy)
-	noteWithBirdImage := NoteWithBirdImage{Note: noteCopy, BirdImage: birdImage}
+	// Wrap note with bird image (using copy) and include SourceID for HA filtering
+	noteWithBirdImage := NoteWithBirdImage{
+		Note:      noteCopy,
+		SourceID:  noteCopy.Source.ID,
+		BirdImage: birdImage,
+	}
 
 	// Create a JSON representation of the note
 	noteJson, err := json.Marshal(noteWithBirdImage)

internal/analysis/processor/mqtt.go

@@ -7,8 +7,17 @@ import (
 	"time"
 
 	"github.com/tphakala/birdnet-go/internal/conf"
+	"github.com/tphakala/birdnet-go/internal/datastore"
 	"github.com/tphakala/birdnet-go/internal/logger"
 	"github.com/tphakala/birdnet-go/internal/mqtt"
+	"github.com/tphakala/birdnet-go/internal/myaudio"
+)
+
+const (
+	// mqttConnectionTimeout is the timeout for MQTT connection attempts
+	mqttConnectionTimeout = 30 * time.Second
+	// discoveryPublishTimeout is the timeout for publishing discovery messages
+	discoveryPublishTimeout = 30 * time.Second
 )
 
 // GetMQTTClient safely returns the current MQTT client
@@ -28,10 +37,12 @@ func (p *Processor) SetMQTTClient(client mqtt.Client) {
 // DisconnectMQTTClient safely disconnects and removes the MQTT client
 func (p *Processor) DisconnectMQTTClient() {
 	p.mqttMutex.Lock()
-	defer p.mqttMutex.Unlock()
-	if p.MqttClient != nil {
-		p.MqttClient.Disconnect()
-		p.MqttClient = nil
+	client := p.MqttClient
+	p.MqttClient = nil
+	p.mqttMutex.Unlock()
+
+	if client != nil {
+		client.Disconnect()
 	}
 }
 
@@ -49,6 +60,9 @@ func (p *Processor) PublishMQTT(ctx context.Context, topic, payload string) erro
 
 // initializeMQTT initializes the MQTT client if enabled in settings
 func (p *Processor) initializeMQTT(settings *conf.Settings) {
+	if settings == nil {
+		return
+	}
 	if !settings.Realtime.MQTT.Enabled {
 		return
 	}
@@ -61,8 +75,13 @@ func (p *Processor) initializeMQTT(settings *conf.Settings) {
 		return
 	}
 
-	// Create a context with a 30-second timeout for the connection attempt
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	// Register Home Assistant discovery handler if enabled
+	if settings.Realtime.MQTT.HomeAssistant.Enabled {
+		p.registerHomeAssistantDiscovery(mqttClient, settings)
+	}
+
+	// Create a context with a timeout for the connection attempt
+	ctx, cancel := context.WithTimeout(context.Background(), mqttConnectionTimeout)
 	defer cancel() // Ensure the cancel function is called to release resources
 
 	// Attempt to connect to the MQTT broker
@@ -74,3 +93,81 @@ func (p *Processor) initializeMQTT(settings *conf.Settings) {
 	// Set the client only if connection was successful
 	p.SetMQTTClient(mqttClient)
 }
+
+// RegisterHomeAssistantDiscovery registers the OnConnect handler for Home Assistant discovery.
+// This is called during MQTT initialization and after MQTT reconfiguration.
+func (p *Processor) RegisterHomeAssistantDiscovery(client mqtt.Client, settings *conf.Settings) {
+	if client == nil || settings == nil {
+		return
+	}
+	if !settings.Realtime.MQTT.HomeAssistant.Enabled {
+		return
+	}
+	p.registerHomeAssistantDiscovery(client, settings)
+}
+
+// registerHomeAssistantDiscovery registers the OnConnect handler for Home Assistant discovery.
+func (p *Processor) registerHomeAssistantDiscovery(client mqtt.Client, settings *conf.Settings) {
+	log := GetLogger()
+
+	// Create discovery configuration
+	haSettings := settings.Realtime.MQTT.HomeAssistant
+	discoveryConfig := mqtt.DiscoveryConfig{
+		DiscoveryPrefix: haSettings.DiscoveryPrefix,
+		BaseTopic:       settings.Realtime.MQTT.Topic,
+		DeviceName:      haSettings.DeviceName,
+		NodeID:          settings.Main.Name,
+		Version:         settings.Version,
+	}
+
+	// Create the discovery publisher
+	publisher := mqtt.NewDiscoveryPublisher(client, &discoveryConfig)
+
+	// Register the OnConnect handler
+	client.RegisterOnConnectHandler(func() {
+		log.Info("MQTT connected, publishing Home Assistant discovery messages")
+
+		// Get audio sources from the registry
+		sources := p.getAudioSourcesForDiscovery()
+
+		// Create a context for publishing
+		ctx, cancel := context.WithTimeout(context.Background(), discoveryPublishTimeout)
+		defer cancel()
+
+		// Publish discovery messages
+		if err := publisher.PublishDiscovery(ctx, sources, settings); err != nil {
+			log.Error("Failed to publish Home Assistant discovery",
+				logger.Error(err))
+		}
+	})
+
+	log.Info("Home Assistant discovery handler registered",
+		logger.String("discovery_prefix", haSettings.DiscoveryPrefix),
+		logger.String("device_name", haSettings.DeviceName))
+}
+
+// getAudioSourcesForDiscovery retrieves audio sources from the registry for HA discovery.
+func (p *Processor) getAudioSourcesForDiscovery() []datastore.AudioSource {
+	registry := myaudio.GetRegistry()
+	registrySources := registry.ListSources()
+
+	// Convert myaudio.AudioSource to datastore.AudioSource
+	sources := make([]datastore.AudioSource, 0, len(registrySources))
+	for _, src := range registrySources {
+		sources = append(sources, datastore.AudioSource{
+			ID:          src.ID,
+			SafeString:  src.SafeString,
+			DisplayName: src.DisplayName,
+		})
+	}
+
+	// If no sources registered yet, create a default source
+	if len(sources) == 0 {
+		sources = append(sources, datastore.AudioSource{
+			ID:          "default",
+			DisplayName: "Default",
+		})
+	}
+
+	return sources
+}

internal/analysis/processor/mqtt_occurrence_test.go

@@ -49,6 +49,16 @@ func (m *MockMqttClientWithCapture) TestConnection(_ context.Context, _ chan<- m
 	// Not needed for test
 }
 
+func (m *MockMqttClientWithCapture) PublishWithRetain(_ context.Context, topic, data string, _ bool) error {
+	m.PublishedTopic = topic
+	m.PublishedData = data
+	return m.PublishError
+}
+
+func (m *MockMqttClientWithCapture) RegisterOnConnectHandler(_ mqtt.OnConnectHandler) {
+	// Not needed for test
+}
+
 func TestMqttAction_IncludesOccurrence(t *testing.T) {
 	// Create test note with occurrence value
 	testNote := datastore.Note{

internal/analysis/sound_level_publish_test.go

@@ -1566,6 +1566,17 @@ func (m *mockMQTTClient) SetControlChannel(ch chan string) {
 	// Not needed for our tests
 }
 
+func (m *mockMQTTClient) PublishWithRetain(ctx context.Context, topic, payload string, retain bool) error {
+	if m.publishFunc != nil {
+		return m.publishFunc(ctx, topic, payload)
+	}
+	return nil
+}
+
+func (m *mockMQTTClient) RegisterOnConnectHandler(handler mqtt.OnConnectHandler) {
+	// Not needed for our tests
+}
+
 // createMockProcessor creates a processor suitable for testing with minimal config
 func createMockProcessor(publishFunc func(ctx context.Context, topic, payload string) error) *processor.Processor {
 	settings := &conf.Settings{

internal/conf/config.go

@@ -432,15 +432,16 @@ type RTSPSettings struct {
 
 // MQTTSettings contains settings for MQTT integration.
 type MQTTSettings struct {
-	Enabled       bool            `json:"enabled"`       // true to enable MQTT
-	Debug         bool            `json:"debug"`         // true to enable MQTT debug
-	Broker        string          `json:"broker"`        // MQTT broker URL
-	Topic         string          `json:"topic"`         // MQTT topic
-	Username      string          `json:"username"`      // MQTT username
-	Password      string          `json:"password"`      // MQTT password
-	Retain        bool            `json:"retain"`        // true to retain messages
-	RetrySettings RetrySettings   `json:"retrySettings"` // settings for retry mechanism
-	TLS           MQTTTLSSettings `json:"tls"`           // TLS/SSL configuration
+	Enabled       bool                  `json:"enabled"`       // true to enable MQTT
+	Debug         bool                  `json:"debug"`         // true to enable MQTT debug
+	Broker        string                `json:"broker"`        // MQTT broker URL
+	Topic         string                `json:"topic"`         // MQTT topic
+	Username      string                `json:"username"`      // MQTT username
+	Password      string                `json:"password"`      // MQTT password
+	Retain        bool                  `json:"retain"`        // true to retain messages
+	RetrySettings RetrySettings         `json:"retrySettings"` // settings for retry mechanism
+	TLS           MQTTTLSSettings       `json:"tls"`           // TLS/SSL configuration
+	HomeAssistant HomeAssistantSettings `json:"homeAssistant"` // Home Assistant auto-discovery settings
 }
 
 // MQTTTLSSettings contains TLS/SSL configuration for secure MQTT connections
@@ -452,6 +453,13 @@ type MQTTTLSSettings struct {
 	ClientKey          string `yaml:"clientkey,omitempty" json:"clientKey,omitempty"`   // path to client key file (managed internally)
 }
 
+// HomeAssistantSettings contains settings for Home Assistant MQTT auto-discovery.
+type HomeAssistantSettings struct {
+	Enabled         bool   `yaml:"enabled" json:"enabled"`                   // true to enable HA auto-discovery
+	DiscoveryPrefix string `yaml:"discovery_prefix" json:"discoveryPrefix"`  // HA discovery topic prefix (default: homeassistant)
+	DeviceName      string `yaml:"device_name" json:"deviceName"`            // base name for devices (default: BirdNET-Go)
+}
+
 // TelemetrySettings contains settings for telemetry.
 type TelemetrySettings struct {
 	Enabled bool   `json:"enabled"` // true to enable Prometheus compatible telemetry endpoint

internal/conf/defaults.go

@@ -235,6 +235,11 @@ func setDefaultConfig() {
 	viper.SetDefault("realtime.mqtt.retrysettings.maxdelay", 3600)
 	viper.SetDefault("realtime.mqtt.retrysettings.backoffmultiplier", 2.0)
 
+	// Home Assistant MQTT auto-discovery configuration
+	viper.SetDefault("realtime.mqtt.homeassistant.enabled", false)
+	viper.SetDefault("realtime.mqtt.homeassistant.discovery_prefix", "homeassistant")
+	viper.SetDefault("realtime.mqtt.homeassistant.device_name", "BirdNET-Go")
+
 	// Privacy filter configuration
 	viper.SetDefault("realtime.privacyfilter.enabled", true)
 	viper.SetDefault("realtime.privacyfilter.debug", false)