Permit join MQTT API change (#3092)

* Permit join MQTT API change. * Fix pairing page.
Koenkk · Oct 11, 2024 · e03fe14 · e03fe14
1 parent f13b8c0
commit e03fe14
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 18 deletions.
diff --git a/docs/guide/usage/mqtt_topics_and_messages.md b/docs/guide/usage/mqtt_topics_and_messages.md
@@ -312,11 +312,33 @@ For requests where a device is involved you can select a specific endpoint by ad
 
 #### zigbee2mqtt/bridge/request/permit_join
 
-Allows to permit or disable joining of new devices. Allowed payloads are `{"value": true}`, `{"value": false}`, `true` or `false`. Example response: `{"data":{"value":true},"status":"ok"}`. This is not persistent (will not be saved to `configuration.yaml`).
-
-To allow joining via a specific device set the `friendly_name` in the `device` property. E.g. `{"value": true, "device": "my_bulb"}`.
-
-To allow joining for only a specific amount of time add the `time` property (in seconds). E.g. `{"value": true, "time": 20}` (will allow joining for 20 seconds).
+Allows or disallows joining of new devices for the specified duration (in seconds).
+
+Allowed payloads:
+
+> Enable for maximum duration:
+>
+> ```json
+> {"time": 254}
+> ```
+>
+> Disable:
+>
+> ```json
+> {"time": 0}
+> ```
+>
+> Enable only for device with given `friendly_name`:
+>
+> ```json
+> {"time": 60, "device": "bulb"}
+> ```
+>
+> Enable only for coordinator:
+>
+> ```json
+> {"time": 60, "device": "coordinator"}
+> ```
 
 #### zigbee2mqtt/bridge/request/health_check
 

diff --git a/docs/guide/usage/pairing_devices.md b/docs/guide/usage/pairing_devices.md
@@ -3,25 +3,21 @@
 
 # Allowing devices to join
 
-To allow devices to join the network joining has to be permitted. There are various ways to do this:
+To allow devices to join the network, joining has to be permitted. There are various ways to do this:
 
-### Frontend (recommended)
+### Frontend
 
-Enabling joining via the frontend ensures that joining is disabled automatically after 255 seconds.
-The joining button can be found in the right top.
+Enabling joining via the frontend will open the network for 254 seconds.
+The joining button can be found at the top right of the navigation bar, and also be used to close the network manually before the end of the timer.
 
-## Pairing via a specific device
+#### Pairing via a specific device
 
-To the right of Permit join (All) button is an arrow pointing down. This will allow you to pick any router to join from.
-That is not a guarantee the router is chosen. This can be useful especially for Aqara devices or a switch to a light bulb.
+To the right of `Permit join (All)` button is an arrow pointing down. This will allow you to pick the coordinator, or any router to join from specifically, instead of letting the device chose on its own.
+That is not a guarantee the router will be chosen (or remain long-term). However, this can be useful for devices that are awkward in router selection, like Aqara, or when wanting to link a switch to a light bulb.
 
-### MQTT (recommended)
+### MQTT
 
-The `zigbee2mqtt/bridge/request/permit_join` MQTT topic can be used to enable joining. It is recommended to provide a value for `time` to ensure joining is automatically disabled. See [MQTT topic and messages](./mqtt_topics_and_messages.md#zigbee2mqtt-bridge-request-permit-join) for more information.
-
-### Configuration.yaml (not recommended)
-
-By setting `permit_join: true` in your `configuration.yaml` the joining will automatically be enabled when starting Zigbee2MQTT. Joining is **not** automatically disabled.
+The `zigbee2mqtt/bridge/request/permit_join` MQTT topic can be used to enable joining. See [MQTT topic and messages](./mqtt_topics_and_messages.md#zigbee2mqtt-bridge-request-permit-join) for more information.
 
 ## Pairing