From 2564e0d4bb203719c7a24f425848e00b0d6c26e1 Mon Sep 17 00:00:00 2001 From: Rohit Jadhav Date: Tue, 28 Dec 2021 12:24:25 +0530 Subject: [PATCH] ESP32 examples Readme.md update with chip-tool instructions --- examples/all-clusters-app/esp32/README.md | 91 ++++++++++--------- examples/bridge-app/esp32/README.md | 81 +++++++++-------- examples/lock-app/esp32/README.md | 76 +++++++++------- .../esp32/README.md | 70 +++++++------- 4 files changed, 165 insertions(+), 153 deletions(-) diff --git a/examples/all-clusters-app/esp32/README.md b/examples/all-clusters-app/esp32/README.md index f63bb3ab9d1443..8fec264d7d6908 100644 --- a/examples/all-clusters-app/esp32/README.md +++ b/examples/all-clusters-app/esp32/README.md @@ -119,6 +119,20 @@ that are currently supported include `ESP32-DevKitC` (default), $ idf.py -p /dev/tty.SLAB_USBtoUART monitor +## Setting up chip-tool + +See [the build guide](../../../docs/guides/BUILDING.md#prerequisites) for +general background on build prerequisites. + +Building the example application is quite straightforward. It can either be done +as part of an overall "build everything" build: + +``` +./gn_build.sh +``` + +which puts the binary at `out/debug/standalone/chip-tool` + ## Commissioning and cluster control Commissioning can be carried out using WiFi, BLE or Bypass. @@ -160,73 +174,60 @@ your network configuration. To erase it, simply run. $ idf.py -p /dev/tty.SLAB_USBtoUART erase_flash -### Setting up Python Controller - -Once ESP32 is up and running, we need to set up a device controller to perform -commissioning and cluster control. - -- Set up python controller. +#### Commission a device using chip-tool - $ cd {path-to-connectedhomeip} - $ ./scripts/build_python.sh -m platform +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. -- Execute the controller. +#### Commission a device over BLE - $ source ./out/python_env/bin/activate - $ chip-device-ctrl +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. -### Commissioning over BLE +The command below uses the default values hard-coded into the debug versions of +the ESP32 all-clusters-app to commission it onto a Wi-Fi network: -- Establish the secure session over BLE. BLE is the default mode in the - application and is configurable through menuconfig. + $ chip-tool pairing ble-wifi ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} 0 20202021 3840 - - chip-device-ctrl > ble-scan - - chip-device-ctrl > connect -ble 3840 20202021 135246 +or equivalently: - Parameters: - 1. Discriminator: 3840 (configurable through menuconfig) - 2. Setup-pin-code: 20202021 (configurable through menuconfig) - 3. Node ID: Optional. - If not passed in this command, then it is auto-generated by the controller and displayed in the output of connect. - The same value should be used in the next commands. - We have chosen a random node ID which is 135246. + $ chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 0 20202021 3840 -- Add credentials of the Wi-Fi network you want the ESP32 to connect to, using - the `AddOrUpdateWiFiNetwork` command and then enable the ESP32 to connect to - it using `EnableWiFiNetwork` command. In this example, we have used - `TESTSSID` and `TESTPASSWD` as the SSID and passphrase respectively. +#### Pair a device over IP - - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 +The command below will discover devices with long discriminator 3840 and try to +pair with the first one it discovers using the provided setup code. - - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 + $ chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 -- Close the BLE connection to ESP32, as it is not required hereafter. +The command below will discover devices based on the given QR code (which +devices log when they start up) and try to pair with the first one it discovers. - - chip-device-ctrl > close-ble + $ chip-tool pairing qrcode ${NODE_ID_TO_ASSIGN} MT:####### -- Resolve DNS-SD name and update address of the node in the device controller. +### Forget the currently-commissioned device - - chip-device-ctrl > resolve 135246 + $ chip-tool pairing unpair ### Cluster control -- After successful commissioning, use the OnOff cluster commands to control - the OnOff attribute. This allows you to toggle a parameter implemented by - the device to be On or Off. +### onoff - `chip-device-ctrl > zcl OnOff Off 135246 1 1` +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name as well as an endpoint id. -- Use the LevelControl cluster commands to control the CurrentLevel attribute. - This allows you to control the brightness of the led. +The endpoint id must be between 1 and 240. - `chip-device-ctrl > zcl LevelControl MoveToLevel 135246 1 1 level=10 transitionTime=0 optionMask=0 optionOverride=0` + $ chip-tool onoff on 12344321 1 -- For ESP32C3-DevKitM, use the ColorControl cluster commands to control the - CurrentHue and CurrentSaturation attribute. This allows you to control the - color of on-board LED. +The client will send a single command packet and then exit. - `zcl ColorControl MoveToHue 135246 1 1 hue=100 direction=0 transitionTime=0 optionsMask=0 optionsOverride=0` - `zcl ColorControl MoveToSaturation 135245 1 1 saturation=200 transitionTime=0 optionsMask=0 optionsOverride=0` +### levelcontrol + +```bash +Usage: + ./out/debug/chip-tool levelcontrol move-to-level Level=10 TransitionTime=0 OptionMask=0 OptionOverride=0 12344321 1 +``` ### Flashing app using script diff --git a/examples/bridge-app/esp32/README.md b/examples/bridge-app/esp32/README.md index 7622731572e944..ddca9adf6e3b9e 100644 --- a/examples/bridge-app/esp32/README.md +++ b/examples/bridge-app/esp32/README.md @@ -151,6 +151,20 @@ make sure the IDF_PATH has been exported(See the manual setup steps above). $ idf.py -p /dev/tty.SLAB_USBtoUART monitor +## Setting up chip-tool + +See [the build guide](../../../docs/guides/BUILDING.md#prerequisites) for +general background on build prerequisites. + +Building the example application is quite straightforward. It can either be done +as part of an overall "build everything" build: + +``` +./gn_build.sh +``` + +which puts the binary at `out/debug/standalone/chip-tool` + ## Commissioning and cluster control Commissioning can be carried out using WiFi, BLE or Bypass. @@ -192,63 +206,50 @@ your network configuration. To erase it, simply run. $ idf.py -p /dev/tty.SLAB_USBtoUART erase_flash -### Setting up Python Controller +#### Commission a device using chip-tool -Once ESP32 is up and running, we need to set up a device controller to perform -commissioning and cluster control. +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. -- Set up python controller. +#### Commission a device over BLE - $ cd {path-to-connectedhomeip} - $ ./scripts/build_python.sh -m platform +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. -- Execute the controller. +The command below uses the default values hard-coded into the debug versions of +the ESP32 all-clusters-app to commission it onto a Wi-Fi network: - $ source ./out/python_env/bin/activate - $ chip-device-ctrl + $ chip-tool pairing ble-wifi ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} 0 20202021 3840 -### Commissioning over BLE +or equivalently: -- Establish the secure session over BLE. BLE is the default mode in the - application and is configurable through menuconfig. + $ chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 0 20202021 3840 - - chip-device-ctrl > ble-scan - - chip-device-ctrl > connect -ble 3840 20202021 135246 +#### Pair a device over IP - Parameters: - 1. Discriminator: 3840 (configurable through menuconfig) - 2. Setup-pin-code: 20202021 (configurable through menuconfig) - 3. Node ID: Optional. - If not passed in this command, then it is auto-generated by the controller and displayed in the output of connect. - The same value should be used in the next commands. - We have chosen a random node ID which is 135246. +The command below will discover devices with long discriminator 3840 and try to +pair with the first one it discovers using the provided setup code. -- Add credentials of the Wi-Fi network you want the ESP32 to connect to, using - the `AddOrUpdateWiFiNetwork` command and then enable the ESP32 to connect to - it using `EnableWiFiNetwork` command. In this example, we have used - `TESTSSID` and `TESTPASSWD` as the SSID and passphrase respectively. + $ chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 - - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 +The command below will discover devices based on the given QR code (which +devices log when they start up) and try to pair with the first one it discovers. - - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 + $ chip-tool pairing qrcode ${NODE_ID_TO_ASSIGN} MT:####### -- Close the BLE connection to ESP32, as it is not required hereafter. +### Forget the currently-commissioned device - - chip-device-ctrl > close-ble + $ chip-tool pairing unpair -- Resolve DNS-SD name and update address of the node in the device controller. - Get fabric ID using `get-fabricid` and use the decimal value of compressed - fabric id. +### Cluster control - - chip-device-ctrl > get-fabricid +### onoff - - chip-device-ctrl > resolve 135246 +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name as well as an endpoint id. -### Cluster Control +The endpoint id must be between 1 and 240. -- After successful commissioning, use the OnOff cluster commands to control - the OnOff attribute on different light devices connected on specific - endpoints. This allows you to toggle a parameter implemented by the device - to be On or Off. + $ chip-tool onoff on 12344321 1 - `chip-device-ctrl > zcl OnOff On 135246 2 0` +The client will send a single command packet and then exit. diff --git a/examples/lock-app/esp32/README.md b/examples/lock-app/esp32/README.md index 081e98fa914bfa..3eeba161aeadc6 100644 --- a/examples/lock-app/esp32/README.md +++ b/examples/lock-app/esp32/README.md @@ -136,61 +136,67 @@ your network configuration. To erase it, simply run. $ idf.py -p /dev/tty.SLAB_USBtoUART erase_flash -### Setting up Python Controller +## Setting up chip-tool -Once ESP32 is up and running, we need to set up a device controller to perform -commissioning and cluster control. +See [the build guide](../../../docs/guides/BUILDING.md#prerequisites) for +general background on build prerequisites. -- Set up python controller. +Building the example application is quite straightforward. It can either be done +as part of an overall "build everything" build: - $ cd {path-to-connectedhomeip} - $ ./scripts/build_python.sh -m platform +``` +./gn_build.sh +``` -- Execute the controller. +which puts the binary at `out/debug/standalone/chip-tool` - $ source ./out/python_env/bin/activate - $ chip-device-ctrl +#### Commission a device using chip-tool -### Commissioning over BLE +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. -- Establish the secure session over BLE. BLE is the default mode in the - application and is configurable through menuconfig. +#### Commission a device over BLE - - chip-device-ctrl > ble-scan - - chip-device-ctrl > connect -ble 3840 20202021 135246 +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. - Parameters: - 1. Discriminator: 3840 (configurable through menuconfig) - 2. Setup-pin-code: 20202021 (configurable through menuconfig) - 3. Node ID: Optional. - If not passed in this command, then it is auto-generated by the controller and displayed in the output of connect. - The same value should be used in the next commands. - We have chosen a random node ID which is 135246. +The command below uses the default values hard-coded into the debug versions of +the ESP32 all-clusters-app to commission it onto a Wi-Fi network: -- Add credentials of the Wi-Fi network you want the ESP32 to connect to, using - the `AddOrUpdateWiFiNetwork` command and then enable the ESP32 to connect to - it using `EnableWiFiNetwork` command. In this example, we have used - `TESTSSID` and `TESTPASSWD` as the SSID and passphrase respectively. + $ chip-tool pairing ble-wifi ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} 0 20202021 3840 - - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 +or equivalently: - - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 + $ chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 0 20202021 3840 -- Close the BLE connection to ESP32, as it is not required hereafter. +#### Pair a device over IP - - chip-device-ctrl > close-ble +The command below will discover devices with long discriminator 3840 and try to +pair with the first one it discovers using the provided setup code. -- Resolve DNS-SD name and update address of the node in the device controller. + $ chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 - - chip-device-ctrl > resolve 135246 +The command below will discover devices based on the given QR code (which +devices log when they start up) and try to pair with the first one it discovers. + + $ chip-tool pairing qrcode ${NODE_ID_TO_ASSIGN} MT:####### + +### Forget the currently-commissioned device + + $ chip-tool pairing unpair ### Cluster control -- After successful commissioning, use the OnOff cluster command to control the - OnOff attribute. This allows you to toggle a parameter implemented by the - device to be On or Off. +### onoff + +To use the Client to send Matter commands, run the built executable and pass it +the target cluster name, the target command name as well as an endpoint id. + +The endpoint id must be between 1 and 240. + + $ chip-tool onoff on 12344321 1 - `chip-device-ctrl > zcl OnOff Off 135246 1 0` +The client will send a single command packet and then exit. ### Example Demo diff --git a/examples/temperature-measurement-app/esp32/README.md b/examples/temperature-measurement-app/esp32/README.md index b8f1ccad190394..4a0d6f956c58e1 100644 --- a/examples/temperature-measurement-app/esp32/README.md +++ b/examples/temperature-measurement-app/esp32/README.md @@ -136,59 +136,63 @@ your network configuration. To erase it, simply run. $ idf.py -p /dev/tty.SLAB_USBtoUART erase_flash -### Setting up Python Controller +## Setting up chip-tool -Once ESP32 is up and running, we need to set up a device controller to perform -commissioning and cluster control. +See [the build guide](../../../docs/guides/BUILDING.md#prerequisites) for +general background on build prerequisites. -- Set up python controller. +Building the example application is quite straightforward. It can either be done +as part of an overall "build everything" build: - $ cd {path-to-connectedhomeip} - $ ./scripts/build_python.sh -m platform +``` +./gn_build.sh +``` + +which puts the binary at `out/debug/standalone/chip-tool` -- Execute the controller. +#### Commission a device using chip-tool - $ source ./out/python_env/bin/activate - $ chip-device-ctrl +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. -### Commissioning over BLE +#### Commission a device over BLE -- Establish the secure session over BLE. BLE is the default mode in the - application and is configurable through menuconfig. +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. - - chip-device-ctrl > ble-scan - - chip-device-ctrl > connect -ble 3840 20202021 135246 +The command below uses the default values hard-coded into the debug versions of +the ESP32 all-clusters-app to commission it onto a Wi-Fi network: - Parameters: - 1. Discriminator: 3840 (configurable through menuconfig) - 2. Setup-pin-code: 20202021 (configurable through menuconfig) - 3. Node ID: Optional. - If not passed in this command, then it is auto-generated by the controller and displayed in the output of connect. - The same value should be used in the next commands. - We have chosen a random node ID which is 135246. + $ chip-tool pairing ble-wifi ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} 0 20202021 3840 -- Add credentials of the Wi-Fi network you want the ESP32 to connect to, using - the `AddOrUpdateWiFiNetwork` command and then enable the ESP32 to connect to - it using `EnableWiFiNetwork` command. In this example, we have used - `TESTSSID` and `TESTPASSWD` as the SSID and passphrase respectively. +or equivalently: - - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 timeoutMs=1000 + $ chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 0 20202021 3840 - - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 timeoutMs=1000 +#### Pair a device over IP -- Close the BLE connection to ESP32, as it is not required hereafter. +The command below will discover devices with long discriminator 3840 and try to +pair with the first one it discovers using the provided setup code. - - chip-device-ctrl > close-ble + $ chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 -- Resolve DNS-SD name and update address of the node in the device controller. +The command below will discover devices based on the given QR code (which +devices log when they start up) and try to pair with the first one it discovers. - - chip-device-ctrl > resolve 135246 + $ chip-tool pairing qrcode ${NODE_ID_TO_ASSIGN} MT:####### + +### Forget the currently-commissioned device + + $ chip-tool pairing unpair ### Cluster control -- The demo application supports TemperatureMeasurement and Basic cluster. +### temperaturemeasurement - `chip-device-ctrl > zcl Basic MfgSpecificPing 135246 1 0` +```bash +Usage: + ./out/debug/chip-tool temperaturemeasurement read measured-value 12344321 1 +``` ### Flashing app using script