examples/persistent-storage/esp32/README.md

   1 # CHIP ESP32 Persistent Storage Example
   2
   3 An example testing and demonstrating the key value storage API.
   4
   5 <hr>
   6
   7 -   [CHIP ESP32 Persistent Storage Example](#chip-esp32-persistent-storage-example)
   8     -   [Introduction](#introduction)
   9     -   [ESP32](#esp32)
  10         -   [Building](#building)
  11         -   [Flashing the Application](#flashing-the-application)
  12         -   [Viewing Logging Output](#viewing-logging-output)
  13
  14 <hr>
  15
  16 <a name="introduction"></a>
  17
  18 ## Introduction
  19
  20 This example serves to both test the key value storage implementation and API as
  21 it is brought-up on different platforms, as well as provide an example for how
  22 to use the API.
  23
  24 In the future this example can be moved into a unit test when available on all
  25 platforms.
  26
  27 <a name="ESP32"></a>
  28
  29 ## ESP32
  30
  31 The ESP32 platform KVS is not yet fully implemented. In particular offset and
  32 partial reads are not yet supported.
  33
  34 <a name="building"></a>
  35
  36 ### Building
  37
  38 Building the example application requires the use of the Espressif ESP32 IoT
  39 Development Framework and the xtensa-esp32-elf toolchain.
  40
  41 The VSCode devcontainer has these components pre-installed, so you can skip this
  42 step. To install these components manually, follow these steps:
  43
  44 -   Clone the Espressif ESP-IDF and checkout release/v4.2 branch
  45
  46           $ mkdir ${HOME}/tools
  47           $ cd ${HOME}/tools
  48           $ git clone https://github.com/espressif/esp-idf.git
  49           $ cd esp-idf
  50           $ git checkout release/v4.2
  51           $ git submodule update --init
  52           $ export IDF_PATH=${HOME}/tools/esp-idf
  53           $ ./install.sh
  54
  55 -   Install ninja-build
  56
  57           $ sudo apt-get install ninja-build
  58
  59 Currently building in VSCode _and_ deploying from native is not supported, so
  60 make sure the IDF_PATH has been exported(See the manual setup steps above).
  61
  62 -   Setting up the environment
  63
  64 To download and install packages.
  65
  66         $ cd ${HOME}/tools/esp-idf
  67         $ ./install.sh
  68         $ . ./export.sh
  69         $ cd {path-to-connectedhomeip}
  70         $ source ./scripts/bootstrap.sh
  71         $ source ./scripts/activate.sh
  72         $ cd {path-to-connectedhomeip-examples}
  73
  74 If packages are already installed then simply activate it.
  75
  76         $ cd ${HOME}/tools/esp-idf
  77         $ ./install.sh
  78         $ . ./export.sh
  79         $ cd {path-to-connectedhomeip}
  80         $ source ./scripts/activate.sh
  81         $ cd {path-to-connectedhomeip-examples}
  82
  83 -   Configuration Options
  84
  85         To choose from the different configuration options, run menuconfig
  86
  87           $ idf.py menuconfig
  88
  89 -   To build the demo application.
  90
  91           $ idf.py build
  92
  93 <a name="flashing"></a>
  94
  95 ### Flashing the Application
  96
  97 -   After building the application, to flash it outside of VSCode, connect your
  98     device via USB. Then run the following command to flash the demo application
  99     onto the device and then monitor its output. If necessary, replace
 100     `/dev/tty.SLAB_USBtoUART`(MacOS) with the correct USB device name for your
 101     system(like `/dev/ttyUSB0` on Linux). Note that sometimes you might have to
 102     press and hold the `boot` button on the device while it's trying to connect
 103     before flashing. For ESP32-DevKitC devices this is labeled in the
 104     [functional description diagram](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html#functional-description).
 105
 106           $ idf.py flash monitor ESPPORT=/dev/tty.SLAB_USBtoUART
 107
 108     Note: Some users might have to install the
 109     [VCP driver](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
 110     before the device shows up on `/dev/tty`.
 111
 112 <a name="view-logging"></a>
 113
 114 ### Viewing Logging Output
 115
 116 The output of the test will be streamed out of the UART and can be observed with
 117 whichever tool is typically used for monitoring this (eg, minicom on linux).