From 8c43a9caa47713902146071f7aeb8c705b98bd9b Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Sat, 22 Nov 2025 14:35:21 +0100
Subject: [PATCH 1/8] fix: add docs for new Z2M API endpoints

---
 docs/guide/usage/binding.md                  | 12 +++++
 docs/guide/usage/mqtt_topics_and_messages.md | 52 +++++++++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/docs/guide/usage/binding.md b/docs/guide/usage/binding.md
index dea1cb3d3f851..3402e5afe0f7d 100755
--- a/docs/guide/usage/binding.md
+++ b/docs/guide/usage/binding.md
@@ -56,6 +56,18 @@ To do this execute the following steps:
 3. Bind the remote to the group by sending the following MQTT message.
     - `zigbee2mqtt/bridge/request/device/bind` with payload `{"from": "my_remote", "to": "my_group"}`
 
+### Clearing bindings
+
+Using `zigbee2mqtt/bridge/request/device/binds/clear`, bindings can be all or selectively cleared.
+
+To clear all bindings, just send the topic with the payload e.g. `{"target": "my_device"}`.
+
+To selectively clear bindings by IEEE address, send the topic with the payload e.g. `{"target": "my_deivce", "ieeeList": ["0xa1a2a3a4a5a6a7a8", "0xb1b2b3b4b5b6b7b8"]}`.
+
+::: tip
+Clearing bindings will automatically adjust the cached data that Zigbee2MQTT uses internally based on the request/response. After successfully executing this requests, bindings in Zigbee2MQTT should reflect actual bindings on the device.
+:::
+
 ## Devices
 
 Not all devices support this, it basically comes down to the Zigbee implementation of the device itself. Check the device specific page for more info (can be reached via the supported devices page)
diff --git a/docs/guide/usage/mqtt_topics_and_messages.md b/docs/guide/usage/mqtt_topics_and_messages.md
index 1b139538fbe49..f0b35815d37f6 100755
--- a/docs/guide/usage/mqtt_topics_and_messages.md
+++ b/docs/guide/usage/mqtt_topics_and_messages.md
@@ -542,7 +542,13 @@ See [Binding](./binding.md).
 
 See [Binding](./binding.md).
 
-#### zigbee2mqtt/bridge/request/device/configure_reporting
+#### zigbee2mqtt/bridge/request/device/binds/clear
+
+See [Binding](./binding.md).
+
+#### zigbee2mqtt/bridge/request/device/reporting/configure
+
+_Alias: `zigbee2mqtt/bridge/request/device/configure_reporting` (deprecated)_
 
 Allows to send a Zigbee configure reporting command to a device. Zigbee devices often have attributes that can report changes in their state, such as temperature, humidity, battery level, etc. Attribute reporting allows these devices to automatically send updates when there is a change in the values of these attributes.
 One example is when you change brightness of a bulb with its remote instead of Zigbee2MQTT, the state becomes out of sync.
@@ -576,6 +582,21 @@ Notes:
 - The `reportable_change` value depends on the unit of the attribute, e.g. for temperature 100 means in general 1°C of change.
 - To specify options, e.g. the manufacturerCode use e.g. `{"id":"my_bulb","cluster":"genLevelCtrl","attribute":"currentLevel","minimum_report_interval":5,"maximum_report_interval":10,"reportable_change":10,"options":{"manufacturerCode":1234}}`
 
+#### zigbee2mqtt/bridge/request/device/reporting/read
+
+Allows to read the reporting configuration registered on a device.
+Attributes must of course be reportable, an error status will be returned for any attribute in the request that is not.
+
+Example payloads:
+
+- For one attribute: `{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","configs":[{"attribute":"currentLevel"}]}`
+- For multiple attributes: `{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","configs":[{"attribute":"currentLevel"},{"attribute":"currentFrequency"}]}`
+- For manufacturer-specific attribute: `{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","configs":[{"attribute":"currentLevel"}], "manufacturerCode": 0x1234}`
+
+::: tip
+Reading reporting config will automatically adjust the cached data that Zigbee2MQTT uses internally based on the request/response. After successfully executing this requests, reporting config in Zigbee2MQTT should reflect the actual reporting config on the device.
+:::
+
 ### Group
 
 #### zigbee2mqtt/bridge/request/group/remove
@@ -629,3 +650,32 @@ See [Touchlink](./touchlink.md).
 #### zigbee2mqtt/bridge/request/touchlink/identify
 
 See [Touchlink](./touchlink.md).
+
+### Action
+
+#### zigbee2mqtt/bridge/request/action
+
+Allows to call specific pre-defined actions, usually manufacturer-specific.
+All action names are published in `zigbee2mqtt/bridge/definitions` under `actions`.
+
+::: tip
+Specific up-to-date actions/parameters can be observed directly in the source code [https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/converters/actions.ts](https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/converters/actions.ts)
+:::
+
+##### Action: `hue_factory_reset`
+
+Allows to reset Hue devices via a manufacturer-specific Touchlink request.
+
+Parameters:
+
+- `extended_pan_id` - Hex string in `0x{id}` format - the extended PAN ID of the network the device(s) should try to join after reset. E.g. `0xa1b2c3d4e5f60123`
+- `serial_numbers` - Array of numbers - the serial numbers of the device(s) to reset. E.g. `[123456, 987654]`
+
+##### Action: `raw`
+
+::: warning
+This allows sending requests that could negatively impact or even break your network. Use with caution!
+:::
+
+Special action that allows to send entirely custom payloads. The given payload is analyzed to chose the proper method of sending (ZCL, ZDO, etc.).
+See link above for parameters details (beyond the scope of this documentation).

From 9d45231afa271a34742bc894d6f42a78a36ea600 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Tue, 25 Nov 2025 18:34:12 +0100
Subject: [PATCH 2/8] fix: match name conv changes

---
 docs/guide/usage/binding.md                  | 2 +-
 docs/guide/usage/mqtt_topics_and_messages.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/guide/usage/binding.md b/docs/guide/usage/binding.md
index 3402e5afe0f7d..33fd073522dd9 100755
--- a/docs/guide/usage/binding.md
+++ b/docs/guide/usage/binding.md
@@ -62,7 +62,7 @@ Using `zigbee2mqtt/bridge/request/device/binds/clear`, bindings can be all or se
 
 To clear all bindings, just send the topic with the payload e.g. `{"target": "my_device"}`.
 
-To selectively clear bindings by IEEE address, send the topic with the payload e.g. `{"target": "my_deivce", "ieeeList": ["0xa1a2a3a4a5a6a7a8", "0xb1b2b3b4b5b6b7b8"]}`.
+To selectively clear bindings by IEEE address, send the topic with the payload e.g. `{"target": "my_deivce", "ieee_list": ["0xa1a2a3a4a5a6a7a8", "0xb1b2b3b4b5b6b7b8"]}`.
 
 ::: tip
 Clearing bindings will automatically adjust the cached data that Zigbee2MQTT uses internally based on the request/response. After successfully executing this requests, bindings in Zigbee2MQTT should reflect actual bindings on the device.
diff --git a/docs/guide/usage/mqtt_topics_and_messages.md b/docs/guide/usage/mqtt_topics_and_messages.md
index f0b35815d37f6..7d0ffa05a59f0 100755
--- a/docs/guide/usage/mqtt_topics_and_messages.md
+++ b/docs/guide/usage/mqtt_topics_and_messages.md
@@ -591,7 +591,7 @@ Example payloads:
 
 - For one attribute: `{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","configs":[{"attribute":"currentLevel"}]}`
 - For multiple attributes: `{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","configs":[{"attribute":"currentLevel"},{"attribute":"currentFrequency"}]}`
-- For manufacturer-specific attribute: `{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","configs":[{"attribute":"currentLevel"}], "manufacturerCode": 0x1234}`
+- For manufacturer-specific attribute: `{"id":"my_bulb","endpoint":1,"cluster":"genLevelCtrl","configs":[{"attribute":"currentLevel"}], "manufacturer_code": 0x1234}`
 
 ::: tip
 Reading reporting config will automatically adjust the cached data that Zigbee2MQTT uses internally based on the request/response. After successfully executing this requests, reporting config in Zigbee2MQTT should reflect the actual reporting config on the device.

From 3aa995bc9887fd48b12d7a4de27fba658a7ff7b2 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Tue, 25 Nov 2025 18:35:00 +0100
Subject: [PATCH 3/8] fix: move hue reset note to device pages

---
 docgen/device_page_notes.ts                  | 9 +++++++++
 docs/guide/usage/mqtt_topics_and_messages.md | 9 ---------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/docgen/device_page_notes.ts b/docgen/device_page_notes.ts
index 4ab29c22977eb..7cced2b74ed6a 100644
--- a/docgen/device_page_notes.ts
+++ b/docgen/device_page_notes.ts
@@ -62,6 +62,15 @@ by pressing and holding the reset button on the bottom of the remote (next to th
 
 ${definition.description.toLowerCase().includes(' go') ? hueGo : ''}
 
+### Touchlink reset by serial numbers
+
+Using the dedicated action allows to reset Hue devices via a manufacturer-specific Touchlink request.
+
+Use the topic \`zigbee2mqtt/bridge/request/action\` with the following parameters:
+
+- \`extended_pan_id\` - Hex string in \`0x{id}\` format - the extended PAN ID of the network the device(s) should try to join after reset. E.g. \`0xa1b2c3d4e5f60123\`
+- \`serial_numbers\` - Array of numbers - the serial numbers of the device(s) to reset. E.g. \`[123456, 987654]\`
+
 ## Power-on behavior
 This device allows you to set the power-on behavior. Note that this requires at least November/December '18 firmware update of the device.
 Send a MQTT command to [\`zigbee2mqtt/FRIENDLY_NAME/set\`](../guide/usage/mqtt_topics_and_messages.md#zigbee2mqtt-friendly-name-set) with the following payload.
diff --git a/docs/guide/usage/mqtt_topics_and_messages.md b/docs/guide/usage/mqtt_topics_and_messages.md
index 7d0ffa05a59f0..a0fadce906d91 100755
--- a/docs/guide/usage/mqtt_topics_and_messages.md
+++ b/docs/guide/usage/mqtt_topics_and_messages.md
@@ -662,15 +662,6 @@ All action names are published in `zigbee2mqtt/bridge/definitions` under `action
 Specific up-to-date actions/parameters can be observed directly in the source code [https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/converters/actions.ts](https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/converters/actions.ts)
 :::
 
-##### Action: `hue_factory_reset`
-
-Allows to reset Hue devices via a manufacturer-specific Touchlink request.
-
-Parameters:
-
-- `extended_pan_id` - Hex string in `0x{id}` format - the extended PAN ID of the network the device(s) should try to join after reset. E.g. `0xa1b2c3d4e5f60123`
-- `serial_numbers` - Array of numbers - the serial numbers of the device(s) to reset. E.g. `[123456, 987654]`
-
 ##### Action: `raw`
 
 ::: warning

From 9413b4440bf74ebea3a0d6ac988eb14bb48e9b10 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Tue, 25 Nov 2025 19:57:40 +0100
Subject: [PATCH 4/8] fix: add hue sn precisions

---
 docgen/device_page_notes.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docgen/device_page_notes.ts b/docgen/device_page_notes.ts
index 7cced2b74ed6a..7f4ee2de68186 100644
--- a/docgen/device_page_notes.ts
+++ b/docgen/device_page_notes.ts
@@ -69,7 +69,7 @@ Using the dedicated action allows to reset Hue devices via a manufacturer-specif
 Use the topic \`zigbee2mqtt/bridge/request/action\` with the following parameters:
 
 - \`extended_pan_id\` - Hex string in \`0x{id}\` format - the extended PAN ID of the network the device(s) should try to join after reset. E.g. \`0xa1b2c3d4e5f60123\`
-- \`serial_numbers\` - Array of numbers - the serial numbers of the device(s) to reset. E.g. \`[123456, 987654]\`
+- \`serial_numbers\` - Array of numbers in hex (\`0x\`) or decimal format - the serial numbers of the device(s) to reset. E.g. \`[0x3A745C, 123456]\`. Unless otherwise specified, the serial numbers of the back of Hue devices is to be appended with \`0x\` so it is processed as hexadecimal, else it should be converted to decimal. E.g. \`3A745C\` should be sent as \`0x3A745C\` OR \`3830876\`.
 
 ## Power-on behavior
 This device allows you to set the power-on behavior. Note that this requires at least November/December '18 firmware update of the device.

From f40c3d666f7ad8b31912e94e10e5e5f3b2ab6012 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Wed, 26 Nov 2025 15:54:41 +0100
Subject: [PATCH 5/8] fix: add e.g. payloads for actions

---
 docs/guide/usage/mqtt_topics_and_messages.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/guide/usage/mqtt_topics_and_messages.md b/docs/guide/usage/mqtt_topics_and_messages.md
index a0fadce906d91..dab9224c92a20 100755
--- a/docs/guide/usage/mqtt_topics_and_messages.md
+++ b/docs/guide/usage/mqtt_topics_and_messages.md
@@ -658,6 +658,14 @@ See [Touchlink](./touchlink.md).
 Allows to call specific pre-defined actions, usually manufacturer-specific.
 All action names are published in `zigbee2mqtt/bridge/definitions` under `actions`.
 
+The payload for this topic takes the following form (refer to specific actions docs for what `params` should contain):
+
+`{"action":"<action_name>","params":{/* action-specific parameters here */}}`
+
+E.g.:
+
+`{"action":"just_an_example","params":{"abcd": 1, "zyx": "my_device"}}`
+
 ::: tip
 Specific up-to-date actions/parameters can be observed directly in the source code [https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/converters/actions.ts](https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/converters/actions.ts)
 :::

From df13230c572feaccab75e9661d4902057a647072 Mon Sep 17 00:00:00 2001
From: Koen Kanters <koenkanters94@gmail.com>
Date: Thu, 27 Nov 2025 20:17:59 +0100
Subject: [PATCH 6/8] Update device page notes

---
 docgen/device_page_notes.ts | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/docgen/device_page_notes.ts b/docgen/device_page_notes.ts
index 7f4ee2de68186..2a65bc0444803 100644
--- a/docgen/device_page_notes.ts
+++ b/docgen/device_page_notes.ts
@@ -34,6 +34,29 @@ Verification: [GitHub PR Comment](https://github.com/Koenkk/zigbee2mqtt.io/pull/
 ### Touchlink factory reset
 See [Touchlink](../guide/usage/touchlink.md)
 
+### Touchlink reset by serial numbers
+
+Using the dedicated action allows to reset Philips Hue devices via the serial number written on the device.
+This can be done by going to the Zigbee2QMQTT frontend -> Touchlink -> Philips Hue reset.
+
+Alternatively, you can also use MQTT directly, topic: \`zigbee2mqtt/bridge/request/action\` payload:
+
+\`\`\`json
+{
+  "action": "philips_hue_factory_reset",
+  "params": {
+    // Array of numbers in hex (\`0x\`) or decimal format - the serial numbers of the device(s) to reset.
+    // E.g. \`[0x3A745C, 123456]\`. Unless otherwise specified, the serial numbers of the back of Hue devices
+    // is to be appended with \`0x\` so it is processed as hexadecimal, else it should be converted to decimal.
+    // E.g. \`3A745C\` should be sent as \`0x3A745C\` OR \`3830876\`.
+    "serial_numbers": ["0x3A745C", "0x3830876"],
+    // Hex string in \`0x{id}\` format - the extended PAN ID of the network the device(s) should try to join after reset. E.g. \`0xa1b2c3d4e5f60123\`
+    // This field is optional. If not provided, the current network's extended PAN ID will be used.
+    "extended_pan_id": "0xa1b2c3d4e5f60123"
+  }
+}
+\`\`\`
+
 ### Hue bridge
 When the light is still connected to the Hue bridge, you can simply factory reset the light
 by removing it from the bridge via the Hue app. Orphaned lights (configured to connect to a non-existing Zigbee network) can be adopted by a Hue bridge by entering the 6 character serial number in the Philips Hue app.
@@ -62,15 +85,6 @@ by pressing and holding the reset button on the bottom of the remote (next to th
 
 ${definition.description.toLowerCase().includes(' go') ? hueGo : ''}
 
-### Touchlink reset by serial numbers
-
-Using the dedicated action allows to reset Hue devices via a manufacturer-specific Touchlink request.
-
-Use the topic \`zigbee2mqtt/bridge/request/action\` with the following parameters:
-
-- \`extended_pan_id\` - Hex string in \`0x{id}\` format - the extended PAN ID of the network the device(s) should try to join after reset. E.g. \`0xa1b2c3d4e5f60123\`
-- \`serial_numbers\` - Array of numbers in hex (\`0x\`) or decimal format - the serial numbers of the device(s) to reset. E.g. \`[0x3A745C, 123456]\`. Unless otherwise specified, the serial numbers of the back of Hue devices is to be appended with \`0x\` so it is processed as hexadecimal, else it should be converted to decimal. E.g. \`3A745C\` should be sent as \`0x3A745C\` OR \`3830876\`.
-
 ## Power-on behavior
 This device allows you to set the power-on behavior. Note that this requires at least November/December '18 firmware update of the device.
 Send a MQTT command to [\`zigbee2mqtt/FRIENDLY_NAME/set\`](../guide/usage/mqtt_topics_and_messages.md#zigbee2mqtt-friendly-name-set) with the following payload.

From affbf18eba51bda31b28f5d7663df9a842ac2551 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Thu, 27 Nov 2025 20:37:25 +0100
Subject: [PATCH 7/8] fix: add note about reportable change

---
 docs/guide/usage/mqtt_topics_and_messages.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/guide/usage/mqtt_topics_and_messages.md b/docs/guide/usage/mqtt_topics_and_messages.md
index dab9224c92a20..f003ef836eff1 100755
--- a/docs/guide/usage/mqtt_topics_and_messages.md
+++ b/docs/guide/usage/mqtt_topics_and_messages.md
@@ -573,6 +573,10 @@ The Minimum Reporting Change is like telling your device to speak up only when s
 If you set a minimum reporting change of 1 degree for a temperature sensor, it means the sensor won't bother you with updates unless the temperature changes by at least 1 degree.
 It's a way to filter out minor fluctuations and focus on important changes in the environment.
 
+::: tip NOTE
+Support for `reportable_change` depends on the type of the attribute. For e.g. a `measure`-type attribute would likely support it, but a `enum`-type attribute would not. If supplied and not supported, it is ignored.
+:::
+
 To disable reporting set the `maximum_report_interval` to `65535`.
 
 Notes:

From f2532194ce59e9d2aa8f49d8f88538ec449dcb4d Mon Sep 17 00:00:00 2001
From: Koen Kanters <koenkanters94@gmail.com>
Date: Sun, 30 Nov 2025 20:40:57 +0100
Subject: [PATCH 8/8] Feedback

---
 docgen/device_page_notes.ts | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/docgen/device_page_notes.ts b/docgen/device_page_notes.ts
index 2a65bc0444803..b4db6c56e8f64 100644
--- a/docgen/device_page_notes.ts
+++ b/docgen/device_page_notes.ts
@@ -45,18 +45,15 @@ Alternatively, you can also use MQTT directly, topic: \`zigbee2mqtt/bridge/reque
 {
   "action": "philips_hue_factory_reset",
   "params": {
-    // Array of numbers in hex (\`0x\`) or decimal format - the serial numbers of the device(s) to reset.
-    // E.g. \`[0x3A745C, 123456]\`. Unless otherwise specified, the serial numbers of the back of Hue devices
-    // is to be appended with \`0x\` so it is processed as hexadecimal, else it should be converted to decimal.
-    // E.g. \`3A745C\` should be sent as \`0x3A745C\` OR \`3830876\`.
-    "serial_numbers": ["0x3A745C", "0x3830876"],
-    // Hex string in \`0x{id}\` format - the extended PAN ID of the network the device(s) should try to join after reset. E.g. \`0xa1b2c3d4e5f60123\`
-    // This field is optional. If not provided, the current network's extended PAN ID will be used.
+    "serial_numbers": ["3A745C", "806C52"],
     "extended_pan_id": "0xa1b2c3d4e5f60123"
   }
 }
 \`\`\`
 
+- \`serial_numbers\`: The "Serial No." of the device(s) to reset (enter exactly as what is printed on the device).
+- \`extended_pan_id\`: (Optional) The extended PAN ID of the network the device(s) should try to join after reset. If not provided, the current network's extended PAN ID will be used.
+
 ### Hue bridge
 When the light is still connected to the Hue bridge, you can simply factory reset the light
 by removing it from the bridge via the Hue app. Orphaned lights (configured to connect to a non-existing Zigbee network) can be adopted by a Hue bridge by entering the 6 character serial number in the Philips Hue app.