Below guide mentions the details about how to build, flash, monitor, commission the esp32 application.
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.
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
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.
Below apps can be used for commissioning the application running on ESP32:
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.
$ out/debug/chip-tool pairing ble-wifi 12345 MY_SSID MY_PASSWORD 20202021 3840
For ESP32-H2, firstly start OpenThread Border Router, you can either use Raspberry Pi OpenThread Border Router OR ESP32 OpenThread Border Router
Get the active operational dataset.
$ ot-ctl> dataset active -x
Commissioning the Thread device
$ ./out/debug/chip-tool pairing ble-thread 12345 hex:<operational-dataset> 20202021 3840
$ 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
If you want to use different values for discriminator and setup pin code please follow Using ESP32 Factory Data Provider guide
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