Plugin ‚matter‘ Konfiguration

plugin logo

Im folgenden sind etwaige Anforderungen und unterstützte Hardware beschrieben. Danach folgt die Beschreibung, wie das Plugin matter konfiguriert wird. Außerdem ist im folgenden beschrieben, wie das Plugin in den Item Definitionen genutzt werden kann. [1]

Es handelt sich bei diesem Plugin um ein gateway Plugin.

ACHTUNG: Dieses Plugin ist als develop gekennzeichnet. Es kann daher sein, dass es noch nicht sämtliche Funktionen unterstützt oder noch fehlerhaft ist.

Beschreibung

Matter-Controller-Plugin: Verbindung zu Matter-Geräten.

Anforderungen

  • Minimum SmartHomeNG Version: 1.12

Konfiguration

Im folgenden ist beschrieben, wie das Plugin matter konfiguriert wird. Außerdem ist im folgenden beschrieben, wie das Plugin in den Item Definitionen genutzt werden kann.

Parameter

Das Plugin verfügt über folgende Parameter, die in der Datei ../etc/plugin.yaml konfiguriert werden:

bridge_control_port

Port, auf dem bridge.js seine WebSocket-Steuer-API anbietet (nur localhost, eigenes Protokoll dieses Plugins). Muss sich zwischen mehreren Instanzen unterscheiden, aus demselben Grund wie bridge_matter_port.

  • Datentyp: int

  • Standardwert: 5561

bridge_discriminator

Kommissionierungs-Diskriminator der Bridge (12 Bit). Fest vergeben, siehe bridge_passcode. Sollte sich zwischen mehreren Instanzen unterscheiden, aus demselben Grund wie bridge_passcode.

  • Datentyp: int

  • Standardwert: 3840

bridge_matter_port

Netzwerk-Port, auf dem die Bridge ihre eigene Matter-Fabric anbietet (fuer Kommissionierung durch andere Controller wie Apple Home). Muss sich von server_sidecar_port unterscheiden, sowie zwischen mehreren Instanzen - sonst kollidieren die bridge.js-Prozesse beim Binden des Ports.

  • Datentyp: int

  • Standardwert: 5560

bridge_passcode

Kommissionierungs-Passcode der Bridge. Fest vergeben (v1 hat noch keine Webif-UI fuer eine pro-Kommissionierung generierte Kombination). Sollte sich zwischen mehreren Instanzen unterscheiden - sonst werben zwei Bridges mit identischen Kommissionierungsdaten gleichzeitig im selben LAN, was beim Scannen/Eingeben nicht mehr eindeutig einer bestimmten Instanz zuzuordnen ist.

  • Datentyp: int

  • Standardwert: 20202021

bridge_sidecar_entry

Pfad (relativ zum Plugin-Verzeichnis) zur bridge.js-Datei - dem eigenen @matter/node-Programm des Plugins fuer die Bridge-Rolle (nicht matter-server). Liegt im sidecar/-Verzeichnis, nicht bridge/, da es sich die dortigen Node.js-Abhaengigkeiten mit der Server-Rolle teilt - ein einziges npm install in plugins/matter/sidecar/ deckt beide Rollen ab.

  • Datentyp: str

  • Standardwert: sidecar/bridge.js

bridge_storage_path

Verzeichnis (relativ zum shng-Arbeitsverzeichnis) fuer die Kommissionierungsdaten der Bridge - eine eigene Matter-Identitaet, getrennt von storage_path (Server-Rolle). Muss sich zwischen mehreren Instanzen unterscheiden, aus demselben Grund wie storage_path.

  • Datentyp: str

  • Standardwert: var/matter/bridge

bridge_vendor_id

Vendor-ID der Bridge (–vendorid-Aequivalent fuer die eigene Geraete-Identitaet, nicht die Fabric wie bei server_fabric_vendor_id). Default 65521 (0xFFF1) ist der von der Matter-Spec reservierte Test-Vendor-Bereich.

  • Datentyp: int

  • Standardwert: 65521

node_binary

Pfad zum Node.js-Binary (muss die von matter-server geforderte Version erfüllen, siehe user_doc.rst)

  • Datentyp: str

  • Standardwert: node

primary_interface

Netzwerk-Interface fuer lokale Adressen (–primary-interface). Auf Hosts mit mehreren Interfaces auf demselben Subnetz kann die automatische Auswahl ein Interface wählen, über das das Zielgerät nicht erreichbar ist - dann explizit setzen (z.B. en0).

  • Datentyp: str

server_alias_base_item

Item, unter dem Alias-Definitionen liegen (direkte Kind-Items, jeweils Typ num mit dem aktuellen node_id als Wert - siehe matter_alias). Muss bereits existieren, wird vom Plugin nicht angelegt. Fehlt es, bleibt die Alias-Funktion inaktiv, ohne den Rest des Plugins zu beeinträchtigen. Sollte sich zwischen mehreren Instanzen unterscheiden, falls beide matter_alias nutzen - ein node_id ist nur innerhalb der Fabric der jeweiligen Instanz gueltig, ein geteiltes Basis-Item wuerde Aliase beider Fabrics ununterscheidbar vermischen.

  • Datentyp: str

  • Standardwert: matter.aliases

server_commission_timeout

Wartezeit (Sekunden) auf die Antwort von matter-server auf einen Kopplungsversuch (commission_with_code), bevor das Plugin selbst aufgibt. matter-server versucht dabei jede bekannte Netzwerkadresse des Geräts mit bis zu 30s Timeout und plant intern bis zu 255s für einen Kopplungsversuch ein - ein realer Versuch dauerte schon einmal ca. 3 Minuten bis zur echten Antwort. Kommt die Antwort trotzdem später als dieser Timeout, wird sie nicht verworfen, sondern im Webif nachträglich als Hinweis angezeigt. Für Tests kann ein kürzerer Wert sinnvoll sein, um schneller ein Fehlschlagen zu sehen - auf Kosten davon, öfter in den verzögerten Hinweis statt die direkte Fehlermeldung zu laufen.

  • Datentyp: int

  • Standardwert: 300

server_enable_test_net_dcl

Testgeräte mit Entwicklungs-Zertifikaten zulassen (–enable-test-net-dcl). NICHT fuer echte Geräte aktivieren.

  • Datentyp: bool

  • Standardwert: False

server_fabric_label

Fabric-Label (–default-fabric-label), das andere Controller (z.B. Apple Home, das Fabrics-Webif-Tab) für shngs eigene Fabric anzeigen. Ohne dies wäre matter-servers eigener Default „HomeAssistant“ sichtbar.

  • Datentyp: str

  • Standardwert: SmartHomeNG

server_fabric_vendor_id

Vendor-ID (–vendorid) für shngs eigene Fabric. Wirkt nur beim allerersten Anlegen der Fabric (in vorhandenen Installationen bereits in den Node-Zertifikaten verankert) - Änderung erfordert Storage-Reset und Neukopplung aller Geräte. Default 65521 (0xFFF1) ist der von der Matter-Spec reservierte Test-Vendor-Bereich; echte Vendor-IDs werden von der CSA vergeben.

  • Datentyp: int

  • Standardwert: 65521

server_sidecar_entry

Pfad (relativ zum Plugin-Verzeichnis) zur matter-server-Einstiegsdatei. matter-server hat kein CLI-Binary, daher wird die Datei direkt mit node ausgeführt.

  • Datentyp: str

  • Standardwert: sidecar/node_modules/matter-server/dist/esm/MatterServer.js

server_sidecar_port

Port, auf dem der matter-server-Sidecar seine WebSocket-API anbietet (nur localhost). Muss sich zwischen mehreren Instanzen unterscheiden - sonst kollidieren die Sidecar-Prozesse beim Binden des Ports.

  • Datentyp: int

  • Standardwert: 5580

storage_path

Verzeichnis (relativ zum shng-Arbeitsverzeichnis) für die Fabric-/Kommissionierungsdaten des Sidecars. Muss sich zwischen mehreren Instanzen unterscheiden - jede Instanz ist eine eigene Fabric, geteilter Storage wuerde die Kommissionierungsdaten der anderen Instanz beschaedigen.

  • Datentyp: str

  • Standardwert: var/matter

Item Attribute

Das Plugin unterstützt folgende Item Attribute, die in den Dateien im Verzeichnis ../items verwendet werden:

matter_alias

Alternative zu matter_node: Name einer Alias-Definition unter server_alias_base_item. Löst node_id über die interne Alias-Tabelle des Plugins auf statt fest im Item-Wert - übersteht ein Rekommissionieren (neue node_id) ohne Änderung an diesem oder abhängigen Items, sobald der Alias über das Webif umgeleitet wird.

  • Datentyp: str

matter_attribute

Attribut-ID innerhalb des Clusters. Das Item wird per Subscribe/Report aktuell gehalten (z.B. 0 fuer OnOff.OnOff)

  • Datentyp: int

matter_available

Nur-Lese-Item, das die von matter-server erkannte Erreichbarkeit des Node spiegelt (dieselbe Information wie die „verfuegbar“-Spalte im Webif, hier als echtes Item fuer eigene Logik/Struct/Visu). Braucht nur matter_node, kein Endpoint/Cluster.

  • Datentyp: bool

matter_cluster

Matter-Cluster-ID (dezimal, z.B. 6 fuer OnOff)

  • Datentyp: int

matter_command

Kommandoname innerhalb des Clusters, der bei einem Item-Write aufgerufen wird (z.B. toggle, on, off)

  • Datentyp: str

matter_command_false

Optionales zweites Kommando fuer ein Bool-Item: bei falsy Wert wird dieses statt matter_command aufgerufen (z.B. matter_command=on, matter_command_false=off - ein Item spiegelt und steuert den Zustand statt zweier getrennter Trigger-Items).

  • Datentyp: str

matter_command_params

Optionale feste Parameter fuer matter_command. Der Platzhalter „$value“ wird durch den geschriebenen Item-Wert ersetzt.

  • Datentyp: dict

matter_endpoint

Endpoint-Nummer auf dem Matter-Node

  • Datentyp: int

matter_expose_name

Bridge-Rolle: Anzeigename fuer den anderen Controller. Default: voller Item-Pfad (strukturell eindeutig; remark/Item-Name koennten mehrfach vorkommen und waeren dann in einer flachen Zubehoerliste nicht unterscheidbar). Max. 32 Zeichen (Matter-Spezifikationslimit) - laengere Werte (oder ein zu langer Item-Pfad als Default) lassen das Item unsichtbar fuer die Bridge-Rolle, mit Fehlermeldung im Log.

  • Datentyp: str

matter_expose_type

Bridge-Rolle: macht dieses Item als Matter-Bridge-Gerät fuer andere Matter-Controller (Apple Home, Google Home, …) sichtbar. switch = steuerbarer Bool-Aktor, contact = Nur-Lese-Bool-Sensor (z.B. Tuerkontakt), temperature_sensor = Nur-Lese-Zahlensensor (Grad Celsius).

  • Datentyp: str

  • Mögliche Werte:

    • switch

    • contact

    • temperature_sensor

matter_node

Matter Node-ID des Geräts (wird bei der Kommissionierung vergeben)

  • Datentyp: int

matter_switch

Kurzform fuer einen Bool-Schalter (z.B. OnOff): Attribut und beide Kommandos werden automatisch aus dem Cluster abgeleitet (siehe clusters.py SWITCH_CLUSTERS). Setzt matter_attribute/matter_command/matter_command_false nicht voraus. Fehlermeldung im Log, falls der Cluster (noch) nicht in der Tabelle steht - dann die low-level Attribute direkt verwenden.

  • Datentyp: bool

Item-Structs

Das Plugin stellt die folgenden Item-Structs zur Verfügung. Diese Informationen sind aus der plugin.yaml entnommen und möglicherweise nicht vollständig.

contact

Kontaktzustand (BooleanState.StateValue)

  • contact (bool, Kontaktzustand (BooleanState.StateValue))

electrical_power_measurement

  • electrical_power_measurement (foo, —)
    • power (num, aktuelle Leistung in W)

      • power_mw (num, aktuelle Leistung in mW)

    • voltage (num, aktuelle Spannung in V)

      • voltage_mv (num, aktuelle Spannung in mV)

      • hinweis (foo, In eigenen Tests wurde die Spannung nur einmalig beim Verbinden aktualisiert. Obwohl das Gerät die Spannung laufend misst, wird sie über Matter nicht mehr übertragen - z.B. über MQTT sehr wohl.)

    • current (num, aktueller Strom in A)

      • current_ma (num, aktueller Strom in mA)

shelly_plug_m_3gen

  • shelly_plug_m_3gen (foo, —)

shelly_plug_m_3gen_simple

  • shelly_plug_m_3gen_simple (foo, —)

    • available (bool, Gerät erreichbar)

switch

  • switch (bool, —)

    • toggle (bool, auf True setzen, um den Schaltzustand zu wechseln)

temperature_sensor

aktuelle Temperatur in °C

  • temperature_sensor (num, aktuelle Temperatur in °C)

    • temperature_raw (num, aktuelle Temperatur in 1/100 °C (Roh-Wert))

Logik Parameter

Das Plugin verfügt über folgende Parameter, die in der Datei ../etc/logic.yaml konfiguriert werden:

Keine Logik Parameter in den Metadaten beschrieben - Bitte in der README nachsehen (siehe Fußnote)

Plugin Functions

Das Plugin verfügt über folgende öffentliche Funktionen, die z.B. in Logiken aufgerufen werden können.

Keine