diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index d7f33d37231f92..8685bab7478ec7 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -978,6 +978,7 @@ testws texinfo textboxes TFT +threadOperationalDataset ThreadStackManager ThreadStackManagerImpl Thunderboard diff --git a/docs/guides/python_chip_controller_building.md b/docs/guides/python_chip_controller_building.md index d7deba4b07dd49..d250afe174cde9 100644 --- a/docs/guides/python_chip_controller_building.md +++ b/docs/guides/python_chip_controller_building.md @@ -143,61 +143,17 @@ following command to scan all advertised Matter devices: chip-device-ctrl > ble-scan ``` -### Step 4: Connect to Matter accessory device over Bluetooth LE +### Step 4: Set network pairing credentials -The controller uses a 12-bit value called **discriminator** to discern between -multiple commissionable device advertisements. Moreover, a 27-bit **PIN code** -is used by the controller to authenticate in the device. You can find those -values in the logging terminal of the device (for example, UART). For example: - -``` -I: 254 [DL]Device Configuration: -I: 257 [DL] Serial Number: TEST_SN -I: 260 [DL] Vendor Id: 9050 (0x235A) -I: 263 [DL] Product Id: 20043 (0x4E4B) -I: 267 [DL] Hardware Version: 1 -I: 270 [DL] Setup Pin Code: 20202021 -I: 273 [DL] Setup Discriminator: 3840 (0xF00) -I: 278 [DL] Manufacturing Date: (not set) -I: 281 [DL] Device Type: 65535 (0xFFFF) -``` - -Run the following command to establish the secure connection over Bluetooth LE, -with the following assumptions for the Matter accessory device: - -- The discriminator of the device is _3840_ -- The setup pin code of the device is _20202021_ -- The temporary Node ID is _1234_ +You must provide the controller with network credentials that will be further +used in the device commissioning procedure to configure the device with a +network interface, such as Thread or Wi-Fi. -``` -chip-device-ctrl > connect -ble 3840 20202021 1234 -``` - -You can skip the last parameter, that is the Node ID. If you skip it, the -controller will assign it randomly. However, note the Node ID down, because it -is required later in the configuration process. - -At the end of the secure connection establishment, the Python controller prints -the following log: - -``` -Secure Session to Device Established -``` - -This means that the PASE (Password-Authenticated Session Establishment) session -using SPAKE2+ protocol is completed. - -### Step 5: Commission Matter accessory to the underlying network +#### Setting Thread network credentials -The main goal of the network commissioning step is to configure the device with -a network interface, such as Thread or Wi-Fi. This process provides the device -with network credentials. - -#### Commissioning a Thread device - -1. Fetch and store the current Active Operational Dataset and Extended PAN ID - from the Thread Border Router. Depending if Thread Border Router is running - on Docker or natively on Raspberry Pi, execute the following commands: +1. Fetch and store the current Active Operational Dataset from the Thread Border + Router. Depending on if the Thread Border Router is running on Docker or + natively on Raspberry Pi, execute the following commands: - For Docker: @@ -205,10 +161,6 @@ with network credentials. sudo docker exec -it otbr sh -c "sudo ot-ctl dataset active -x" 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 Done - - sudo docker exec -it otbr sh -c "sudo ot-ctl dataset extpanid” - 4fe76e9a8b5edaf5 - Done ``` - For native installation: @@ -217,10 +169,6 @@ with network credentials. sudo ot-ctl dataset active -x 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 Done - - sudo ot-ctl dataset extpanid - 4fe76e9a8b5edaf5 - Done ``` Matter specification does not define how the Thread or Wi-Fi credentials are @@ -228,73 +176,80 @@ with network credentials. datasets directly from the Thread Border Router, you might also use a different out-of-band method. -2. Inject the previously obtained Active Operational Dataset as hex-encoded - value using ZCL Network Commissioning cluster: - - > Each ZCL command has a following format: - > `zcl [arguments]` +2. Set the previously obtained Active Operational Dataset as a hex-encoded value + using the following command: ``` - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateThreadNetwork 1234 0 0 operationalDataset=hex:0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 breadcrumb=0 + chip-device-ctrl > set-pairing-thread-credential 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 ``` -3. Enable Thread interface on the device by executing the following command with - `networkID` equal to Extended PAN Id of the Thread network: - - ``` - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 1234 0 0 networkID=hex:4fe76e9a8b5edaf5 breadcrumb=0 - ``` +#### Setting Wi-Fi network credentials -#### Commissioning a Wi-Fi device +Assuming your Wi-Fi SSID is _TESTSSID_, and your Wi-Fi password is _P455W4RD_, +set the credentials to the controller by executing the following command: -1. Assuming your Wi-Fi SSID is _TESTSSID_, and your Wi-Fi password is - _P455W4RD_, inject the credentials to the device by executing the following - command: +``` +chip-device-ctrl > set-pairing-wifi-credential TESTSSID P455W4RD +``` - ``` - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 1234 0 0 ssid=str:TESTSSID credentials=str:P455W4RD breadcrumb=0 - ``` +### Step 5: Commission the Matter accessory device over Bluetooth LE -2. Enable the Wi-Fi interface on the device by executing the following command: +The controller uses a 12-bit value called **discriminator** to discern between +multiple commissionable device advertisements, as well as a 27-bit **setup PIN +code** to authenticate the device. You can find these values in the logging +terminal of the device (for example, UART). For example: - ``` - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 1234 0 0 networkID=str:TESTSSID breadcrumb=0 - ``` +``` +I: 254 [DL]Device Configuration: +I: 257 [DL] Serial Number: TEST_SN +I: 260 [DL] Vendor Id: 9050 (0x235A) +I: 263 [DL] Product Id: 20043 (0x4E4B) +I: 267 [DL] Hardware Version: 1 +I: 270 [DL] Setup Pin Code: 20202021 +I: 273 [DL] Setup Discriminator: 3840 (0xF00) +I: 278 [DL] Manufacturing Date: (not set) +I: 281 [DL] Device Type: 65535 (0xFFFF) +``` -### Step 6: Close Bluetooth LE connection. +Run the following command to establish the secure connection over Bluetooth LE, +with the following assumptions for the Matter accessory device: -After the Matter accessory device was provisioned with Thread or Wi-Fi -credentials (or both), the commissioning process is finished. The Python CHIP -controller is now using only the IPv6 traffic to reach the device, so you can -close the Bluetooth LE connection. To close the connection, run the following -command: +- The discriminator of the device is _3840_ +- The setup pin code of the device is _20202021_ +- The temporary Node ID is _1234_ ``` -chip-device-ctrl > close-ble +chip-device-ctrl > connect -ble 3840 20202021 1234 ``` -### Step 7: Discover IPv6 address of the Matter accessory. - -The Matter controller must discover the IPv6 address of the node that it -previously commissioned. Depending on the network type: +You can skip the last parameter, the Node ID, in the command. If you skip it, +the controller will assign it randomly. In that case, note down the Node ID, +because it is required later in the configuration process. -- For Thread, the Matter accessory uses SRP (Service Registration Protocol) to - register its presence on the Thread Border Router’s SRP Server. -- For Wi-Fi or Ethernet devices, the Matter accessory uses the mDNS (Multicast - Domain Name System) protocol. +After connecting the device over Bluetooth LE, the controller will go through +the following stages: -Assuming your Node ID is _1234_ (use the Node ID you noted down when you -established the secure connection over Bluetooth LE)), run the following -command: +- Establishing a secure connection that completes the PASE + (Password-Authenticated Session Establishment) session using SPAKE2+ + protocol and results in printing the following log: -``` -chip-device-ctrl > resolve 1234 -``` + ``` + Secure Session to Device Established + ``` -A notification in the log indicates that the node address has been updated. The -IPv6 address of the device is cached in the controller for later usage. +- Providing the device with a network interface using ZCL Network + Commissioning cluster commands, and the network pairing credentials set in + the previous step. +- Discovering the IPv6 address of the Matter accessory using the SRP (Service + Registration Protocol) for Thread devices, or the mDNS (Multicast Domain + Name System) protocol for Wi-Fi or Ethernet devices. It results in printing + log that indicates that the node address has been updated. The IPv6 address + of the device is cached in the controller for later usage. +- Closing the Bluetooth LE connection, as the commissioning process is + finished and the Python CHIP controller is now using only the IPv6 traffic + to reach the device. -### Step 8: Control application ZCL clusters. +### Step 6: Control application ZCL clusters. For the light bulb example, execute the following command to toggle the LED state: @@ -310,7 +265,7 @@ value somewhere between 0 and 255. chip-device-ctrl > zcl LevelControl MoveToLevel 1234 1 0 level=50 ``` -### Step 9: Read basic information out of the accessory. +### Step 7: Read basic information out of the accessory. Every Matter accessory device supports a Basic Cluster, which maintains collection of attributes that a controller can obtain from a device, such as the @@ -372,6 +327,24 @@ chip-device-ctrl > ble-scan 2021-05-29 22:28:16,246 ChipBLEMgr INFO scanning stopped ``` +### `set-pairing-thread-credential ` + +Provides the controller with Thread network credentials that will be used in the +device commissioning procedure to configure the device with a Thread interface. + +``` +chip-device-ctrl > set-pairing-thread-credential 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 +``` + +### `set-pairing-wifi-credential ` + +Provides the controller with Wi-Fi network credentials that will be used in the +device commissioning procedure to configure the device with a Wi-Fi interface. + +``` +chip-device-ctrl > set-pairing-wifi-credential TESTSSID P455W4RD +``` + ### `connect -ip
[]` Do key exchange and establish a secure session between controller and device