Skip to content

Commit

Permalink
z2m: final changes
Browse files Browse the repository at this point in the history
  • Loading branch information
Morg42 committed Dec 12, 2023
1 parent b38ced2 commit 57eb432
Show file tree
Hide file tree
Showing 15 changed files with 1,472 additions and 0 deletions.
680 changes: 680 additions & 0 deletions zigbee2mqtt/_pv_1_1_2/__init__.py

Large diffs are not rendered by default.

23 changes: 23 additions & 0 deletions zigbee2mqtt/_pv_1_1_2/locale.yaml
Original file line number Diff line number Diff line change
@@ -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'

120 changes: 120 additions & 0 deletions zigbee2mqtt/_pv_1_1_2/plugin.yaml
Original file line number Diff line number Diff line change
@@ -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)
134 changes: 134 additions & 0 deletions zigbee2mqtt/_pv_1_1_2/user_doc.rst
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 57eb432

Please sign in to comment.