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 and ESP32C6 are only supported and tested with lighting-app, lit-icd-app, and all-clusters-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

    Activate the Matter environment. Below command needs to be executed after sourcing esp-idf/export.sh.

    $ 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 (target chip)

  • Configuration Options

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

    To build a specific configuration (example m5stack or esp32h2 or esp32c6):

    $ 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, ESP32C6)#

$ 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 onnetwork 12345 20202021

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. Currently default ethernet board supported is IP101, if you want to use other types of ethernet board then you can extend the ESPEthernetDriver class in your application and override the current implementation under ESPEthernetDriver::Init

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
$ idf.py set-target esp32c6

    • Execute below sequence of commands

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