ESP32 examples Readme.md update with chip-tool instructions

project-chip · Dec 29, 2021 · 2564e0d · 2564e0d
1 parent 83b2f46
commit 2564e0d
Show file tree

Hide file tree

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