🔌Schnittstellen

Wie Programme mit Home Assistant reden (REST, WebSocket) und wie Home Assistant mit Geräten redet (MQTT, Zigbee, Z-Wave, Matter, ESPHome). Alle Tokens sind Platzhalter, alle Adressen aus 192.0.2.0/24.

🔑Anmeldung: Long-Lived Access Token

💡 Wo gibt es das Token?

Im Benutzerprofil (Profil → Sicherheit → Langlebige Zugangstoken). Es wird nur einmal angezeigt und gilt 10 Jahre – wie ein Passwort behandeln.

⚠️ Nie in Code oder Screenshots

Tokens gehören in Umgebungsvariablen oder secrets.yaml. Hier steht überall <LONG_LIVED_ACCESS_TOKEN> – echte Tokens nimmt diese App gar nicht an.

✅ Eigener Benutzer

Für Skripte einen eigenen Benutzer ohne Admin-Rechte anlegen – dann lässt sich der Zugang getrennt sperren und im Context (user_id) erkennen.

🔄WebSocket-API Schritt für Schritt

Endpunkt /api/websocket. Diese Verbindung nutzt auch das Frontend. Die Nachrichten sind mit dem eigenen Nachrichtenbau erzeugt (Format laut developers.home-assistant.io), die Zustände stammen aus der Engine.

Schritt 1 / 13 · Tasten ← →

Verbindung

Der Client verbindet sich mit /api/websocket – über wss://, wenn TLS/Proxy davor steht.

WebSocket öffnen: ws://192.0.2.20:8123/api/websocket

🌐REST-API

Einfacher als WebSocket, aber ohne Push: gut für Skripte und einzelne Aufrufe. Alle Anfragen brauchen den Header Authorization: Bearer <TOKEN>; Port standardmäßig 8123.

Weitere: /api/config, /api/events, /api/services, /api/logbook, /api/error_log, /api/calendars, /api/config/core/check_config, DELETE /api/states/…

Action aufrufen. Antwort: Liste der States, die sich dabei geändert haben. Mit ?return_response gibt es Antwortdaten (bei Actions, die welche liefern).

Anfrage

curl -X POST \
  -H "Authorization: Bearer <LONG_LIVED_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"entity_id":"light.flur","brightness_pct":60}' \
  http://192.0.2.20:8123/api/services/light/turn_on

Antwort 200 OK

[
  {
    "entity_id": "light.flur",
    "state": "on",
    "attributes": {
      "supported_color_modes": [
        "brightness"
      ],
      "color_mode": "brightness",
      "brightness": 153,
      "friendly_name": "esp-flur Flurlicht",
      "supported_features": 40
    },
    "last_changed": "2026-09-25T19:30:00.000+00:00",
    "last_reported": "2026-09-25T19:30:00.000+00:00",
    "last_updated": "2026-09-25T19:30:00.000+00:00",
    "context": {
      "id": "01M3D0QHP0EVTYHPPW5RG0XSRY",
      "parent_id": null,
      "user_id": null
    }
  }
]

📨MQTT-Discovery

Geräte können sich selbst bei Home Assistant anmelden, indem sie eine Konfiguration auf ein bestimmtes Topic veröffentlichen.

componentdevice_classnode_id (optional)object_idGerätename

Discovery-Topic

homeassistant/sensor/esp-garten/temperatur/config

Format: <discovery_prefix>/<component>/[<node_id>/]<object_id>/config, Präfix standardmäßig „homeassistant“.

Payload (JSON) → homeassistant/sensor/esp-garten/temperatur/config

{
  "name": "Temperatur",
  "device_class": "temperature",
  "state_topic": "garten/esp-garten/temperatur/state",
  "unit_of_measurement": "°C",
  "state_class": "measurement",
  "availability_topic": "garten/esp-garten/status",
  "unique_id": "esp_garten_temperatur",
  "device": {
    "identifiers": [
      "esp_garten"
    ],
    "name": "Gartenhaus",
    "manufacturer": "Eigenbau",
    "model": "ESP32"
  }
}

Ergebnis in HA

sensor.gartenhaus_temperatur

Löschen

Leere Nachricht (retained) auf dasselbe Config-Topic.

Neuer ist die Geräte-Discovery: ein Topic homeassistant/device/<object_id>/config mit allen Entitäten unter cmps (components) – weniger Nachrichten, gemeinsame Geräteangaben. Zigbee2MQTT und ESPHome (im MQTT-Modus) erzeugen solche Discovery-Nachrichten automatisch.

📶Funk- und Geräteprotokolle

🐝 Zigbee · ZHA

Integration im Core: spricht über einen Zigbee-Koordinator (USB- oder Netzwerk-Stick) direkt mit den Geräten. Kein MQTT nötig, alles in der HA-Oberfläche.

Gerät ~~Funk~~ Stick ─USB─ ZHA (im Core) ─▶ Entitäten

📨 Zigbee · Zigbee2MQTT

Eigenes Projekt (als App oder Container) mit eigener Weboberfläche und sehr großer Geräteliste. Es übersetzt Zigbee in MQTT; Home Assistant bindet die Geräte per MQTT-Discovery ein.

Gerät ~~Funk~~ Stick ─ Z2M ─MQTT─ Broker ─MQTT─ HA

🌊 Z-Wave · Z-Wave JS

Die Z-Wave-Integration verbindet sich per WebSocket mit einem Z-Wave-JS-Server – üblicherweise die App „Z-Wave JS“ bzw. Z-Wave JS UI. Bei Container-Installationen betreibt man den Server selbst.

Gerät ~~Funk~~ Stick ─ Z-Wave JS Server ─WS─ HA

🧵 Matter & Thread

Matter ist ein herstellerübergreifender Standard über WLAN, Ethernet oder Thread. HA nutzt die App „Matter Server“ (WebSocket). Anlernen per Companion-App über Bluetooth; dank Multi-Admin gleichzeitig in Apple Home, Google Home und HA. IPv6 im Netz ist Pflicht; Thread-Geräte brauchen einen Thread-Border-Router. Offiziell unterstützt nur unter Home Assistant OS.

Thread-Gerät ~~802.15.4~~ Border Router ─IPv6─ Matter Server ─WS─ HA

🔌 ESPHome

Firmware für ESP32/ESP8266 aus einer YAML-Beschreibung. Geräte werden per mDNS gefunden und über die Native API (TCP-Port 6053, Protobuf, optional mit Noise-Verschlüsselung) angebunden – schnell und ohne Broker.

ESP32 (ESPHome) ─Native API :6053─ HA

📡 MQTT allgemein

Publish/Subscribe über einen Broker (z. B. Mosquitto). Viele Eigenbau- und Tasmota/Shelly-Geräte sprechen MQTT; mit Discovery erscheinen sie automatisch als Geräte in HA.

Gerät ─publish─▶ Broker ─subscribe─▶ HA

# ESPHome-Gerät „esp-flur“ (Ausschnitt, Werte erfunden)
esphome:
  name: esp-flur
esp32:
  board: esp32dev
wifi:
  ssid: "Musterhaus-WLAN"
  password: "beispiel-passwort"
api:
  encryption:
    key: "<PLATZHALTER-SCHLÜSSEL>"      # Noise-PSK, Base64
light:
  - platform: monochromatic
    name: "Flurlicht"
    output: pwm_flur
output:
  - platform: ledc
    id: pwm_flur
    pin: GPIO16
# → in HA: light.esp_flur_flurlicht (hier im Musterhaus umbenannt zu light.flur)