Merge pull request #863 from Morg42/z2m-2

z2m: complete overhaul of plugin, more generic approach
smarthomeNG · Dec 12, 2023 · 9369500 · 9369500
2 parents d66346a + 57eb432
commit 9369500
Show file tree

Hide file tree

Showing 20 changed files with 2,768 additions and 701 deletions.
diff --git a/zigbee2mqtt/__init__.py b/zigbee2mqtt/__init__.py
diff --git a/zigbee2mqtt/_pv_1_1_2/__init__.py b/zigbee2mqtt/_pv_1_1_2/__init__.py
diff --git a/zigbee2mqtt/_pv_1_1_2/locale.yaml b/zigbee2mqtt/_pv_1_1_2/locale.yaml
@@ -0,0 +1,23 @@
+# translations for the web interface
+plugin_translations:
+    # Translations for the plugin specially for the web interface
+    'Relais':             {'de': '=', 'en': 'Relay'}
+    'Mac Adresse':        {'de': '=', 'en': 'Mac Address'}
+    'IP Adresse':         {'de': '=', 'en': 'IP Address'}
+    'Firmware Version':   {'de': '=', 'en': '='}
+    'neue Firmware':      {'de': '=', 'en': 'new Firmware'}
+    'konfiguriert':       {'de': '=', 'en': 'configured'}
+    'Message Durchsatz':  {'de': '=', 'en': 'Message throughput'}
+    'letzte Minute':      {'de': '=', 'en': 'last minute'}
+    'letzte 5 Min.':      {'de': '=', 'en': 'last 5 min'}
+    'letzte 15 Min.':     {'de': '=', 'en': 'last 15 min'}
+    'Energie':            {'de': '=', 'en': 'Energy'}
+
+    # Alternative format for translations of longer texts:
+    'Durchschnittlich Messages je Minute empfangen':
+        de: '='
+        en: 'Messages per minute received on average'
+    'Durchschnittlich Messages je Minute gesendet':
+        de: '='
+        en: 'Messages per minute sent on average'
+
diff --git a/zigbee2mqtt/_pv_1_1_2/plugin.yaml b/zigbee2mqtt/_pv_1_1_2/plugin.yaml
@@ -0,0 +1,120 @@
+# Metadata for the plugin
+plugin:
+    # Global plugin attributes
+    type: gateway                  # plugin type (gateway, interface, protocol, system, web)
+    description:
+        de: 'Plugin zur Steuerung von Geräten, die mit einem Zigbee Gateway mit der Zigbee2MQTT Firmware versehen sind. Die Kommunikation erfolgt über das MQTT Module von SmartHomeNG.'
+        en: 'Plugin to control devices which are linked to Zigbee Gateway equipped with Zigbee2MQTT firmware. Communication is handled through the MQTT module of SmartHomeNG.'
+    maintainer: Michael Wenzel
+    tester: Michael Wenzel         # Who tests this plugin?
+    state: develop                 # change to ready when done with development
+    keywords: iot
+    documentation: ''
+    support: https://knx-user-forum.de/forum/supportforen/smarthome-py/1856775-support-thread-f%C3%BCr-das-zigbee2mqtt-plugin
+
+    version: 1.1.2                 # Plugin version
+    sh_minversion: 1.8.2           # minimum shNG version to use this plugin
+#    sh_maxversion:                # maximum shNG version to use this plugin (leave empty if latest)
+    py_minversion: 3.8             # minimum Python version to use for this plugin
+    multi_instance: True           # plugin supports multi instance
+    restartable: unknown
+    classname: Zigbee2Mqtt         # class containing the plugin
+
+parameters:
+    # Definition of parameters to be configured in etc/plugin.yaml (enter 'parameters: NONE', if section should be empty)
+    base_topic:
+        type: str
+        default: 'zigbee2mqtt'
+        description:
+            de: TopicLevel_1 um mit dem ZigBee2MQTT Gateway zu kommunizieren (%topic%)
+            en: TopicLevel_1 to be used to communicate with the ZigBee2MQTT Gateway (%topic%)
+
+    poll_period:
+        type: int
+        default: 300
+        valid_min: 10
+        valid_max: 3600
+        description:
+            de: Zeitabstand in Sekunden in dem das Gateway Infos liefer soll
+            en: Timeperiod in seconds in which the Gateway shall send information
+
+    read_at_init:
+        type: bool
+        default: True
+        description:
+            de: Einlesen aller Werte beim Start
+            en: Read all values at init
+
+
+item_attributes:
+    # Definition of item attributes defined by this plugin (enter 'item_attributes: NONE', if section should be empty)
+    zigbee2mqtt_topic:
+        type: str
+        mandatory: true
+        description:
+            de: TopicLevel_2 um mit dem ZigBee2MQTT Gateway zu kommunizieren; entspricht dem Friendly_Name oder Short_Name des Zigbee-Gerätes
+            en: TopicLevel_2 to be used to communicate with the ZigBee2MQTT Gateway
+
+    zigbee2mqtt_attr:
+        type: str
+        mandatory: true
+        description:
+            de: "Zu lesendes/schreibendes Attribut des ZigBee2MQTT Devices. Achtung: Nicht jedes Attribut ist auf allen Device-Typen vorhanden."
+            en: "Attribute of ZigBee2MQTT device that shall be read/written. Note: Not every attribute is available on all device types"
+        valid_list_ci:
+            - online
+            - bridge_permit_join
+            - bridge_health_check
+            - bridge_restart
+            - bridge_networkmap_raw
+            - device_remove
+            # - device_ota_update_check
+            # - device_ota_update_update
+            - device_configure
+            - device_options
+            - device_rename
+            # - device_bind
+            # - device_unbind
+            - device_configure_reporting
+            - temperature
+            - humidity
+            - battery
+            - battery_low
+            - linkquality
+            - action
+            - vibration
+            - action_group
+            - voltage
+            - angle
+            - angle_x
+            - angle_x_absolute
+            - angle_y
+            - angle_y_absolute
+            - angle_z
+            - strength
+            - last_seen
+            - tamper
+            - sensitivity
+            - contact
+            - brightness                            # Helligkeit in % [0-100]
+            - color_temp                            # Farbtemperatur in Kelvin
+            - state
+            - hue
+            - saturation
+            - color_x
+            - color_y
+            - color_mode
+
+        valid_list_description:
+            de:
+              - "<noch kein Attribut gewählt>"
+              - "Online Status des Zigbee Devices -> bool, r/o"
+
+item_structs: NONE
+    # Definition of item-structure templates for this plugin (enter 'item_structs: NONE', if section should be empty)
+
+plugin_functions: NONE
+    # Definition of plugin functions defined by this plugin (enter 'plugin_functions: NONE', if section should be empty)
+
+logic_parameters: NONE
+    # Definition of logic parameters defined by this plugin (enter 'logic_parameters: NONE', if section should be empty)
diff --git a/zigbee2mqtt/_pv_1_1_2/user_doc.rst b/zigbee2mqtt/_pv_1_1_2/user_doc.rst
@@ -0,0 +1,134 @@
+===========
+zigbee2mqtt
+===========
+
+Das Plugin dienst zur Steuerung von Zigbee Devices via Zigbee2MQTT über MQTT. Notwendige Voraussetzung ist eine
+funktionsfähige und laufende Installation von Zigbee2Mqtt. Die Installation, Konfiguration und der Betrieb ist hier
+beschrieben: https://www.zigbee2mqtt.io/
+Dort findet man ebenfalls die unterstützten Zigbee Geräte.
+
+.. attention::
+
+    Das Plugin kommuniziert über MQTT und benötigt das mqtt Modul, welches die Kommunikation mit dem MQTT Broker
+    durchführt. Dieses Modul muß geladen und konfiguriert sein, damit das Plugin funktioniert.
+
+Getestet ist das Plugin mit folgenden Zigbee-Geräten:
+
+- SONOFF SNZB-02
+- IKEA TRADFRI E1766
+- Aqara DJT11LM
+- TuYa TS0210
+- Aqara Opple 3fach Taster
+
+
+Konfiguration
+=============
+
+Die Informationen zur Konfiguration des Plugins sind unter :doc:`/plugins_doc/config/zigbee2mqtt` beschrieben.
+
+Nachfolgend noch einige Zusatzinformationen.
+
+Konfiguration des Plugins
+-------------------------
+
+Die Konfigruation des Plugins erfolgt über das Admin-Interface. Dafür stehen die folgenden Einstellungen zur Verfügung:
+
+- `base_topic`: MQTT TopicLevel_1, um mit dem ZigBee2MQTT Gateway zu kommunizieren (%topic%)
+- `poll_period`: Zeitabstand in Sekunden in dem das Gateway Infos liefer soll
+
+
+Konfiguration von Items
+-----------------------
+
+Für die Nutzung eines Zigbee Devices müssen in dem entsprechenden Item die zwei Attribute ``zigbee2mqtt_topic`` und
+``zigbee2mqtt_attr`` konfiguriert werden, wie im folgenden Beispiel gezeigt:
+
+.. code-block:: yaml
+
+    sensor:
+        temp:
+            type: num
+            zigbee2mqtt_topic: SNZB02_01
+            zigbee2mqtt_attr: temperature
+        hum:
+            type: num
+            zigbee2mqtt_topic: SNZB02_01
+            zigbee2mqtt_attr: humidity
+
+
+Dabei entspricht das Attribute ``zigbee2mqtt_topic`` dem Zigbee ``Friendly Name`` des Device bzw. dem MQTT Topic Level_2, um mit dem ZigBee2MQTT Gateway zu kommunizieren.
+
+Das Attribut ``zigbee2mqtt_attr`` entspricht dem jeweiligen Tag aus der Payload, der verwendet werden soll. Welche Tags beim jeweiligen Device verfügbar sind, kann man im WebIF des Pluigns sehen.
+
+Die folgenden Tags des Attributes ``zigbee2mqtt_attr`` sind definiert und werden vom Plugin unterstützt:
+
+- online
+- bridge_permit_join
+- bridge_health_check
+- bridge_restart
+- bridge_networkmap_raw
+- device_remove
+- device_configure
+- device_options
+- device_rename
+- device_configure_reporting
+- temperature
+- humidity
+- battery
+- battery_low
+- linkquality
+- action
+- vibration
+- action_group
+- voltage
+- angle
+- angle_x
+- angle_x_absolute
+- angle_y
+- angle_y_absolute
+- angle_z
+- strength
+- last_seen
+- tamper
+- sensitivity
+- contact
+
+
+Web Interface des Plugins
+=========================
+
+Zigbee2Mqtt Items
+-----------------
+
+Das Webinterface zeigt die Items an, für die ein Zigbee2Mqtt Device konfiguriert ist.
+
+.. image:: user_doc/assets/webif_tab1.jpg
+   :class: screenshot
+
+
+Zigbee2Mqtt Devices
+-------------------
+
+Das Webinterface zeigt Informationen zu den konfigurierten Zigbee2Mqtt Devices an, sowie etwa hinzugekommen Devices die
+in SmartHomeNG noch nicht konfiguriert (mit einem Item vebunden) sind.
+
+.. image:: user_doc/assets/webif_tab2.jpg
+   :class: screenshot
+
+
+Zigbee2Mqtt Bridge Info
+-----------------------
+
+Das Webinterface zeigt detaillierte Informationen der Zigbee2Mqtt Bridge zu jedem verbundenen Device an.
+
+.. image:: user_doc/assets/webif_tab3.jpg
+   :class: screenshot
+
+
+Broker Information
+------------------
+
+Das Webinterface zeigt Informationen zum genutzten MQTT Broker an.
+
+.. image:: user_doc/assets/webif_tab6.jpg
+   :class: screenshot