Skip to content

Comments

feat(mqtt): add native Home Assistant MQTT Discovery integration (SCR-278)#279

Merged
Starosdev merged 3 commits intodevelopfrom
feature/SCR-278-mqtt-homeassistant-integration
Feb 24, 2026
Merged

feat(mqtt): add native Home Assistant MQTT Discovery integration (SCR-278)#279
Starosdev merged 3 commits intodevelopfrom
feature/SCR-278-mqtt-homeassistant-integration

Conversation

@Starosdev
Copy link
Owner

Summary

  • Add native MQTT Discovery support so Scrutiny drives auto-appear as Home Assistant devices
  • Each drive creates 5 HA entities: temperature, health status, power-on hours, power cycle count, and problem binary sensor
  • Uses Last Will and Testament (LWT) for automatic offline detection in HA
  • Async publishing via goroutines so MQTT never blocks API responses
  • Publishes discovery on device registration, state on SMART uploads, and removes devices on archive/delete
  • Loads all active devices on startup via LoadInitialData (mirrors existing Prometheus metrics pattern)
  • Disabled by default; enable via web.mqtt.enabled: true or SCRUTINY_WEB_MQTT_ENABLED=true

Files Created

File Purpose
webapp/backend/pkg/mqtt/client.go MQTT client wrapper (paho, LWT, auto-reconnect)
webapp/backend/pkg/mqtt/discovery.go HA MQTT Discovery message builders (5 entities per drive)
webapp/backend/pkg/mqtt/publisher.go High-level publish orchestration
webapp/backend/pkg/mqtt/discovery_test.go 16 discovery tests
webapp/backend/pkg/mqtt/publisher_test.go 7 publisher/state payload tests
webapp/backend/pkg/web/middleware/mqtt.go Gin middleware to inject publisher
webapp/backend/pkg/web/handler/mqtt_helpers.go Shared MQTT helper functions for handlers

Files Modified

File Change
go.mod Added paho.mqtt.golang v1.5.0 dependency
webapp/backend/pkg/config/config.go Added web.mqtt.* config defaults
webapp/backend/pkg/web/server.go AppEngine struct, middleware registration, lifecycle
webapp/backend/pkg/web/handler/upload_device_metrics.go Publish state after SMART upload
webapp/backend/pkg/web/handler/register_devices.go Publish discovery on device registration
webapp/backend/pkg/web/handler/delete_device.go Remove from HA on device deletion
webapp/backend/pkg/web/handler/archive_device.go Remove from HA on device archive
webapp/backend/pkg/web/handler/unarchive_device.go Re-publish to HA on device unarchive
example.scrutiny.yaml Documented MQTT config section

Configuration

web:
  mqtt:
    enabled: false                      # SCRUTINY_WEB_MQTT_ENABLED
    broker: "tcp://localhost:1883"       # SCRUTINY_WEB_MQTT_BROKER
    username: ""                        # SCRUTINY_WEB_MQTT_USERNAME
    password: ""                        # SCRUTINY_WEB_MQTT_PASSWORD
    client_id: "scrutiny"               # SCRUTINY_WEB_MQTT_CLIENT_ID
    topic_prefix: "homeassistant"       # SCRUTINY_WEB_MQTT_TOPIC_PREFIX
    qos: 1                              # SCRUTINY_WEB_MQTT_QOS
    retain: true                        # SCRUTINY_WEB_MQTT_RETAIN

Linked Issues

Closes #278

Test plan

  • 23 new unit tests pass (discovery message structure, state payload, status mapping)
  • Full test suite passes with zero regressions
  • Both scrutiny and collector-metrics binaries build cleanly
  • go vet clean (no new warnings)
  • Manual integration test with Mosquitto broker and Home Assistant

Add MQTT publishing so Scrutiny drives auto-appear as Home Assistant
devices with sensors for temperature, health status, power-on hours,
power cycle count, and a problem binary sensor. Disabled by default;
enable via web.mqtt.enabled config or SCRUTINY_WEB_MQTT_ENABLED env var.
@Starosdev Starosdev added enhancement New feature or request backend Backend/Go related labels Feb 24, 2026
@Starosdev Starosdev linked an issue Feb 24, 2026 that may be closed by this pull request
13 tasks
- Handle unchecked error returns on publish calls (errcheck)
- Pass heavy structs by pointer instead of value (gocritic/hugeParam)
- Reorder StatePayload fields for optimal alignment (govet/fieldalignment)
- Use index-based range loop to avoid 384-byte copies (gocritic/rangeValCopy)
- Pass device by pointer in publishStateSync (gocritic/hugeParam)
- Reorder StatePayload fields for optimal alignment (govet/fieldalignment)
@Starosdev Starosdev merged commit c1af8fa into develop Feb 24, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend Backend/Go related enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(mqtt): add native Home Assistant MQTT Discovery integration

1 participant