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:

<STANDORT>-<BEREICH>-<TYP>-<NUMMER>-<FUNKTION>

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:

<domain>.<standort>_<bereich>_<typ>_<nummer>_<funktion>

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-<BEREICH>-<FUNKTION>-<NUMMER>

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

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:

<STANDORT>-<BEREICH>-<TYP>-<NUMMER>-<FUNKTION>

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.