examples/pigweed-app/esp32/README.md

   1 # CHIP ESP32 Pigweed Example Application
   2
   3 The ESP32 example demonstrates the usage of Pigweed module functionalities in an
   4 application.
   5
   6 The example is based on [CHIP](https://github.com/project-chip/connectedhomeip),
   7 the [Pigweed](https://pigweed.googlesource.com/pigweed/pigweed) module, which is
   8 a collection of libraries that provide different functionalities for embedded
   9 systems, and the ESP32 platform.
  10
  11 You can use this example as a training ground for making experiments, testing
  12 Pigweed module features and checking what actions are necessary to fully
  13 integrate Pigweed in a CHIP project.
  14
  15 Pigweed functionalities are being gradually integrated into CHIP. Currently, the
  16 following features are available:
  17
  18 -   **Echo RPC** - Creates a Remote Procedure Call server and allows sending
  19     commands through the serial port to the device, which makes echo and sends
  20     the received commands back.
  21
  22 ---
  23
  24 -   [CHIP ESP32 Pigweed Example Application](#chip-esp32-pigweed-example-application)
  25     -   [Building the Example Application](#building-the-example-application)
  26         -   [To build the application, follow these steps:](#to-build-the-application-follow-these-steps)
  27     -   [Testing the Example Application](#testing-the-example-application)
  28
  29 ---
  30
  31 ## Building the Example Application
  32
  33 Building the example application requires the use of the Espressif ESP32 IoT
  34 Development Framework and the xtensa-esp32-elf toolchain.
  35
  36 The VSCode devcontainer has these components pre-installed, so you can skip this
  37 step. To install these components manually, follow these steps:
  38
  39 -   Clone the Espressif ESP-IDF and checkout release/v4.2 branch
  40
  41           $ mkdir ${HOME}/tools
  42           $ cd ${HOME}/tools
  43           $ git clone https://github.com/espressif/esp-idf.git
  44           $ cd esp-idf
  45           $ git checkout release/v4.2
  46           $ git submodule update --init
  47           $ export IDF_PATH=${HOME}/tools/esp-idf
  48           $ ./install.sh
  49
  50 -   Install ninja-build
  51
  52           $ sudo apt-get install ninja-build
  53
  54 ### To build the application, follow these steps:
  55
  56 Currently building in VSCode _and_ deploying from native is not supported, so
  57 make sure the IDF_PATH has been exported(See the manual setup steps above).
  58
  59 -   In the root of the example directory, sync the CHIP tree's submodules and
  60     source `idf.sh`. Note: This does not have to be repeated for incremental
  61     builds.
  62
  63           $ source idf.sh
  64
  65 -   Configuration Options
  66
  67         To choose from the different configuration options, run menuconfig
  68
  69           $ idf make menuconfig
  70
  71         This example uses UART0 for serial communication. You can change this through
  72         `PW RPC Example Configuration`. As a result, the console has been shifted to UART1
  73         You can change this through `Component config` -> `Common ESP-related` ->
  74         `UART for console output`
  75
  76         To use the default configuration options, run the default config
  77
  78           $ idf make defconfig
  79
  80 -   Run make to build the demo application.
  81
  82           $ idf make
  83
  84 -   After building the application, to flash it outside of VSCode, connect your
  85     device via USB. Then run the following command to flash the demo application
  86     onto the device and then monitor its output. If necessary, replace
  87     `/dev/tty.SLAB_USBtoUART`(MacOS) with the correct USB device name for your
  88     system(like `/dev/ttyUSB0` on Linux). Note that sometimes you might have to
  89     press and hold the `boot` button on the device while it's trying to connect
  90     before flashing. For ESP32-DevKitC devices this is labeled in the
  91     [functional description diagram](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html#functional-description).
  92
  93           $ idf make flash ESPPORT=/dev/tty.SLAB_USBtoUART
  94
  95     Note: Some users might have to install the
  96     [VCP driver](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
  97     before the device shows up on `/dev/tty`.
  98
  99 ## Testing the Example Application
 100
 101 Run the following command to start an interactive Python shell, where the Echo
 102 RPC commands can be invoked:
 103
 104         python -m pw_hdlc.rpc_console --device /dev/tty.SLAB_USBtoUART -b 115200 $CHIP_ROOT/third_party/pigweed/repo/pw_rpc/pw_rpc_protos/echo.proto -o /tmp/pw_rpc.out
 105
 106 To send an Echo RPC message, type the following command, where the actual
 107 message is the text in quotation marks after the `msg=` phrase:
 108
 109         rpcs.pw.rpc.EchoService.Echo(msg="hi")