|
| 1 | +# Thread Border Router usage |
| 2 | + |
| 3 | +This document describes the use of the Thread Border router and secondary |
| 4 | +network interface for a Matter application |
| 5 | + |
| 6 | +<hr> |
| 7 | + |
| 8 | +- [Thread Border Router usage](#thread-border-router-usage) |
| 9 | + - [Thread Border Router overview](#thread-border-router-overview) |
| 10 | + - [Using the Thread Border Router management cluster](#using-the-thread-border-router-management-cluster) |
| 11 | + - [Using the Secondary Network commissioning interface](#using-the-secondary-network-commissioning-interface) |
| 12 | + - [Using the Thread credential sharing mechanism](#using-the-thread-credential-sharing-mechanism) |
| 13 | + |
| 14 | +<hr> |
| 15 | + |
| 16 | +<a name="thread-border-router-overview"></a> |
| 17 | + |
| 18 | +## Thread Border Router overview |
| 19 | + |
| 20 | +This section contains an overview of the Border Router architecture and |
| 21 | +describes the general use cases. |
| 22 | + |
| 23 | +<a name="using-the-thread-border-router-management-cluster"></a> |
| 24 | + |
| 25 | +## Using the Thread Border Router management cluster |
| 26 | + |
| 27 | +The Thread Border Router management cluster allows provisioning of the Thread |
| 28 | +interface using a Matter commissioner. |
| 29 | + |
| 30 | +After the device has been provisioned over WIFI the set active dataset command |
| 31 | +can be used to configure the Thread active dataset on the border router. Once |
| 32 | +the dataset is set successfully the Thread network interface will be enabled and |
| 33 | +the device will create a new PAN or join an existing one if already present. |
| 34 | +Note that this command cannot be used on a device that already has an active |
| 35 | +dataset configured. In this situation the set pending dataset command must be |
| 36 | +used instead. |
| 37 | + |
| 38 | +Before using the set active dataset command a fail-safe timer must be armed |
| 39 | +(recommend using a timeout of 120 seconds): |
| 40 | + |
| 41 | +``` |
| 42 | +ubuntu@ubuntu:~$ ./chip-tool generalcommissioning arm-fail-safe timeout-seconds 1 node-id 0 |
| 43 | +``` |
| 44 | + |
| 45 | +Then an active dataset in HEX TLV format (the same type used to provision a |
| 46 | +Matter over Thread device using the `ble-thread` command) can be used to |
| 47 | +provision the Border Router. What the active dataset should be is outside the |
| 48 | +scope of this README but as an example one can be obtained from the OpenThread |
| 49 | +cli on an already provisioned device using the `dataset active -x` command. |
| 50 | + |
| 51 | +Note that the Thread Border Router management cluster has been set to endpoint 2 |
| 52 | +in the zap file. |
| 53 | + |
| 54 | +``` |
| 55 | +ubuntu@ubuntu:~$ ./chip-tool threadborderroutermanagement set-active-dataset-request hex:<active-dataset> node id 2 |
| 56 | +``` |
| 57 | + |
| 58 | +If the active dataset command is successful, a commissioning complete command |
| 59 | +must be send to disarm the fail-safe timer and commit the configuration to |
| 60 | +non-volatile storage. |
| 61 | + |
| 62 | +``` |
| 63 | +ubuntu@ubuntu:~$ ./chip-tool-19-jul generalcommissioning commissioning-complete node-id 0 |
| 64 | +``` |
| 65 | + |
| 66 | +Note that this command cannot be used on a device that already has an active |
| 67 | +dataset configured. In this situation the set pending dataset command must be |
| 68 | +used instead. |
| 69 | + |
| 70 | +``` |
| 71 | +ubuntu@ubuntu:~$ ./chip-tool threadborderroutermanagement set-pending-dataset-request hex:<active-dataset> node id 2 |
| 72 | +``` |
| 73 | + |
| 74 | +To read the active dataset of an already provisioned device, for example to make |
| 75 | +a joining Border Router use the same Thread network as an already configured |
| 76 | +one, the get active dataset command can be used: |
| 77 | + |
| 78 | +``` |
| 79 | +ubuntu@ubuntu:~$ ./chip-tool-19-jul threadborderroutermanagement get-active-dataset-request node-id 2 |
| 80 | +``` |
| 81 | + |
| 82 | +<a name="using-the-secondary-network-commissioning-interface"></a> |
| 83 | + |
| 84 | +## Using the Secondary Network commissioning interface |
| 85 | + |
| 86 | +To use the secondary network commissioning interface over Thread the device must |
| 87 | +not be provisioned over WIFI. The regular `ble-thread` pairing is used as for |
| 88 | +any other Matter over Thread device. The chip-tool will read all the endpoints |
| 89 | +of the device and discover Thread network commissioning cluster on endpoint 3 |
| 90 | +and use that to provision the device. As for any other Matter over Thread device |
| 91 | +a Thread Border Router is required in this case. |
| 92 | + |
| 93 | +``` |
| 94 | +ubuntu@ubuntu:~$ ./chip-tool pairing ble-thread node-id hex:<active-dataset> 20202021 3840 |
| 95 | +``` |
| 96 | + |
| 97 | +<a name="using-the-thread-credential-sharing-mechanism"></a> |
| 98 | + |
| 99 | +## Using the Thread credential sharing mechanism |
| 100 | + |
| 101 | +The details about using the credential sharing mechanism are in the ot-nxp repo |
| 102 | +border router application |
| 103 | +[readme](https://github.com/NXP/ot-nxp/blob/v1.4.0-pvw1/examples/br/README-OTBR.md). |
| 104 | +See `Ephemeral Key functionality` section. |
| 105 | + |
| 106 | +Note that all OpenThread commands executed from then Matter CLI must have |
| 107 | +`otcli` added before the command. |
0 commit comments