Verwendung von Packages

[Tom Bombadil]

Da in einem anderen Thread die Frage zur Verwendung von Packages aufkam, hier der Versuch einer (bewusst kurzen) Erläuterung. Vielleicht ist das ja mal wieder ein Thema für Walter scw2wi .


Die Gründe für mich, Packages zu verwenden, sind vielfältig. Auf Anhieb fällt mir ein:

• Ich denke gern primär in 'Geräten' oder 'Systemen' statt in Entitätstypen - Fehlermeldungen kommen meist nicht als 'Die sensors: Domain ist kaputt', sondern als 'Heizung HK1 hat den Zustand: unavailable'. Da möchte ich schnell und gezielt das YAML finden können.
• Ich möchte das gesamte YAML gern zentral unterhalb eines '/conf' Verzeichnisses ablegen, um es schnell zu finden und auch schnell sichern zu können. Ohne großes Nachdenken, was denn vielleicht sonst noch irgendwo rumlungert.
• Oft brauche ich auch einfach schnell mal ein paar 'Spielentitäten', ohne dabei die eigentlich Config und mein laufendes YAML anfassen zu wollen. Dann baue ich mir eben schnell mit ein paar Zeilen ein neues Package mit Verweis auf neue Dateien, und los geht es. Mein laufendes HA-YAML bleibt dann unverändert.

Der Anfang: Bei den meisten dürfte eine gekürzte configuration.yaml in etwa wie folgt aussehen:

default_config:

homeassistant:
  name: "Zu Hause"

automation:   !include automations.yaml
script:       !include scripts.yaml
scene:        !include scenes.yaml
sensor:       !include sensors.yaml
rest:         !include rests.yaml
template:     !include templates.yaml
media_player: !include media_players.yaml
input_select: !include input_selects.yaml
input_number: !include input_numbers.yaml
input_text:   !include input_texts.yaml

Dies lässt sich mit Packages wie folgt erweitern, um ein zentrales 'conf' Verzeichnis einzubinden, in dem das gesamte YAML liegt. Wahlweise mit oder ohne Unterverzeichnisse - im Grunde ist ein Package eine Verdopplung der 'Haupt-Ebene' der configuration.yaml (ganz linke Seite) unter einem eigenen, frei wählbaren Namen. Damit werden die Konfigurationsmöglichkeiten massiv erweitert, und man kann sein YAML deutlich besser strukturieren, schlicht und ergreifend weil man Schlüssel wie sensor:, binary_sensor:, cover: etc erneut verwenden kann.

Im folgenden Beispiel werden folgende Packages definiert: diverser_jahreszeitbedingter_schnulli, lueftung, licht, heizung, raumklima, muell:. Der Name des Packages ist frei wählbar (siehe erstes Beispiel):

default_config:

homeassistant:
  name: "Zu Hause"
  
  packages:   # die Namen der Packages sind frei wählbar - sind nur Platzhalter!

    # Entitäten direkt hier im Package definieren (unschön, bläht configuration.yaml auf):
    diverser_jahreszeitbedingter_schnulli:
      sensor:
        - day_of_the_month
          [...]
      binary_sensor:
        - is_it_xmas_already
          [...]
      template:
        - sensor:
          - name: show_happy_xmas_in_december
            [...]

    # alles eingerückt in einer Datei: - sensors:, - binary_sensors: etc
    lueftung: !include conf/lueftung/lueftung.yaml

    # mehrere Dateien - Auto-Import der gesamten Verzeichnisstruktur
    licht:    !include_dir_merge_list conf/licht/

    # mehrere Dateien: sensors:, binary_sensors: etc manuell
    heizung:
      input_number:      !include conf/heizung/input_numbers.yaml
      input_datetime:    !include conf/heizung/input_datetime.yaml
      automation:        !include conf/heizung/automations.yaml
      template:          !include conf/heizung/templates.yaml
      sensor:            !include conf/heizung/statistics.yaml
      
    # mehrere Dateien: verschiedene Sensor-Dateien (nur bei einigen Domains möglich)
    raumklima:
      sensor:            !include conf/raumklima/sensors_allgemein.yaml
      sensor eg:         !include conf/raumklima/sensors_eg.yaml
      sensor og:         !include conf/raumklima/sensors_og.yaml
      sensor dg:         !include conf/raumklima/sensors_dg.yaml

    # das hier kennen wahrscheinlich viele
    muell:
      waste_collection_schedule: !include conf/muell/muellkalender.yaml
      sensor waste_collection:   !include conf/muell/muelltemplates.yaml

# ... und nur noch ganz kleiner Grabbelkram verbleibt hier in den Haupt-/Root-Einträgen:
automation:   !include conf/automations.yaml
script:       !include conf/scripts.yaml
scene:        !include conf/scenes.yaml
sensor:       !include conf/sensors.yaml
rest:         !include conf/rests.yaml
template:     !include conf/templates.yaml
media_player: !include conf/media_players.yaml
input_select: !include conf/input_selects.yaml
input_number: !include conf/input_numbers.yaml
input_text:   !include conf/input_texts.yaml

Ich hoffe, das hilft, das Grundprinzip der Packages zu verstehen - für Leute, die tief in HA eingearbeitet sind, ist diese etwas andere 'Denke' vielleicht etwas gewöhnungsbedürftig. Ich nutze Packages nun seit längerer Zeit schon sehr intensiv, um die Standardbeschränkungen der configuration.yaml zu umgehen - würde sie nicht mehr missen wollen ...

/tom

[scw2wi]

Du solltest 4 Varianten vergleichen.

1. Alles in der Configuration.yaml => sehr schnell unübersichtlich

2. Alles über includes => besser, aber teilweise immer noch recht große Files

3. include mit dir_merge_list / names => auf beliebig viele Files in Ordnern aufteilbar, aber alle typen (sensor, cover, automation) immer getrennt voneinander

4. Packages => jetzt kann man nach Themen gruppieren, also z.B. alle switches, sensoren, trigger, automationen für die Bewässerung in ein File (oder einen Ordner) zusammen.

Ich verwende derzeit nur 3, aber für große Themen könnte ich 4 mal probieren, wenn sich 3 und 4 problemlos mischen lässt.

Update: Dein Beispiel oben ist übrigens ganz schön gefährlich, ich bin da voll drauf reingefallen. Hier ein besserer Vorschlag.

automation: !include gui/automations.yaml
automation manual: !include_dir_merge_list manual_automations/​

scene: !include gui/scenes.yaml
scene manual: !include_dir_merge_list manual_scenes/

script: !include gui/scripts.yaml
script manual: !include_dir_merge_list manual_scripts/​

[Sven1973]

Ich hatte von beginn an mit zum Teil packages gearbeitet.
Nun habe ich heute das update auf 12.1 gemacht und habe massive Problme.

homeassistant:
  packages: !include_dir_merge_named integrations/​
​

nun bekomme ich eine Warnung:

grafik.png

mein nächstes Problem sind meine Sensor Templates, diese musste ich auf das neue Schema umstellen. Also habe ich das den Vorschlägen entsprechend abgeändert.

Beispiel:

  template:  
  - sensors:

    - default_entity_id: fenster_o1_karl_status
      name: Fenster O1 Karl Status
      unique_id: fenster_o1_karl_status
      state: |
        {% set b1 = states('binary_sensor.karl_kipp_2') %}
        {% set b2 = states('binary_sensor.o1_karl_km_fenster_verschlossen_2') %}
        {% if b1 == 'off' and b2 == 'on' %} geschlossen
        {% elif b1 == 'on' and b2 == 'off' %} gekippt
        {% elif b2 == 'off' %} offen
        {% elif b1 == 'on' and b2 == 'on' %} fehler
        {% else %} offen
        {% endif %}
      icon: |
        {% set b1 = states('binary_sensor.karl_kipp_2') %}
        {% set b2 = states('binary_sensor.o1_karl_km_fenster_verschlossen_2') %}
        {% if b1 == 'off' and b2 == 'on' %} kuf:fts_window_2w
        {% elif b1 == 'on' and b2 == 'off' %} kuf:fts_window_2w_tilt
        {% elif b2 == 'off' %} kuf:fts_window_2w_open
        {% elif b1 == 'on' and b2 == 'on' %} mdi:exclamation
        {% else %} kuf:fts_window_2w_open
        {% endif %}​

sensor vitocal: !include conf/vitocal.yaml
sensor kontakte: !include conf/kontakte.yaml
sensor temperatur: !include conf/temperatur.yaml
sensor cover: !include conf/cover.yaml
[/CODE]

auch hier eine Fehlermeldung.
grafik.png

irgendwas muss ich noch ändern aber ich weiß nicht was...
kann ich das alles irgendwie in packages unterbekommen?

[Sven1973]

so, ich habe jetzt das komplette System einmal zurückgesetzt.
Ich bin jetzt damit beschäftigt Packages erst einmal richtig zu konfiguriere, allerding klappt schon das nicht bei mir.

in meiner configuration.yaml sieht der Punkt "packages" wie folgt aus:

homeassistant:
  packages: !include_dir_merge_named integrations/
 
  customize:
    sensor.naechster:
      unit_of_measurement: Tage
    sensor.altpapier:
      unit_of_measurement: Tage
    sensor.bioabfall:
      unit_of_measurement: Tage
    sensor.gelbersack:
      unit_of_measurement: Tage
    sensor.restabfall:
      unit_of_measurement: Tage

sensor vitocal: !include conf/vitocal.yaml
sensor kontakte: !include conf/kontakte.yaml
sensor temperatur: !include conf/temperatur.yaml
sensor cover: !include conf/cover.yaml

template:
  - trigger:
      - trigger: event
        event_type: bubble_card_update_modules
    sensor:
      - name: "Bubble Card Modules"
        state: "saved"
        icon: "mdi:puzzle"
        attributes:
          modules: "{{ trigger.event.data.modules }}"
          last_updated: "{{ trigger.event.data.last_updated }}"​

so wird auch alles erkannt. stelle ich das ganze in der Form wie oben beschrieben um, werden meine yaml-Datein nicht mehr erkannt.

meine Verzeichnissstrucktur:
grafik.png

[scw2wi]

Ich bin gerade dabei auf das packages Schema umzusteigen und verwende dafür die Empfehlung aus der Doku.

packages: !include_dir_named packages/

Es gibt auch eine Beschreibung, was bei Verwendung von include_dir_merge_named zu beachten ist, aber das erscheint mir unnötig kompliziert und ohne Vorteile, daher bleibe ich bei der Variante ohne merge.

Der Umzug selbst ist denkbar einfach.

aus einem input_boolean File der alten Struktur mit der Entität "ib_name"

ib_name:
  name: "ib friendly name"

Wird folgender input_boolean in der neuen Struktur

input_boolean:
  ib_name:
    name: "ib friendly name"
​

Es kommt also nur die Domäne an den Anfang und der Rest rückt um 2 char nach rechts.

Ich glaub, ich kann mich mit Packages anfreunden.

[Tom Bombadil]

packages: !include_dir_merge_named integrations/

Es macht genau das, was da steht - es importiert alles unterhalb von 'integrations' (und zwar genau von nur da).
Deshalb wird Dein yaml im parallelen Verzeichnis 'conf' nicht berücksichtigt; denn das wird nirgendwo erwähnt.

Anmerkung: Ich mag diese Pauschalangabe 'packages: !include_dir_merge_named integrations' überhaupt nicht. Das ist bequem, verbaut aber komplett den Weg, weitere Zeilen unter packages: manuell hinzuzufügen. Es geht genau diese eine Zeile (nicht mehr und nicht weniger), und alles muss unter dem einen angegebenen Verzeichnis liegen. Aber ist sicher Geschmackssache.

Ich sehe zwei Wege für Dich:

1. Verschieb die Dateien aus 'conf' nach 'integrations' - oder besser, verschiebe sogar das gesamte Verzeichnis 'conf' unterhalb 'integrations'. Und behalte den derzeitigen 'Generalimport' bei (dann müssen auch in Zukunft alle package-yaml's unter integrations liegen). Die innere Struktur der verschobenen Dateien muss natürlich mit der inneren Struktur der bereits unter 'integrations' liegenden Dateien übereinstimmen - kann ich aus der Ferne nicht prüfen.
2. Oder Du baust wie folgt um:

homeassistant:
  packages:
    alter_integrationsimport: !include_dir_merge_named integrations/     # nenne es vorne wie Du willst
    conf_verzeichnis: !include_dir_merge_named conf/                     # auch beliebiger Name
    # hier ggf. später beliebig viele weitere Packages

Variante 2 hält Dir die Tür offen, später weitere Zeilen hinzuzufügen. Aber wie schon geschrieben - Geschmackssache.

/tom

[Tom Bombadil]

Es kommt also nur die Domäne an den Anfang und der Rest rückt um 2 char nach rechts.

Kommt drauf an, wie Du das als package einbinden willst. Wenn nur input_booleans in der entsprechenden YAML-Datei sind, kannst Du auch das hier machen:

homeassistant:
  packages:
    mein_erstes_package:
      input_boolean: <datei>
      sensor: <andere_datei>

Dann brauchst Du die yaml gar nicht anfassen ...

/tom

[Sven1973]

ich hatte mich auch schon für den Weg 2 entschieden und wollte es auch noch etwas weiter struckturieren:

 homeassistant:
  packages:

    knx_int: !include_dir_merge_named integrations/knx_int/
    mqtts:  !include_dir_merge_named integrations/mqtts/

​

aber das klappt nicht

grafik.png

die Datein aus dem conf Verzeichnis habe ich einzeln eingebunden

[Tom Bombadil]

Uff, aus der Ferne und ohne tiefer 'reinzuleuchten' ist es schwer zu sagen, woran es liegt.

Ich sehe im Screenshot nur Symptome, aber keine Ursachen - irgendwas im Log?
Läuft es denn, wenn Du es wie oben von mir beschrieben schreibst - also ohne gleichzeitig auch noch auf neue Strukturen umzubauen?

Muss es vielleicht hier nur 'knx:' statt 'knx_int:' heissen, weil die Integration das so braucht? (hab kein grünes Kabel im Haus, kann das nicht nachstellen)

/tom

[scw2wi]

Dann brauchst Du die yaml gar nicht anfassen ...

Jetzt frag ich mich, was einfacher ist.

Die oberste Zeile im YAML stört mich aktuell gar nicht.

Jedes einzelne Package einzeln hinzuzufügen halte ich jedoch für unnötig, da ich damit nichts gewinne.
Daher gefällt mir mein aktueller Ansatz besser.

[Tom Bombadil]

Jetzt frag ich mich, was einfacher ist.

Ist meiner Meinung nach wieder Geschmackssache. Gibt kein 'richtig' oder 'falsch' hier.

Viele mögen z.B. eine möglichst kompakte configuration.yaml - für die ist Dein Weg anzuraten. Die Extremform ist dann der Einzeiler 'packages: !include_dir_named packages/'. Verbaut -wie schon geschrieben- aber die manuelle Erfassung weiterer Pakete; man muss dann alles von Hand über Unterverzeichnisse und Dateinamen unterhalb packages/ organisieren. Und ist unter Entwicklern von Integrationen eher verpönt - ein einzelner Entwickler bestimmt die Struktur des gesamten Systems für seine kleine heilige Integration, der sich dann alle anderen Entwickler gefälligst unterzuordnen haben (aka 'Axxxlochprogrammierung' - hatte diesen Fall schon in der 'Opferrolle').

Ich mag die längere, ausführlichere Form in der configuration.yaml; das ermöglicht mir, gezielt durch ein '#' am Zeilenanfang ganz schnell das Laden einzelner Package-Domänen oder sogar des ganzen Packages und manchmal sogar von ganzen Integrationen zu verhindern (z.B. weil grad mal wieder irgendeine Integration kaputt ist - # an den Zeilenanfang, reload YAML, schwupps fertig. In der oben genannten 'Kurzform' geht für das gleiche Ergebnis das Gefrickel und Umbenennen in den Dateien und Ordnern unter packages/ los, oder das Auskommentieren ganzer YAML-Dateien ...)

/tom

[scw2wi]

man muss dann alles von Hand über Unterverzeichnisse und Dateinamen unterhalb packages/ organisieren.

Ich komm grad nicht drauf, welchen Usecase du damit meinst.

Unterhalb von packages/ hab ich eine völlig beliebige Subfolder Struktur die nur mir gefallen muss und auch für jedes Package anders sein kann, HA ist das völlig egal.

Außerhalb von packages/ hab ich meine alte Struktur, die parallel dazu weiterhin unbehelligt funktioniert.

Wenn ich einzelne Blöcke von packages/ nach außerhalb verschiebe mache ich einen shift left um 2 char, in der anderen Richtung shift right.

Dass ich einzelne Packages nicht excluden kann ist mir klar, hatte diesen Fall aber bisher auch noch nicht, und wäre mit einem einfachen "git mv" auch erledigt.

[Tom Bombadil]

Ist meiner Meinung nach wieder Geschmackssache. Gibt kein 'richtig' oder 'falsch' hier.

/tom

[Tom Bombadil]

p.s. Wie wär's denn damit? Das Beste aus beiden Welten ...

Das allererste Package 'walters_package_import' entspricht dem aktuell von Dir verwendeten Code, der Rest ist copy/paste aus meinem HA-Entwicklersystem, in dem ich einige Integrationen bei Nichtverwendung abschalte, indem die zugehörigen Entitäten einfach nicht aktiviert werden (=auskommentiert) - spart mir De-Installation und später erneute Installation der Integration in HACS, wenn ich daran weiterarbeiten will. Auch ein paar 'archivierte' YAML's aus alten Projekten sind dabei - die liegen nach wie vor da, wo sie mal waren - sind nur auskommentiert und tun somit nicht weh. Kann aber jederzeit reinschauen.

Die gezeigte Funktionalität bekommst Du mit der 'Kurzschreibweise' nur mit Kopfständen sowie Verschieben oder Auskommentieren von ganzen YAML-Dateien hin.

Aber wie schon geschrieben: Geschmackssache. Für mich funktioniert es so gut.

packages:

  walters_package_import: !include_dir_named packages/

  #
  # ---------------------------------------------------------------------
  #

  helios_vallox:          !include custom_components/helios_vallox_ventilation/user_conf.yaml

  # work in progress - switch ~400 SNMP sensors between develop or 'live' version
  tp_link_switch:         !include dev/tplink/tp_link_switch.yaml​
  # tp_link_switch:       !include conf/tplink/tp_link_switch.yaml​

  muell:
    waste_collection_schedule: !include conf/muell/muellkalender.yaml
    sensor waste_collection:   !include conf/muell/muell_templates.yaml

  espeasy:
    rest:                 !include conf/raumklima/esps_feuchte_temp.yaml

  jahreskalender:
    template:             !include conf/jahreskalender/jahreskalender.yaml

  #vitocal:               # Spielprojekt mit KNX_UF\@Sven1973; archiviert
  #  sensor:              !include dev/vitocal.yaml

  #ugreen_nas:            # alte REST Version - wird nur zu Archivzwecken aufbewahrt
  #  rest:                !include dev/nas/ugreen_nas_rest.yaml
  #  input_text:          !include dev/nas/ugreen_nas_input_text.yaml
  #  template:            !include dev/nas/ugreen_nas_template_sensors.yaml

  #trovis557x:            # wird nur beim Weiterentwickeln der Trovis-Integration aktiviert
  #  input_number:        !include dev/heizung/input_numbers.yaml
  #  input_datetime:      !include dev/heizung/input_datetime.yaml
  #  automation:          !include dev/heizung/automations.yaml
  #  template:            !include dev/heizung/templates.yaml
  #  sensor statistics:   !include dev/heizung/statistics.yaml
  #  #
  #  # ~~diese Dateien entfallen mit der Template-Umstellung 2025.12.01~~
  #  # sensor main:         !include dev/heizung/template_sensors.yaml
  #  # sensor curves:       !include dev/heizung/heating_curves.yaml
  #  # template triggers:   !include dev/heizung/trigger_actions.yaml
  #  # automation triggers: !include dev/heizung/trigger_actions.yaml
  #  # automation start:    !include dev/heizung/trigger_startup.yaml
  #  # automation update:   !include dev/heizung/trigger_updates.yaml

/tom

[scw2wi]

Mir ist schon klar, dass es kein Richtig oder Falsch gibt, sonst gäbe es ja auch nicht beide Möglichkeiten.
Ich wollte nur verstehen, welchen Vorteil du siehst, damit ich prüfen kann, ob das für mich ev. mal relevant wird.

Meine beiden Packages, die ich jetzt migriert habe, sind in komplett unterschiedlichen Folderstrukturen aufgeteil, weil sich das so angeboten hat.
Das einzige, was passen muss, ist die jeweils oberste Zeile mit der Domäne, wobei man selbst das innerhalb eines Files mischen dürfte - mach ich aber nicht.

Für das kurzfristige Excluden hab ich bei meiner Variante jetzt auch eine schnelle Lösung gefunden, obwohl ich da noch keinen Bedarf habe, aber vielleicht wäre das ja für dich ein Anreiz, mal die alternative Variante zu testen.

Rename des Subfolders thema1 zu .thema1 - und schon ist alles was darunter liegt grau und wird auch von HA ignoriert.
Man sollte in diesem Fall dann aber bei git aufpassen, dass man dort nicht auch alles mit .* excluded, sonst ist es dort auch ausgeblendet (daher war's bei mir auch grau).

Update: Wir haben uns jetzt überschnitten, aber soweit ich deinen Entwurf verstehe, wird der Folder packages/ vollständig und die Folder conf/ und dev/ nur zeilenweise included. Auch wenn ich glaube, es verstanden zu haben, so sehe ich aktuell trotzdem noch keine Verwendung für mich. Vielleich kommt das aber noch, wenn ich selbst mal Code entwickle. Ich hab das Gefühl, du hast da gerade einen sehr universellen Entwurf erstellt.