From d47baf5384b1215257606976c79afc19023c7276 Mon Sep 17 00:00:00 2001 From: Sweety Date: Thu, 21 Oct 2021 01:50:28 +0530 Subject: [PATCH] ESP32: Add README for bridge app (#10495) --- examples/bridge-app/esp32/README.md | 254 ++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 examples/bridge-app/esp32/README.md diff --git a/examples/bridge-app/esp32/README.md b/examples/bridge-app/esp32/README.md new file mode 100644 index 00000000000000..add83d3346f770 --- /dev/null +++ b/examples/bridge-app/esp32/README.md @@ -0,0 +1,254 @@ +# CHIP ESP32 Bridge App Example + +A prototype application that demonstrates dynamic endpoint with device +commissioning and cluster control. It adds the non-chip device as endpoints on a +bridge(Matter device). In this example four light devices supporting on-off +cluster have been added as endpoints + +1. Light1 at endpoint 2 +2. Light2 at endpoint 6 +3. Light3 at endpoint 4 +4. Light4 at endpoint 5 + +--- + +- [CHIP ESP32 Bridge App Example](#chip-esp32-bridge-app-example) + - [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) + - [Commissioning over BLE](#commissioning-over-ble) + - [Cluster control](#cluster-control) + +--- + +## Dynamic Endpoints + +The Bridge Example makes use of Dynamic Endpoints. Current SDK support is +limited for dynamic endpoints, since endpoints are typically defined (along with +the clusters and attributes they contain) in a .zap file which then generates +code and static structures to define the endpoints. + +To support endpoints that are not statically defined, the ZCL attribute storage +mechanisms will hold additional endpoint information for `NUM_DYNAMIC_ENDPOINTS` +additional endpoints. These additional endpoint structures must be defined by +the application and can change at runtime. + +To facilitate the creation of these endpoint structures, several macros are +defined: + +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName)` +`DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask)` +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(clusterRevision)` + +- These three macros are used to declare a list of attributes for use within a + cluster. The declaration must begin with the + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN` macro which will define the name of + the allocated attribute structure. Each attribute is then added by the + `DECLARE_DYNAMIC_ATTRIBUTE` macro. Finally, + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_END` macro should be used to close the + definition. + +- All attributes defined with these macros will be configured as + `ATTRIBUTE_MASK_EXTERNAL_STORAGE` in the ZCL database and therefore will + rely on the application to maintain storage for the attribute. Consequently, + reads or writes to these attributes must be handled within the application + by the `emberAfExternalAttributeWriteCallback` and + `emberAfExternalAttributeReadCallback` functions. See the bridge + application's `main.cpp` for an example of this implementation. + +`DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName)` +`DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs)` +`DECLARE_DYNAMIC_CLUSTER_LIST_END` + +- These three macros are used to declare a list of clusters for use within a + endpoint. The declaration must begin with the + `DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN` macro which will define the name of the + allocated cluster structure. Each cluster is then added by the + `DECLARE_DYNAMIC_CLUSTER` macro referencing attribute list previously + defined by the `DECLARE_DYNAMIC_ATTRIBUTE...` macros. Finally, + `DECLARE_DYNAMIC_CLUSTER_LIST_END` macro should be used to close the + definition. + +`DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)` + +- This macro is used to declare an endpoint and its associated cluster list, + which must be previously defined by the `DECLARE_DYNAMIC_CLUSTER...` macros. + +## Building the Example Application + +Building the example application requires the use of the Espressif ESP32 IoT +Development Framework and the xtensa-esp32-elf toolchain. + +The VSCode devcontainer has these components pre-installed, so you can skip this +step. To install these components manually, follow these steps: + +- Clone the Espressif ESP-IDF and checkout + [v4.3 tag](https://github.com/espressif/esp-idf/releases/v4.3) + + $ mkdir ${HOME}/tools + $ cd ${HOME}/tools + $ git clone https://github.com/espressif/esp-idf.git + $ cd esp-idf + $ git checkout v4.3 + $ git submodule update --init + $ ./install.sh + +- Install ninja-build + + $ sudo apt-get install ninja-build + +Currently building in VSCode _and_ deploying from native is not supported, so +make sure the IDF_PATH has been exported(See the manual setup steps above). + +- Setting up the environment + + $ cd ${HOME}/tools/esp-idf + $ ./install.sh + $ . ./export.sh + $ cd {path-to-connectedhomeip} + + To download and install packages. + + $ source ./scripts/bootstrap.sh + $ source ./scripts/activate.sh + + If packages are already installed then simply activate them. + + $ source ./scripts/activate.sh + +- Configuration Options + + This application uses `ESP32-DevKitC` as a default device type. To use other + ESP32 based device types, please refer + [examples/all-clusters-app/esp32](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/esp32) + +- To build the demo application. + + $ idf.py build + +- After building the application, to flash it outside of VSCode, connect your + device via USB. Then run the following command to flash the demo application + onto the device and then monitor its output. If necessary, replace + `/dev/tty.SLAB_USBtoUART`(MacOS) with the correct USB device name for your + system(like `/dev/ttyUSB0` on Linux). Note that sometimes you might have to + press and hold the `boot` button on the device while it's trying to connect + before flashing. For ESP32-DevKitC devices this is labeled in the + [functional description diagram](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html#functional-description). + + $ idf.py -p /dev/tty.SLAB_USBtoUART flash monitor + + Note: Some users might have to install the + [VCP driver](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) + before the device shows up on `/dev/tty`. + +- Quit the monitor by hitting `Ctrl+]`. + + Note: You can see a menu of various monitor commands by hitting + `Ctrl+t Ctrl+h` while the monitor is running. + +- If desired, the monitor can be run again like so: + + $ idf.py -p /dev/tty.SLAB_USBtoUART monitor + +## Commissioning and cluster control + +Commissioning can be carried out using WiFi, BLE or Bypass. + +1. Set the `Rendezvous Mode` for commissioning using menuconfig; the default + Rendezvous mode is BLE. + + $ idf.py menuconfig + +Select the Rendezvous Mode via `Demo -> Rendezvous Mode`. If Rendezvous Mode is +Bypass then set the credentials of the WiFi Network (i.e. SSID and Password from +menuconfig). + +`idf.py menuconfig -> Component config -> CHIP Device Layer -> WiFi Station Options` + +2. Now flash the device with the same command as before. (Use the right `/dev` + device) + + $ idf.py -p /dev/tty.SLAB_USBtoUART flash monitor + +3. The device should boot up. When device connects to your network, you will + see a log like this on the device console. + + I (5524) chip[DL]: SYSTEM_EVENT_STA_GOT_IP + I (5524) chip[DL]: IPv4 address changed on WiFi station interface: ... + +4. Use + [python based device controller](https://github.com/project-chip/connectedhomeip/tree/master/src/controller/python) + or + [standalone chip-tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool) + or + [iOS chip-tool app](https://github.com/project-chip/connectedhomeip/tree/master/src/darwin/CHIPTool) + or + [Android chip-tool app](https://github.com/project-chip/connectedhomeip/tree/master/src/android/CHIPTool) + to communicate with the device. + +Note: The ESP32 does not support 5GHz networks. Also, the Device will persist +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. + + $ cd {path-to-connectedhomeip} + $ ./scripts/build_python.sh -m platform + +- Execute the controller. + + $ source ./out/python_env/bin/activate + $ chip-device-ctrl + +### Commissioning over BLE + +- Establish the secure session over BLE. BLE is the default mode in the + application and is configurable through menuconfig. + + - chip-device-ctrl > ble-scan + - chip-device-ctrl > connect -ble 3840 20202021 135246 + + 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. + +- Add credentials of the Wi-Fi network you want the ESP32 to connect to, using + the `AddWiFiNetwork` 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-device-ctrl > zcl NetworkCommissioning AddWiFiNetwork 135246 0 0 ssid=str:TESTSSID credentials=str:TESTPASSWD breadcrumb=0 timeoutMs=1000 + + - chip-device-ctrl > zcl NetworkCommissioning EnableNetwork 135246 0 0 networkID=str:TESTSSID breadcrumb=0 timeoutMs=1000 + +- Close the BLE connection to ESP32, as it is not required hereafter. + + - chip-device-ctrl > close-ble + +- 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. + + - chip-device-ctrl > get-fabricid + + - chip-device-ctrl > resolve 135246 + +### Cluster Control + +- 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-device-ctrl > zcl OnOff On 135246 2 0`