ESP32 Application Usage Guide

Below guide mentions the details about how to build, flash, monitor, commission the esp32 application.

Supported target chips

All the Matter demo application is intended to work on: the ESP32-DevKitC, the ESP32-WROVER-KIT_V4.1, the M5Stack, the ESP32C3-DevKitM, ESP32-Ethernet-Kit and the ESP32S3.

All the applications support variants of ESP32, ESP32C3, ESP32S3 chips.

ESP32H2 is only supported and tested with lighting-app.

Note: M5Stack Core 2 display is not supported in the tft component, while other functionality can still work fine.

Building an example application

Set up the environment variables

  • ESP-IDF

    Tools path SHALL be added to the PATH environment variable to make the tools usable from the command line. ESP-IDF provides another script which does that.

    $ cd path/to/esp-idf
$ source export.sh

  • Matter

    Before running any other build command, the scripts/activate.sh environment setup script should be sourced at the top level. This script set up a Python environment with libraries used to build and test.

    $ cd path/to/connectedhomeip
$ source scripts/activate.sh

  • Ccache

    Enable Ccache for faster IDF builds. It is recommended to have Ccache installed for faster builds.

    $ export IDF_CCACHE_ENABLE=1

Build, flash and monitor an example

  • Change to example application directory

    $ cd examples/<app-name>/esp32

  • Set the Matter target to build

    $ idf.py set-target (Matter)

    All the example applications supports target chips: esp32, esp32s3, esp32c3

    ESP32H2 is only supported in lighting-app, to set it as target

    idf.py --preview set-target esp32h2

  • Configuration Options

    To build the default configuration (sdkconfig.defaults) skip this step.

    To build a specific configuration (example m5stack):

    $ rm sdkconfig
$ idf.py -D 'SDKCONFIG_DEFAULTS=sdkconfig_m5stack.defaults' build

    Note: If using a specific device configuration, it is highly recommended to start off with one of the defaults and customize on top of that. Certain configurations have different constraints that are customized within the device specific configuration (eg: main app stack size).

    To customize the configuration, run menuconfig:

    $ idf.py menuconfig

  • Build the application

    idf.py build

  • Flash the application

    After building the application, to flash it connect your device via USB. Then run the following command to erase the whole flash, flash the demo application onto the device and then monitor its output.

    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

    $ idf.py -p (PORT) erase_flash
$ idf.py -p (PORT) flash monitor

    Please replace (PORT) with the correct USB device name for your system (like /dev/ttyUSB0 on Linux or /dev/tty.usbserial-101 on Mac).

    Note: Some users might have to install the VCP driver before the device shows up on /dev/tty.

  • Quit the monitor by pressing Ctrl+]. Note: You can see a menu of various monitor commands by hitting Ctrl+t Ctrl+h while the monitor is running.

Commissioning

Below apps can be used for commissioning the application running on ESP32:

Building Standalone chip-tool

cd path/to/connectedhomeip
scripts/examples/gn_build_example.sh examples/chip-tool out/debug

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 the WiFi devices (ESP32, ESP32C3, ESP32S3)

$ out/debug/chip-tool pairing ble-wifi 12345 MY_SSID MY_PASSWORD 20202021 3840

Commissioning the Thread device (ESP32H2)

Commissioning the Ethernet device (ESP32-Ethernet-Kit)

$ out/debug/chip-tool pairing ethernet 12345 20202021 3840 device-remote-ip 5540

Note: In order to commission an ethernet device, from all-clusters-app enable these config options: select ESP32-Ethernet-Kit under Demo->Device Type and select On-Network rendezvous mode under Demo->Rendezvous Mode

Commissioning Parameters

  • Node Id : 12345 (you can assign any node id)
  • Discriminator : 3840 (Test discriminator)
  • Setup Pin Code : 20202021 (Test setup pin code)

If you want to use different values for discriminator and setup pin code please follow Using ESP32 Factory Data Provider guide

Flashing app using script

  • Follow these steps to use ${app_name}.flash.py.

    • First set IDF target, run set-target with one of the commands.

      $ idf.py set-target esp32
$ idf.py set-target esp32c3

    • Execute below sequence of commands

      $ export ESPPORT=/dev/tty.SLAB_USBtoUART
$ idf.py build
$ idf.py flashing_script
$ python ${app_name}.flash.py