Quelltext der Seite (Zigbee2MQTT) Stolperfallen

=Fehlermeldung=

 Beim Deaktivieren der legacy_action_sensor option kommt folgende fehlermeldung frontend:api:bridge: Sending {"topic":"bridge/request/options","payload":{"options":{"homeassistant":{"legacy_action_sensor":false}},"transaction":"yaom6-1"}} [4/12/2026, 7:57:04 AM] z2m: Request 'zigbee2mqtt/bridge/request/options' failed with error: 'Extension with name HomeAssistant already present'

Das ist sehr wahrscheinlich '''ein Bug beim Umschalten der Home-Assistant-Optionen zur Laufzeit im Zigbee2MQTT-Frontend''', nicht ein Fehler in deiner Konfiguration. Ein aktueller Issue zeigt denselben Fehler beim Ein-/Ausschalten von HA-Optionen per <code>bridge/request/options</code>:

<blockquote><code>Extension with name HomeAssistant already present</code> ([https://github.com/Koenkk/zigbee2mqtt/issues/31089?utm_source=chatgpt.com GitHub])
</blockquote>
Außerdem ist <code>legacy_action_sensor</code> in der Zigbee2MQTT-Doku als Home-Assistant-Option beschrieben; wenn aktiviert, sendet Zigbee2MQTT '''nach jeder Action absichtlich ein leeres <code>action</code>'''. ([https://www.zigbee2mqtt.io/guide/configuration/homeassistant.html?utm_source=chatgpt.com Zigbee2MQTT])

<span id="was-das-für-dich-bedeutet"></span>
== Was das für dich bedeutet ==

Dein eigentliches Problem bleibt:

* <code>.../action</code> Topic ist korrekt
* <code>payload.action</code> wird danach leer
* das passt exakt zu <code>legacy_action_sensor: true</code> ([https://www.zigbee2mqtt.io/guide/configuration/homeassistant.html?utm_source=chatgpt.com Zigbee2MQTT])

Der neue Fehler bedeutet nur:

* das '''Frontend kann die HomeAssistant-Extension gerade nicht sauber live neu aufbauen'''
* daher musst du die Option '''in der Datei ändern und Zigbee2MQTT neu starten''', statt sie im Frontend umzuschalten. ([https://github.com/Koenkk/zigbee2mqtt/issues/31089?utm_source=chatgpt.com GitHub])

<span id="so-gehst-du-sauber-vor"></span>
== So gehst du sauber vor ==

Öffne deine Zigbee2MQTT-<code>configuration.yaml</code> und setze:

<syntaxhighlight lang="yaml">homeassistant:
  enabled: true
  legacy_action_sensor: false</syntaxhighlight>
Optional, wenn du die neuere Richtung nutzen willst:

<syntaxhighlight lang="yaml">homeassistant:
  enabled: true
  legacy_action_sensor: false
  experimental_event_entities: true</syntaxhighlight>
Danach '''Zigbee2MQTT komplett neu starten'''. Die Doku führt beide Optionen im <code>homeassistant</code>-Block. ([https://www.zigbee2mqtt.io/guide/configuration/homeassistant.html?utm_source=chatgpt.com Zigbee2MQTT])

<span id="wichtig-nicht-im-frontend-umschalten"></span>
== Wichtig: nicht im Frontend umschalten ==

Der Fehler kommt genau von diesem Weg:

<syntaxhighlight lang="text">zigbee2mqtt/bridge/request/options</syntaxhighlight>
also vom dynamischen Options-Update aus dem Frontend. Dafür gibt es aktuell einen bekannten Fehler bei HA-bezogenen Optionen. ([https://github.com/Koenkk/zigbee2mqtt/issues/31089?utm_source=chatgpt.com GitHub])

<span id="wenn-du-den-code-trotzdem-patchen-willst"></span>
== Wenn du den Code trotzdem patchen willst ==

Die richtige Stelle ist '''nicht''' der TS0044-Converter, sondern die HA-Extension von Zigbee2MQTT:

<syntaxhighlight lang="text">lib/extension/homeassistant.ts</syntaxhighlight>
Dort sitzt die Logik, die bei aktivem <code>legacy_action_sensor</code> direkt nach einer Action noch einmal <code>{action: &quot;&quot;}</code> publiziert. Das ist im aktuellen Quellcode so zu sehen. ([https://github.com/Koenkk/zigbee2mqtt/blob/master/lib/extension/homeassistant.ts?utm_source=chatgpt.com GitHub])

Wenn du lokal patchen willst, ist der Minimal-Patch, diese Zeile zu deaktivieren:

<syntaxhighlight lang="ts">await this.publishEntityState(data.entity, {action: ""});</syntaxhighlight>
Aber der bessere Weg ist wirklich, <code>legacy_action_sensor: false</code> in der Konfig zu setzen und Zigbee2MQTT neu zu starten. ([https://www.zigbee2mqtt.io/guide/configuration/homeassistant.html?utm_source=chatgpt.com Zigbee2MQTT])

<span id="erwartetes-verhalten-danach"></span>
== Erwartetes Verhalten danach ==

Nach dem Neustart solltest du typischerweise sehen:

* kein absichtliches Leeren von <code>payload.action</code>
* Actions weiter korrekt auf <code>zigbee2mqtt/DEIN_GERAET/action</code>
* in Home Assistant besser mit MQTT Device Triggern oder Event-Entities arbeiten statt mit dem alten Action-Sensor. Das wird in den Zigbee2MQTT-Hinweisen ebenfalls so empfohlen. ([https://github.com/Koenkk/zigbee2mqtt/issues/25461?utm_source=chatgpt.com GitHub])

<span id="wenn-du-den-patch-direkt-suchst"></span>
== Wenn du den Patch direkt suchst ==

Je nach Installation findest du die laufende JS-Datei oft eher hier als die TS-Datei:

<syntaxhighlight lang="text">/app/lib/extension/homeassistant.js</syntaxhighlight>
Die Quellreferenz bleibt aber:

<syntaxhighlight lang="text">lib/extension/homeassistant.ts</syntaxhighlight>
([https://github.com/Koenkk/zigbee2mqtt/blob/master/lib/extension/homeassistant.ts?utm_source=chatgpt.com GitHub])

=TS0044 action <nowiki>=</nowiki> Leerstring im payload=

Das liegt sehr wahrscheinlich '''nicht am TS0044_1-Converter''', sondern an der '''Home-Assistant-Integration von Zigbee2MQTT'''.

Der entscheidende Hinweis ist dein Symptom:

* '''<code>.../action</code> Topic''' enthält den richtigen Tastendruck
* '''Payload-Feld <code>action</code>''' im normalen Geräte-Topic ist danach leer
* im Frontend ist <code>action</code> ebenfalls leer

Genau dieses Verhalten ist dokumentiert, wenn '''<code>homeassistant.legacy_action_sensor</code>''' aktiviert ist: Dann wird '''nach jeder Action absichtlich ein leeres <code>action</code>''' gesendet. ([https://www.zigbee2mqtt.io/guide/configuration/all-settings.html?utm_source=chatgpt.com Zigbee2MQTT])

Außerdem zeigt der Zigbee2MQTT-Quellcode genau diese Logik in der Home-Assistant-Extension: Wenn <code>legacyActionSensor</code> aktiv ist und <code>data.message.action</code> existiert, wird direkt danach <code>publishEntityState(..., {action: &quot;&quot;})</code> aufgerufen; erst darunter wird der korrekte Wert zusätzlich auf <code>.../action</code> publiziert. ([https://raw.githubusercontent.com/Koenkk/zigbee2mqtt/master/lib/extension/homeassistant.ts GitHub])

<span id="was-bei-dir-also-wahrscheinlich-aktiv-ist"></span>
== Was bei dir also wahrscheinlich aktiv ist ==

In deiner <code>configuration.yaml</code> von Zigbee2MQTT vermutlich so etwas:

<syntaxhighlight lang="yaml">homeassistant:
  enabled: true
  legacy_action_sensor: true</syntaxhighlight>
Die Doku beschreibt genau dazu:

* <code>legacy_action_sensor</code>: aktiviert alte Action-Sensoren
* dabei wird '''nach jeder Action ein leerer <code>action</code>-Wert gesendet''' ([https://www.zigbee2mqtt.io/guide/configuration/all-settings.html?utm_source=chatgpt.com Zigbee2MQTT])

<span id="warum-recent-activity-trotzdem-richtig-ist"></span>
== Warum „Recent activity“ trotzdem richtig ist ==

Weil Zigbee2MQTT für Actions zusätzlich das separate MQTT-Topic

<syntaxhighlight lang="text">zigbee2mqtt/DEIN_GERAET/action</syntaxhighlight>
publiziert. Das ist genau der Pfad, den Zigbee2MQTT für MQTT Device Triggers verwendet. ([https://raw.githubusercontent.com/Koenkk/zigbee2mqtt/master/lib/extension/homeassistant.ts GitHub])

<span id="was-du-tun-solltest"></span>
== Was du tun solltest ==

<span id="sauberste-lösung"></span>
=== Sauberste Lösung ===

<code>legacy_action_sensor</code> deaktivieren oder entfernen:

<syntaxhighlight lang="yaml">homeassistant:
  enabled: true
  legacy_action_sensor: false</syntaxhighlight>
Danach Zigbee2MQTT neu starten.

Dann solltest du für Automationen das '''separate <code>/action</code> Topic''' oder die von Zigbee2MQTT empfohlenen '''MQTT device triggers''' verwenden. Zigbee2MQTT empfiehlt für Button-Actions in Home Assistant genau diesen Weg. ([https://www.zigbee2mqtt.io/guide/usage/integrations/home_assistant.html?utm_source=chatgpt.com Zigbee2MQTT])

<span id="falls-du-in-home-assistant-event-entities-willst"></span>
=== Falls du in Home Assistant Event-Entities willst ===

Optional:

<syntaxhighlight lang="yaml">homeassistant:
  enabled: true
  experimental_event_entities: true</syntaxhighlight>
Das ist die neuere Richtung für Action-/Event-Geräte. ([https://www.zigbee2mqtt.io/guide/configuration/all-settings.html?utm_source=chatgpt.com Zigbee2MQTT])


-----

<span id="wo-du-patchen-müsstest"></span>
== Wo du patchen müsstest ==

'''Nicht''' im TS0044_1-Geräte-Converter, denn der liefert die Action offenbar korrekt — sonst wäre das Topic <code>.../action</code> nicht richtig.

Die richtige Stelle ist in Zigbee2MQTT selbst:

<syntaxhighlight lang="text">lib/extension/homeassistant.ts</syntaxhighlight>
Dort in der Methode <code>onPublishEntityState(...)</code>.

Die relevante Stelle ist sinngemäß:

<syntaxhighlight lang="ts">if (this.legacyActionSensor && data.message.action) {
    await this.publishEntityState(data.entity, {action: ""});
}

if (settings.get().advanced.output === "json" && entity.isDevice() && entity.definition && data.message.action) {
    const value = data.message.action.toString();
    await this.publishDeviceTriggerDiscover(entity, "action", value);
    await this.mqtt.publish(`${data.entity.name}/action`, value, {});
}</syntaxhighlight>
Genau dieser Code ist im Repository sichtbar. ([https://raw.githubusercontent.com/Koenkk/zigbee2mqtt/master/lib/extension/homeassistant.ts GitHub])

<span id="wenn-du-wirklich-patchen-willst"></span>
== Wenn du wirklich patchen willst ==

Dann ist der Minimal-Patch:

<syntaxhighlight lang="ts">if (this.legacyActionSensor && data.message.action) {
    // await this.publishEntityState(data.entity, {action: ""});
}</syntaxhighlight>
oder härter:

<syntaxhighlight lang="ts">if (false && this.legacyActionSensor && data.message.action) {
    await this.publishEntityState(data.entity, {action: ""});
}</syntaxhighlight>
<span id="wichtig-dabei"></span>
== Wichtig dabei ==

Bei einer laufenden Installation patchst du meistens '''nicht''' die TypeScript-Quelldatei direkt, sondern die ausgelieferte JS-Datei im Container/Add-on. Je nach Installation liegt sie oft unter etwas wie:

<syntaxhighlight lang="text">/app/lib/extension/homeassistant.js</syntaxhighlight>
Die saubere Lösung ist aber trotzdem: '''<code>legacy_action_sensor</code> ausschalten''', statt den Code zu patchen.

<span id="kurzfazit"></span>
== Kurzfazit ==

Dein Problem ist sehr wahrscheinlich:

* '''kein TS0044_1-Bug'''
* '''kein Converter-Bug'''
* sondern das absichtliche Verhalten von '''<code>legacy_action_sensor: true</code>'''

Die beste Abhilfe ist daher, diese Option auszuschalten und mit <code>.../action</code> bzw. MQTT Device Triggers weiterzuarbeiten. ([https://www.zigbee2mqtt.io/guide/configuration/all-settings.html?utm_source=chatgpt.com Zigbee2MQTT])