HomeAssistant Namenskonventionen Hier ist eine BookStack-taugliche Dokumentation mit neutralem Standort. Du kannst sie direkt als Seite in BookStack einfügen. Namenskonvention für Home-Assistant-, Zigbee- und Smart-Home-Geräte 1. Ziel der Namenskonvention Diese Namenskonvention dient dazu, Geräte, Sensoren, Aktoren, Automationen und technische Komponenten in Home Assistant eindeutig, lesbar und langfristig wartbar zu benennen. Sie orientiert sich gedanklich an strukturierten Gebäudeautomationssystemen wie KNX oder GLT, ist jedoch für Home Assistant, Zigbee, MQTT, WLAN-Geräte, Kameras und weitere Integrationen praxisnah angepasst. Ziel ist eine einheitliche Struktur für: Geräte Entitäten Automationen Szenen Dashboards Dokumentation Fehlersuche spätere Erweiterungen 2. Grundstruktur Die empfohlene Namensstruktur lautet: ---- Beispiel: SITE-GARTEN-BWV-01-RASEN Bedeutung: SITE = neutraler Standortcode GARTEN = Bereich / Raum / Zone BWV = Gerätetyp, hier Bewässerungsventil 01 = laufende Nummer RASEN = Funktion oder konkrete Zone 3. Standortcode Der Standortcode beschreibt den Installationsort neutral und ohne personenbezogene oder vollständige Adressangabe. Empfohlene neutrale Standortcodes: SITE HAUS HOME OBJ01 STANDORT01 Für produktive Umgebungen mit mehreren Standorten empfiehlt sich: OBJ01 OBJ02 OBJ03 Beispiele: OBJ01-GARTEN-BWV-01-RASEN OBJ01-TECH-ZBC-01-SONOFF OBJ01-EG-BEW-01-FLUR Wenn nur ein Standort vorhanden ist, reicht auch: HOME-GARTEN-BWV-01-RASEN oder: SITE-GARTEN-BWV-01-RASEN 4. Bereiche Der Bereich beschreibt Raum, Etage, Außenbereich oder technische Zone. Empfohlene Bereichscodes: TECH Technik / Server / Netzwerk EG Erdgeschoss OG Obergeschoss DG Dachgeschoss KG Keller GARTEN Garten HOF Hof / Einfahrt AUSSEN Allgemeiner Außenbereich GARAGE Garage CARPORT Carport BAD Badezimmer KUECHE Küche WOHNEN Wohnzimmer SCHLAF Schlafzimmer BUERO Büro FLUR Flur Beispiele: SITE-TECH-ZBC-01-SONOFF SITE-GARTEN-BWV-01-RASEN SITE-EG-BEW-01-FLUR SITE-GARAGE-STE-01-WERKBANK 5. Gerätetypen und Kürzel Zentrale Technik HA Home Assistant RPI Raspberry Pi SRV Server NAS Netzwerkspeicher SW Netzwerk-Switch AP Access Point RTR Router FW Firewall ZBC Zigbee Coordinator ZBR Zigbee Router / Repeater MQTT MQTT-Broker Licht und Strom LIC Licht / Leuchte LAM Lampe STE Steckdose REL Relais DIM Dimmer SCH Schalter TAS Taster Sensorik TEMP Temperatursensor HUM Luftfeuchtesensor FEU Bodenfeuchtesensor BEW Bewegungsmelder PIR PIR-Bewegungsmelder PRES Präsenzsensor TUR Tür-/Fensterkontakt FEN Fensterkontakt RAUCH Rauchmelder WASS Wassersensor HELL Helligkeitssensor BAT Batteriesensor Bewässerung BWV Bewässerungsventil BWP Bewässerungspumpe BWS Bewässerungssensor REGEN Regensensor FEU Bodenfeuchtesensor Klima und Energie THERM Thermostat HK Heizkörper KLIMA Klimagerät PV Photovoltaik WR Wechselrichter AKKU Batteriespeicher ZAEHL Zähler ENERG Energiemessgerät Sicherheit und Kamera CAM Kamera NVR Videorekorder DOOR Türklingel / Doorbell ALARM Alarmgerät SIR Sirene LOCK Schloss 6. Nummerierung Die Nummer ist zweistellig und beginnt bei 01 . Beispiele: 01 02 03 Nicht empfohlen: 1 2 3 Grund: Zweistellige Nummern sortieren sauberer und bleiben bei größeren Installationen übersichtlich. Beispiele: SITE-GARTEN-BWV-01-RASEN SITE-GARTEN-BWV-02-BEET SITE-GARTEN-BWV-03-GEWAESHAUS 7. Funktion oder Zone Die Funktion beschreibt den konkreten Zweck, die Zone oder den Einsatzort. Beispiele: RASEN BEET TERRASSE GEWAESHAUS HAUSTUER EINFAHRT WERKBANK FLUR SERVER Beispiele vollständiger Gerätenamen: SITE-GARTEN-BWV-01-RASEN SITE-GARTEN-BWV-02-BEET SITE-GARTEN-FEU-01-RASEN SITE-GARTEN-FEU-02-BEET SITE-TECH-ZBC-01-SONOFF SITE-EG-BEW-01-FLUR SITE-GARAGE-STE-01-WERKBANK 8. Home-Assistant-Entitäten Home Assistant wandelt Gerätenamen meist in kleingeschriebene Entitäten mit Unterstrichen um. Aus: SITE-GARTEN-BWV-01-RASEN wird idealerweise: switch.site_garten_bwv_01_rasen sensor.site_garten_bwv_01_rasen_battery sensor.site_garten_bwv_01_rasen_linkquality Empfohlene Entitätsstruktur: .____ Beispiele: switch.site_garten_bwv_01_rasen sensor.site_garten_feu_01_rasen binary_sensor.site_eg_tur_01_haustuer camera.site_aussen_cam_01_einfahrt light.site_eg_lic_01_flur 9. Beispiele für Zigbee-Geräte Zigbee Coordinator Gerätename: SITE-TECH-ZBC-01-SONOFF Beschreibung: Zigbee Coordinator für Home Assistant / ZHA Mögliche Entitäten: sensor.site_tech_zbc_01_sonoff_status sensor.site_tech_zbc_01_sonoff_linkquality Bewässerungsventil Gerätename: SITE-GARTEN-BWV-01-RASEN Mögliche Entität: switch.site_garten_bwv_01_rasen Beschreibung: Zigbee-Bewässerungsventil für die Rasenbewässerung Bodenfeuchtesensor Gerätename: SITE-GARTEN-FEU-01-RASEN Mögliche Entitäten: sensor.site_garten_feu_01_rasen_moisture sensor.site_garten_feu_01_rasen_battery sensor.site_garten_feu_01_rasen_temperature Bewegungsmelder Gerätename: SITE-EG-BEW-01-FLUR Mögliche Entität: binary_sensor.site_eg_bew_01_flur_motion Steckdose Gerätename: SITE-GARAGE-STE-01-WERKBANK Mögliche Entität: switch.site_garage_ste_01_werkbank 10. Automationen Automationen sollten ebenfalls nach einem einheitlichen Muster benannt werden. Empfohlene Struktur: AUTO--- Beispiele: AUTO-GARTEN-BEWAESSERUNG-01 AUTO-GARTEN-BEWAESSERUNG-RASEN-MORGENS AUTO-EG-LICHT-FLUR-BEWEGUNG AUTO-AUSSEN-KAMERA-EINFAHRT-BEWEGUNG Für Home Assistant kann der Anzeigename sprechender sein: Bewässerung Garten Rasen morgens Licht Flur bei Bewegung einschalten Kamera Einfahrt Bewegung melden Die interne Entität kann daraus werden: automation.bewaesserung_garten_rasen_morgens automation.licht_flur_bei_bewegung_einschalten 11. Beispiel: Bewässerungsautomation Gerät: SITE-GARTEN-BWV-01-RASEN Entität: switch.site_garten_bwv_01_rasen Automation: AUTO-GARTEN-BEWAESSERUNG-RASEN-MORGENS Beispielhafte Automation: alias: AUTO-GARTEN-BEWAESSERUNG-RASEN-MORGENS description: Bewässert den Rasen morgens für 15 Minuten. trigger: - platform: time at: "06:00:00" condition: [] action: - service: switch.turn_on target: entity_id: switch.site_garten_bwv_01_rasen - delay: "00:15:00" - service: switch.turn_off target: entity_id: switch.site_garten_bwv_01_rasen mode: single Wichtig: Bewässerungsventile sollten immer mit automatischer Abschaltung betrieben werden. Nicht empfohlen: nur einschalten Empfohlen: einschalten → definierte Dauer warten → ausschalten 12. Regeln für gute Namen Verwenden Großbuchstaben für Gerätenamen Bindestriche als Trenner klare Bereichscodes klare Typkürzel zweistellige Nummern sprechende Funktionsbezeichnung Beispiel: SITE-GARTEN-BWV-01-RASEN Vermeiden Herstellernamen als Hauptname unverständliche Zigbee-/Tuya-Bezeichnungen Leerzeichen Umlaute Sonderzeichen zu lange freie Namen Nicht empfohlen: Tuya Valve TS0601 Bewässerung neu Garten Ding Ventil 1 Besser: SITE-GARTEN-BWV-01-RASEN 13. Umgang mit Umlauten Für technische Namen sollten Umlaute vermieden werden. Empfohlene Schreibweise: Ä → AE Ö → OE Ü → UE ß → SS Beispiele: KUECHE TUER GEWAESHAUS AUSSEN Nicht empfohlen: Küche Tür Gewächshaus Außen 14. Empfohlene Startstruktur Für eine typische Home-Assistant-Installation kann folgender Anfang verwendet werden: SITE-TECH-HA-01 SITE-TECH-ZBC-01-SONOFF SITE-TECH-MQTT-01 SITE-GARTEN-BWV-01-RASEN SITE-GARTEN-FEU-01-RASEN SITE-EG-BEW-01-FLUR SITE-AUSSEN-CAM-01-EINFAHRT SITE-GARAGE-STE-01-WERKBANK 15. Dokumentationsvorlage für einzelne Geräte Für jedes Gerät sollte in BookStack eine kurze Gerätedokumentation gepflegt werden. Gerätename SITE-GARTEN-BWV-01-RASEN Gerätetyp Zigbee-Bewässerungsventil Bereich Garten Funktion Bewässerung der Rasenfläche Integration Home Assistant / ZHA Protokoll Zigbee Entitäten switch.site_garten_bwv_01_rasen sensor.site_garten_bwv_01_rasen_battery sensor.site_garten_bwv_01_rasen_linkquality Automationen AUTO-GARTEN-BEWAESSERUNG-RASEN-MORGENS Hinweise Das Ventil muss in Automationen immer mit automatischer Abschaltung verwendet werden. 16. Zusammenfassung Die empfohlene Namenskonvention lautet: ---- Beispiel: SITE-GARTEN-BWV-01-RASEN Für Home Assistant entstehen daraus saubere Entitäten wie: switch.site_garten_bwv_01_rasen Diese Struktur ist: lesbar erweiterbar KNX-/GLT-nah für Automationen geeignet für Dokumentation geeignet für spätere Fehlersuche hilfreich Sie sollte konsequent für alle neuen Geräte, Entitäten und Automationen verwendet werden.