From 0f6a52ac9cc43d2d1de3b9cb1f099a90d291edc9 Mon Sep 17 00:00:00 2001 From: Rohit Jadhav <69809379+jadhavrohit924@users.noreply.github.com> Date: Wed, 5 Jan 2022 00:00:32 +0530 Subject: [PATCH] ESP32 examples Readme.md update with chip-tool instructions (#13264) --- examples/all-clusters-app/esp32/README.md | 81 +++++++++---------- examples/bridge-app/esp32/README.md | 75 ++++++++--------- examples/lock-app/esp32/README.md | 72 ++++++++--------- .../esp32/README.md | 68 ++++++++-------- 4 files changed, 139 insertions(+), 157 deletions(-) diff --git a/examples/all-clusters-app/esp32/README.md b/examples/all-clusters-app/esp32/README.md index f63bb3ab9d1443..73cac3d7c1cf07 100644 --- a/examples/all-clusters-app/esp32/README.md +++ b/examples/all-clusters-app/esp32/README.md @@ -9,7 +9,7 @@ control. - [Supported Devices](#supported-devices) - [Building the Example Application](#building-the-example-application) - [Commissioning and cluster control](#commissioning-and-cluster-control) - - [Setting up Python Controller](#setting-up-python-controller) + - [Setting up chip-tool](#setting-up-chip-tool) - [Commissioning over BLE](#commissioning-over-ble) - [Cluster control](#cluster-control) - [Flashing app using script](#flashing-app-using-script) @@ -160,73 +160,66 @@ 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. -Once ESP32 is up and running, we need to set up a device controller to perform -commissioning and cluster control. +### Setting up chip-tool -- Set up python controller. +See [the build guide](../../../docs/guides/BUILDING.md#prerequisites) for +general background on build prerequisites. - $ cd {path-to-connectedhomeip} - $ ./scripts/build_python.sh -m platform +Building the example: -- Execute the controller. +``` +$ cd examples/chip-tool - $ source ./out/python_env/bin/activate - $ chip-device-ctrl +$ rm -rf out -### Commissioning over BLE +$ gn gen out/debug -- Establish the secure session over BLE. BLE is the default mode in the - application and is configurable through menuconfig. +$ ninja -C out/debug +``` - - chip-device-ctrl > ble-scan - - chip-device-ctrl > connect -ble 3840 20202021 135246 +which puts the binary at `out/debug/chip-tool` - 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. +### Commission a device using chip-tool -- 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. +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. - - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 +#### Commissioning over BLE - - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. -- Close the BLE connection to ESP32, as it is not required hereafter. +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: - - chip-device-ctrl > close-ble + $ .out/debug/chip-tool pairing ble-wifi 12344321 ${SSID} ${PASSWORD} 20202021 3840 -- Resolve DNS-SD name and update address of the node in the device controller. +Parameters: - - chip-device-ctrl > resolve 135246 +1. Discriminator: 3840 (configurable through menuconfig) +2. Setup-pin-code: 20202021 (configurable through menuconfig) +3. Node-id: 12344321 (you can assign any node id) ### 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. + $ .out/debug/chip-tool onoff on 12344321 1 - `chip-device-ctrl > zcl LevelControl MoveToLevel 135246 1 1 level=10 transitionTime=0 optionMask=0 optionOverride=0` +The client will send a single command packet and then exit. -- 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. +#### levelcontrol - `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` +```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..96e1a60f3ffb98 100644 --- a/examples/bridge-app/esp32/README.md +++ b/examples/bridge-app/esp32/README.md @@ -16,7 +16,7 @@ cluster have been added as endpoints - [Dynamic Endpoints](#dynamic-endpoints) - [Building the Example Application](#building-the-example-application) - [Commissioning and cluster control](#commissioning-and-cluster-control) - - [Setting up Python Controller](#setting-up-python-controller) + - [Setting up chip-tool](#setting-up-chip-tool) - [Commissioning over BLE](#commissioning-over-ble) - [Cluster control](#cluster-control) @@ -192,63 +192,56 @@ 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. -Once ESP32 is up and running, we need to set up a device controller to perform -commissioning and cluster control. +### Setting up chip-tool -- Set up python controller. +See [the build guide](../../../docs/guides/BUILDING.md#prerequisites) for +general background on build prerequisites. - $ cd {path-to-connectedhomeip} - $ ./scripts/build_python.sh -m platform +Building the example: -- Execute the controller. +``` +$ cd examples/chip-tool - $ source ./out/python_env/bin/activate - $ chip-device-ctrl +$ rm -rf out -### Commissioning over BLE +$ gn gen out/debug -- Establish the secure session over BLE. BLE is the default mode in the - application and is configurable through menuconfig. +$ ninja -C out/debug +``` - - chip-device-ctrl > ble-scan - - chip-device-ctrl > connect -ble 3840 20202021 135246 +which puts the binary at `out/debug/chip-tool` - 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. +### Commission a device using chip-tool -- 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. +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. - - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 +#### Commissioning over BLE - - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. -- Close the BLE connection to ESP32, as it is not required hereafter. +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: - - chip-device-ctrl > close-ble + $ .out/debug/chip-tool pairing ble-wifi 12344321 ${SSID} ${PASSWORD} 20202021 3840 -- 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. +Parameters: - - chip-device-ctrl > get-fabricid +1. Discriminator: 3840 (configurable through menuconfig) +2. Setup-pin-code: 20202021 (configurable through menuconfig) +3. Node-id: 12344321 (you can assign any node id) - - chip-device-ctrl > resolve 135246 +### Cluster control -### Cluster Control +#### onoff -- 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. +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. - `chip-device-ctrl > zcl OnOff On 135246 2 0` + $ .out/debug/chip-tool onoff on 12344321 1 + +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..fa9aab5abcff86 100644 --- a/examples/lock-app/esp32/README.md +++ b/examples/lock-app/esp32/README.md @@ -7,7 +7,7 @@ This example demonstrates the mapping of OnOff cluster to lock/unlock logic. - [CHIP ESP32 Lock Example](#chip-esp32-lock-example) - [Building the Example Application](#building-the-example-application) - [Commissioning and cluster control](#commissioning-and-cluster-control) - - [Setting up Python Controller](#setting-up-python-controller) + - [Setting up chip-tool](#setting-up-chip-tool) - [Commissioning over BLE](#commissioning-over-ble) - [Cluster control](#cluster-control) - [Example Demo](#example-demo) @@ -136,63 +136,61 @@ 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. -Once ESP32 is up and running, we need to set up a device controller to perform -commissioning and cluster control. +### Setting up chip-tool -- Set up python controller. +See [the build guide](../../../docs/guides/BUILDING.md#prerequisites) for +general background on build prerequisites. - $ cd {path-to-connectedhomeip} - $ ./scripts/build_python.sh -m platform +Building the example: -- Execute the controller. +``` +$ cd examples/chip-tool - $ source ./out/python_env/bin/activate - $ chip-device-ctrl +$ rm -rf out -### Commissioning over BLE +$ gn gen out/debug -- Establish the secure session over BLE. BLE is the default mode in the - application and is configurable through menuconfig. +$ ninja -C out/debug +``` - - chip-device-ctrl > ble-scan - - chip-device-ctrl > connect -ble 3840 20202021 135246 +which puts the binary at `out/debug/chip-tool` - 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. +### Commission a device using chip-tool -- 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. +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. - - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 +#### Commissioning over BLE - - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. -- Close the BLE connection to ESP32, as it is not required hereafter. +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: - - chip-device-ctrl > close-ble + $ .out/debug/chip-tool pairing ble-wifi 12344321 ${SSID} ${PASSWORD} 20202021 3840 -- Resolve DNS-SD name and update address of the node in the device controller. +Parameters: - - chip-device-ctrl > resolve 135246 +1. Discriminator: 3840 (configurable through menuconfig) +2. Setup-pin-code: 20202021 (configurable through menuconfig) +3. Node-id: 12344321 (you can assign any node id) ### 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 - `chip-device-ctrl > zcl OnOff Off 135246 1 0` +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. -### Example Demo + $ .out/debug/chip-tool onoff on 12344321 1 + +The client will send a single command packet and then exit. + +## Example Demo This demo app illustrates controlling OnOff cluster (Server) attributes of an endpoint and lock/unlock status of door using LED's. For `ESP32-DevKitC`, a GPIO diff --git a/examples/temperature-measurement-app/esp32/README.md b/examples/temperature-measurement-app/esp32/README.md index b8f1ccad190394..63834903af093e 100644 --- a/examples/temperature-measurement-app/esp32/README.md +++ b/examples/temperature-measurement-app/esp32/README.md @@ -7,7 +7,7 @@ This example is meant to represent a minimal-sized application. - [CHIP ESP32 Temperature Sensor Example](#chip-esp32-temperature-sensor-example) - [Building the Example Application](#building-the-example-application) - [Commissioning and cluster control](#commissioning-and-cluster-control) - - [Setting up Python Controller](#setting-up-python-controller) + - [Setting up chip-tool](#setting-up-chip-tool) - [Commissioning over BLE](#commissioning-over-ble) - [Cluster control](#cluster-control) - [Flashing app using script](#flashing-app-using-script) @@ -136,61 +136,59 @@ 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. -Once ESP32 is up and running, we need to set up a device controller to perform -commissioning and cluster control. +### Setting up chip-tool -- Set up python controller. +See [the build guide](../../../docs/guides/BUILDING.md#prerequisites) for +general background on build prerequisites. - $ cd {path-to-connectedhomeip} - $ ./scripts/build_python.sh -m platform +Building the example: -- Execute the controller. +``` +$ cd examples/chip-tool - $ source ./out/python_env/bin/activate - $ chip-device-ctrl +$ rm -rf out -### Commissioning over BLE +$ gn gen out/debug -- Establish the secure session over BLE. BLE is the default mode in the - application and is configurable through menuconfig. +$ ninja -C out/debug +``` - - chip-device-ctrl > ble-scan - - chip-device-ctrl > connect -ble 3840 20202021 135246 +which puts the binary at `out/debug/chip-tool` - 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. +### Commission a device using chip-tool -- 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. +To initiate a client commissioning request to a device, run the built executable +and choose the pairing mode. - - chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 timeoutMs=1000 +#### Commissioning over BLE - - chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 timeoutMs=1000 +Run the built executable and pass it the discriminator and pairing code of the +remote device, as well as the network credentials to use. -- Close the BLE connection to ESP32, as it is not required hereafter. +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: - - chip-device-ctrl > close-ble + $ .out/debug/chip-tool pairing ble-wifi 12344321 ${SSID} ${PASSWORD} 20202021 3840 -- Resolve DNS-SD name and update address of the node in the device controller. +Parameters: - - chip-device-ctrl > resolve 135246 +1. Discriminator: 3840 (configurable through menuconfig) +2. Setup-pin-code: 20202021 (configurable through menuconfig) +3. Node-id: 12344321 (you can assign any node id) ### 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 +## Flashing app using script - Follow these steps to use `${app_name}.flash.py`.