Gebeurtenissen in Home Assistant

Home Assistant (HA) core is ‘event-driven’ wat inhoudt dat alles wat binnen HA gebeurt, een event is. Een lamp die aangaat, een sensor die iets waarneemt, een automatisering die uitgevoerd wordt, etc…

De ‘Recorder‘ integratie in Home Assistant houdt alle gebeurtenissen bij die zich binnen Home Assistant afspelen en bewaard het in een tabel genaamd ‘events‘. Ze kunnen bekeken worden via de menu-optie ‘Geschiedenis‘ en/of ‘Logboek‘. Beiden zijn afhankelijk van de ‘Recorder‘ waarin instellingen gemaakt kunnen worden die direct van invloed zijn op het bijhouden van gebeurtenissen. M.a.w. als in de recorder een intiteit excluded wordt, zullen de geschiedenis en het logboek hier geen data van kunnen tonen.

Elke entiteit binnen HA is een ‘state‘ en heeft een ‘identity‘ in de vorm <domain>.<object_id> en een domain kan zijn light, switch, input_boolean, lock, fan, climate, etc… Bijvoorbeeld een lamp in de keuken boven de eettafel: light.keuken_eettafel waarvan de stateon‘ is en eventueel attributen zoals kleur en helderheid. Alle entiteiten met hun ‘state’ worden in een database bijgehouden en een tabel genaamd ‘states‘.

Voorbeeld: Indien een lamp wordt aangezet, zal de ‘last_updated_ts‘ en de ‘last_changed_ts‘ aangepast worden omdat de ‘state’ van ‘off’ naar ‘on’ gaat. Indien de lamp van de kleur blauw naar de kleur groen gaat, zal alleen de ‘last_updated_ts‘ aangepast worden, de ‘state’ blijft immers ‘on’.

Meer over data in HA lees je hier.

Recorder

Het aantal dagen dat statistieken bijgehouden worden is afhankelijk van de instelling in ‘Recorder’ die standaard op 10 dagen staat. Dit wordt het ‘purgen‘ van data genoemd.

Deze optie kan aangepast worden door de ‘purge_keep_days‘ aan te geven. ‘auto_purge‘ staat standaard aan en gebeurt op 04:12 elke nacht waarbij alles ouder dan purge_keep_days verwijderd wordt uit de database.

Een uitzondering hierop zijn de zogenaamde ‘long-term-statistics’ voor sensors. Deze worden elk uur verzameld en blijven altijd bewaard in de database. De sensor dient dan over een ‘state_class‘ te beschikken met een waarde ‘measurement‘, ‘total’ of ‘total_increasing‘. Bijvoorbeeld een temperatuur sensor:

De recorder-optie dient in configuration.yaml te worden ingesteld, bijvoorbeeld:

recorder:
  purge_keep_days: 7 ## keep events for only 1 week

Wellicht handig om de recorder te voorzien van white-list (include) en black-list (exclude) opties. Dit kan per domain, bijvoorbeeld switch of light, of per entiteit. Een voorbeeld:

recorder:
  purge_keep_days: 7
  include:
    domains:
      - sensor
      - light
      - switch
  exclude:
    entities:
      - sensor.last_boot
      - sensor.date
    entity_globs:
      - sensor.buienradar_*

Hiermee zullen alle light en switch events worden bijgehouden maar voor de sensor worden uitzonderingen gemaakt. Hiervan zal sensor.last_boot en sensor.date niet bewaard blijven en alle events van sensor.buienradar worden ook niet bewaard.

Handmatig purgen

Het purgen kan als service aangeroepen worden (via Ontwikkelhulpmiddelen) binnen HA om dit handmatig uit te voeren. Tevens kan hierbij de optie ‘repack‘ aangegeven worden om de database opnieuw op te bouwen en zodoende disk-ruimte te besparen.

Een andere service is om entities te purgen waarbij je op kunt geven welke ruimte, domain of entity er ge-purged dient te worden.

Meer informatie over recorder vind je hier.

History (Geschiedenis)

Informatie over gebeurtenissen binnen Home Assistant kunnen wel in de database opgenomen worden (via de ‘Recorder’) maar toch niet getoond worden in de ‘Geschiedenis’ door de ‘history’ te voorzien van white-list (include) en black-list (exclude) opties. Dit kan per domain, bijvoorbeeld switch of light, of per entiteit. De history-opties dienen ook in configuration.yaml te komen. Bijvoorbeeld:

history:
  include:
    domains:
      - sensor
      - switch
      - media_player
  exclude:
    entities:
     - sensor.last_boot
     - sensor.date

Net zoals bij de Recorder, zijn de include- en exclude-opties apart in te stellen voor domains of entiteiten.

De Gebeurtenissen in HA:

Meer informatie over history vind je hier.

Logbook

Net als de Geschiedenis, is er ook een Logboek binnen Home Assistant en ook deze is afhankelijk van de instellingen in ‘Recorder’. De logbook optie (Logboek via het menu) laat HA gebeurtenissen zien in reverse order, dus de nieuwste eerst en dan aflopend v.w.b. date/time.

Ook hier weer kunnen domains en/of entiteiten in een exclude of include opgenomen worden om ze wel of niet zichtbaar te maken in het logboek. bijvoorbeeld:

logbook:
  include:
    domains:
      - alarm_control_panel
      - light
    entity_globs:
      - binary_sensor.*_occupancy
  exclude:
    entities:
      - light.kitchen_light

Het logboek in HA:

Lokale database

Standaard worden alle gebeurtenissen (die niet excluded zijn) bijgehouden in een lokale database. Dit is een SQLLite database genaamd home-assistant_v2.db en staat in de config directory van Home Assistant. Uitzonderingen daarop zijn database-instellingen in ‘Recorder’.

Informatie over jouw HA database vind je via Instellingen -> Systeem -> Herstelwerkzaamheden en vervolgens het menu rechtsboven (met de drie stippen) selecteren en kiezen voor Systeeminformatie. Scroll naar beneden voor de Recorder info:

In het geval van Home Assistant op een Raspberry Pi met alleen een SD-card voor de data, kan het aantal gebeurtenissen die geschreven worden in de database, en dus op de SD-card, van invloed zijn op de ‘lifetime’ van de SD-card. In dit geval is het beter om in ieder geval de commit_interval ruimer te zetten dan de standaard 5 seconden of onnodige gebeurtenissen te excluden, of de data wegschrijven naar een externe database.

Externe database

In de recorder kan een externe database geconfigureerd worden. De instellingen daarvoor staan in configuration.yaml onder ‘recorder’, bijvoorbeeld:

recorder:
  db_url: mysql://user:password@SERVER_IP/DB_NAME?charset=utf8mb4

voor alle opties en instellingen voor externe databases, zie deze pagina.

Lange tijd bewaren van gebeurtenissen

Om gebeurtenissen (die niet onder ‘long-term-statistics’ vallen) lange tijd te bewaren kan natuurlijk de ‘purge_keep_days’ aangepast worden maar een wildgroei van de database wordt hiermee aangemoedigd en is niet aanbevolen en zal de response-tijd van Home Assistant aanzienlijk verslechteren. De aanbevolen optie is om de entiteiten waarvan long-term-data opgeslagen dient te worden in een aparte database te plaatsen, bijvoorbeeld naar een time-series database zoals influxDB.