From 373ab43860f5a4bcf87a8a5cc90a4d0d74fc8fa9 Mon Sep 17 00:00:00 2001 From: Nerivec <62446222+Nerivec@users.noreply.github.com> Date: Mon, 21 Oct 2024 23:00:17 +0200 Subject: [PATCH] API change for endpoint specification for bind, groups, configure reporting --- .prettierignore | 4 +++- docs/guide/usage/binding.md | 10 +++++++--- docs/guide/usage/groups.md | 5 +++-- docs/guide/usage/mqtt_topics_and_messages.md | 2 +- 4 files changed, 14 insertions(+), 7 deletions(-) diff --git a/.prettierignore b/.prettierignore index 0ee9ed84c35d8..cf493c08657da 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,2 +1,4 @@ docs/devices/*.md -pnpm-lock.yaml \ No newline at end of file +pnpm-lock.yaml +public/images/**/* +docs/images/**/* \ No newline at end of file diff --git a/docs/guide/usage/binding.md b/docs/guide/usage/binding.md index 27e8bcec610cb..ad61688fa5cf2 100755 --- a/docs/guide/usage/binding.md +++ b/docs/guide/usage/binding.md @@ -19,7 +19,7 @@ A use case for binding is, for example, the TRADFRI wireless dimmer. Binding the All commands below can also be executed via the frontend, click on your device and go to the _Bind_ tab. ::: -Binding can be configured by using either `zigbee2mqtt/bridge/request/device/bind` to bind and `zigbee2mqtt/bridge/request/device/unbind` to unbind. The payload should be `{"from": SOURCE, "to": TARGET}` where `SOURCE` and `TARGET` can be the `friendly_name` of a group or device. Example request payload: `{"from": "my_remote", "to": "my_bulb"}`, example response payload: `{"data":{"from":"my_remote","to":"my_bulb","clusters":["genScenes","genOnOff","genLevelCtrl"],"failed":[]},"status":"ok"}`. The `clusters` in the response indicate the bound/unbound clusters, `failed` indicates any failed to bind/unbind clusters. In case all clusters fail to bind the `status` is set to `error`. +Binding can be configured by using either `zigbee2mqtt/bridge/request/device/bind` to bind and `zigbee2mqtt/bridge/request/device/unbind` to unbind. The payload should be `{"from": SOURCE, "to": TARGET}` where `SOURCE` and `TARGET` can be the `friendly_name` of a group or device. Example request payload: `{"from": "my_remote", "to": "my_bulb"}`, example response payload: `{"data":{"from":"my_remote","from_endpoint":"default","to":"my_bulb","clusters":["genScenes","genOnOff","genLevelCtrl"],"failed":[]},"status":"ok"}`. The `clusters` in the response indicate the bound/unbound clusters, `failed` indicates any failed to bind/unbind clusters. In case all clusters fail to bind the `status` is set to `error`. By default all supported clusters are bound. To restrict which clusters are being bound/unbound add `clusters` to the request payload e.g. `{"from": "my_remote", "to": "my_bulb", "clusters": ["genOnOff"]}`. Possible clusters are: `genScenes`, `genOnOff`, `genLevelCtrl`, `lightingColorCtrl` and `closuresWindowCovering`. @@ -33,9 +33,13 @@ In the above example, the TRADFRI wireless dimmer would be the `SOURCE` device a **This is not applicable for most users** -By default, the first endpoint is taken. In case your device has multiple endpoints, e.g. `left` and `right`. You can specify `SOURCE` or `TARGET` as e.g. `my_switch/right` to bind/unbind the `right` endpoint. +If wanting to bind to specific endpoints instead of the default ones, specify the payload `{"from": SOURCE, "from_endpoint": SOURCE_ENDPOINT, "to": TARGET, "to_endpoint": TARGET_ENDPOINT}` where `SOURCE_ENDPOINT` and `TARGET_ENDPOINT` are the desired endpoints ID or name. Example request payload: `{"from": "my_remote", "from_endpoint": "top", "to": "my_bulb", "to_endpoint": 3}`, example response payload: `{"data":{"from":"my_remote","from_endpoint":"top","to":"my_bulb","to_endpoint":3,"clusters":["genScenes","genOnOff","genLevelCtrl"],"failed":[]},"status":"ok"}` -It is also possible to specify the endpoints in numeric, use e.g. `my_switch/3` for the `SOURCE` or `TARGET`. +`SOURCE_ENDPOINT` and `TARGET_ENDPOINT` are optional. `SOURCE_ENDPOINT` will default to the default endpoint for the `SOURCE` device if not supplied. `TARGET_ENDPOINT` behaves the same, but is only used if `TARGET` is a device. + +::: tip +The default endpoint for a device is the first registered endpoint (most often endpoint ID 1). +::: ### Binding a remote to a group diff --git a/docs/guide/usage/groups.md b/docs/guide/usage/groups.md index 088458a63386d..afde59632dd3f 100755 --- a/docs/guide/usage/groups.md +++ b/docs/guide/usage/groups.md @@ -10,6 +10,7 @@ Groups are much more efficient than controlling devices separately as it signifi ::: ## Creating a group + Groups can be created via the frontend (easiest), [MQTT](./mqtt_topics_and_messages.md#zigbee2mqttbridgerequestgroupadd) or by adding them to the `configuration.yaml` as shown below. ## Configuration @@ -46,7 +47,7 @@ Devices can also be added/removed from groups via MQTT, the possible topics are: - `zigbee2mqtt/bridge/request/group/members/remove` remove a device from a group - `zigbee2mqtt/bridge/request/group/members/remove_all` remove a device from all groups -The payload should be `{"group": GROUP, "device": DEVICE}` where `GROUP` is the `friendly_name` of the group you want to add/remove the device from, `DEVICE` is the `friendly_name` of the device you want to add/remove from the group. Example payload: `{"group":"my_group","device":"my_bulb"}`, example response: `{"data":{"device":"my_bulb","group":"my_group"},"status":"ok"}`. In case of executing a `remove_all` the `group` property in the request can be omitted. +The payload should be `{"group": GROUP, "device": DEVICE}` where `GROUP` is the `friendly_name` of the group you want to add/remove the device from, `DEVICE` is the `friendly_name` of the device you want to add/remove from the group. Example payload: `{"group":"my_group","device":"my_bulb"}`, example response: `{"data":{"device":"my_bulb","endpoint":"default","group":"my_group"},"status":"ok"}`. In case of executing a `remove_all` the `group` property in the request can be omitted. When removing a device from a group and when the group has any devices bound to it. The reporting of this members will be disabled, if you want to skip this use `skip_disable_reporting` (e.g. `{"group":"my_group","device":"my_bulb", "skip_disable_reporting": true}`). @@ -77,4 +78,4 @@ When using the `set` command, e.g. to turn on all devices in a group, a broadcas ## Adding a specific endpoint -In case you want to add a device to a group with multiple endpoints, e.g. a QBKG03LM with 2 buttons you can specify it by adding the endpoint name to the `DEVICE` in the request payload in the format of `DEVICE/ENDPOINT`. Example request payload `{"group":"my_group","device":"my_switch/right"}`. +In case you want to add a device to a group with multiple endpoints, e.g. a QBKG03LM with 2 buttons, you can specify it with the request payload `{"group": GROUP, "device": DEVICE, "endpoint": ENDPOINT}` where `ENDPOINT` is the desired endpoint name or ID. Example request payload `{"group":"my_group","device":"my_switch","endpoint":"right"}`. diff --git a/docs/guide/usage/mqtt_topics_and_messages.md b/docs/guide/usage/mqtt_topics_and_messages.md index e3a1d50e3479f..1180e3469afa1 100755 --- a/docs/guide/usage/mqtt_topics_and_messages.md +++ b/docs/guide/usage/mqtt_topics_and_messages.md @@ -454,7 +454,7 @@ By setting up reporting for the bulb it will send notifications to Zigbee2MQTT a It is a good practice to keep a balance between staying updated with relevant information and conserving energy, especially in the case of battery-powered devices. -Refer to the Configure Reporting Command in the [ZigBee Cluster Library](https://github.com/Koenkk/zigbee-herdsman/blob/master/docs/07-5123-08-Zigbee-Cluster-Library.pdf) for more information. Example payload is `{"id":"my_bulb","cluster":"genLevelCtrl","attribute":"currentLevel","minimum_report_interval":5,"maximum_report_interval":10,"reportable_change":10}`. In this case the response would be `{"data":{"id":"my_bulb","cluster":"genLevelCtrl","attribute":"currentLevel","minimum_report_interval":5,"maximum_report_interval":"10","reportable_change":10},"status":"ok"}`. +Refer to the Configure Reporting Command in the [ZigBee Cluster Library](https://github.com/Koenkk/zigbee-herdsman/blob/master/docs/07-5123-08-Zigbee-Cluster-Library.pdf) for more information. Example payload is `{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","attribute":"currentLevel","minimum_report_interval":5,"maximum_report_interval":10,"reportable_change":10}`. In this case the response would be `{"data":{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","attribute":"currentLevel","minimum_report_interval":5,"maximum_report_interval":"10","reportable_change":10},"status":"ok"}`. Parameters