Tutorial: Publikowanie komunikatu MQTT Discovery, który trafia do panelu energii

MQTT Discovery opisuje czujnik w Home Assistant. Osobny temat przenosi odczyty. Panel energii korzysta następnie z odpowiednich danych i statystyk. Każdy etap wymaga osobnej kontroli: poprawny JSON nie gwarantuje działającej encji ani wykresu energii.

1. Najpierw określenie mierzonej wielkości

Przykład dotyczy skumulowanego poboru energii elektrycznej w kWh. Licznik zwykle rośnie, lecz może rozpocząć ponownie od zera, dlatego pasuje tu total_increasing. Licznik całkowitego zużycia bez resetów może korzystać z total bez last_reset. Licznik bilansujący, którego wartość rośnie i maleje, wymaga innego traktowania; total_increasing błędnie interpretowałoby rzeczywiste spadki.

Moc w W opisuje chwilowe tempo przepływu energii, a energia w kWh — zgromadzoną ilość. Aktualne wersje Home Assistant obsługują również odpowiednie czujniki mocy w polach mocy panelu: device_class: power z state_class: measurement. Zmiana etykiety W na kWh nie przelicza wartości.

2. Publikacja poprawnej konfiguracji czujnika

Warunki wstępne to dostępny broker, skonfigurowana integracja MQTT i włączone Discovery z właściwym prefiksem. Przykład dla pojedynczego komponentu używa homeassistant/sensor/example_meter_import/config. Identyfikatory w temacie Discovery dopuszczają litery, cyfry, podkreślenia i łączniki, a nie dowolny tekst.

Plik energy-discovery.json opisuje fikcyjny licznik. Stały identyfikator musi pozostać unikalny w instalacji. Nazwa wyświetlana może zmieniać się niezależnie.

{
  "name": "Imported energy",
  "state_topic": "example/meter/import_kwh",
  "unique_id": "example_meter_import",
  "device_class": "energy",
  "unit_of_measurement": "kWh",
  "state_class": "total_increasing",
  "expire_after": 900,
  "device": {
    "identifiers": [
      "example_meter"
    ],
    "name": "Example meter"
  }
}

state_topic jest wymagany dla czujnika MQTT. Pozostałe pola zależą od potrzebnej funkcji. Unikalny identyfikator umożliwia zarządzanie przez rejestr encji i pokazane powiązanie z urządzeniem; nie stanowi ogólnego wymogu panelu energii. Discovery urządzenia przez wspólny komunikat device używa innego formatu z dodatkowymi polami obowiązkowymi.

3. Dostępna konfiguracja i świeże odczyty

Przykład zachowuje konfigurację u brokera przez Retain. Alternatywą jest ponowne wysłanie Discovery po komunikacie startowym Home Assistant, zwykle online w temacie homeassistant/status. Po Discovery potrzebne są również aktualne stany. Retain jest sposobem dostarczania danych, a nie obowiązkowym polem ani gwarancją zapisu na dysku na wypadek awarii brokera.

Poniższe polecenia wymagają klientów Mosquitto w wersji co najmniej 2.1, ponieważ korzystają z -o. Plik mqtt-client.conf zawiera adres brokera, ustawienia TLS i dane logowania jako opcje, po jednej w wierszu. Ograniczone uprawnienia pliku chronią dane dostępowe; hasło nie trafia do wiersza poleceń. W starszych wersjach alternatywą jest domyślny plik konfiguracji klienta. Plik nie może zawierać opcji Retain dla publikacji stanów.

mosquitto_pub -o ./mqtt-client.conf -q 1 -r \
  -t homeassistant/sensor/example_meter_import/config \
  -f energy-discovery.json
mosquitto_pub -o ./mqtt-client.conf -q 1 \
  -t example/meter/import_kwh -m '1234.500'
mosquitto_pub -o ./mqtt-client.conf -q 1 \
  -t example/meter/import_kwh -m '1234.625'

Najpierw wykonywane jest tylko polecenie konfiguracji. Przed wysłaniem obu odczytów encja i subskrypcja stanu muszą być gotowe; udana publikacja nie dowodzi przetworzenia Discovery. Podczas migracji trzeba również usunąć istniejący zachowany odczyt z tematu stanu. Kolejne komunikaty bez Retain nie kasują starszej zachowanej wartości.

Różnica między przykładowymi odczytami wynosi 0,125 kWh. Przykład jest przeznaczony dla odizolowanego czujnika testowego; fikcyjne odczyty nie powinny trafić do historii rzeczywistego licznika. Publikacja powinna odbywać się regularnie, z zapasem wobec ustawionego czasu ważności 900 sekund.

Komunikaty stanu celowo pomijają -r. Przy expire_after stary zachowany odczyt mógłby wrócić po przeładowaniu i ponownie wyglądać na świeży. Komunikaty dostępności Birth i Will mogą dodatkowo sygnalizować utratę połączenia. Nie dowodzą aktualności fizycznego pomiaru.

4. Osobna kontrola każdego etapu

• Discovery: Subskrypcja dokładnego tematu konfiguracji oraz kontrola błędów MQTT w Home Assistant. Poprawny składniowo JSON może naruszać schemat czujnika.
• Odczyt: W example/meter/import_kwh powinna występować liczba z kropką dziesiętną, bez jednostki. Subskrypcja tej gałęzi nie obejmuje homeassistant/....
• Statystyki: Kontrola klasy energii, jednostki kWh, właściwej klasy sumy oraz aktywnego Recorder. Błędy statystyk i niedostępne wartości wymagają wyjaśnienia przed interpretacją wykresu.
• Panel: Wybór czujnika w polu energii pobranej. Statystyki krótkoterminowe powstają co pięć minut, długoterminowe co godzinę. Pierwszy odczyt ustala punkt odniesienia; nie oznacza zużycia od instalacji. Pełny wykres nie jest gwarantowany bezpośrednio po Discovery.

Niespodziewane spadki wymagają sprawdzenia licznika i klasy stanu. Reset oraz rzeczywisty ujemny przepływ energii są różnymi zdarzeniami. Sumowanie liczników resetujących się w różnych chwilach może tworzyć sztuczne wartości. Osobne źródła w panelu unikają tego konkretnego problemu sumowania.

mosquitto_pub -o ./mqtt-client.conf -q 1 -r \
  -t homeassistant/sensor/example_meter_import/config -n

Źródła

• MQTT discovery
• MQTT sensor
• Energy FAQ
• Long-term statistics
• Sensor state classes
• Mosquitto publisher
• Mosquitto broker persistence