fix: add docs for new Z2M API endpoints (#4457)

Co-authored-by: Koen Kanters <[email protected]>

Author: Nerivec

docgen/device_page_notes.ts

@@ -34,6 +34,26 @@ 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": {
+    "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.

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", "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.
+:::
+
 ## 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)

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.
@@ -567,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:
@@ -576,6 +586,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"}], "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.
+:::
+
 ### Group
 
 #### zigbee2mqtt/bridge/request/group/remove
@@ -629,3 +654,31 @@ 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`.
+
+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)
+:::
+
+##### 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).