Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Permit join MQTT API change. #3092

Merged
merged 2 commits into from
Oct 11, 2024
Merged

Permit join MQTT API change. #3092

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b3c9e2b
Permit join MQTT API change.
Nerivec Oct 11, 2024
2ae1626
Fix pairing page.
Nerivec Oct 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 27 additions & 5 deletions docs/guide/usage/mqtt_topics_and_messages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
22 changes: 9 additions & 13 deletions docs/guide/usage/pairing_devices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down