ESP32 examples Readme.md update with chip-tool instructions (#13264)

project-chip · Jan 4, 2022 · 440c0b1 · 440c0b1
1 parent fa89fc4
commit 440c0b1
Show file tree

Hide file tree

Showing 4 changed files with 139 additions and 157 deletions.
diff --git 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
@@ -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 <Compressed Fabric ID> 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
@@ -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