ESP Matter

Matter is the unified IP-based connectivity protocol built on proven technologies, helping connect and build reliable, secure IoT ecosystems. This new technology and royalty-free connectivity standard enables communications among a wide range of smart devices.

ESP Matter is the official Matter development framework for the Espressif's ESP32 series SoCs.

Development Setup

This sections talks about setting up your development host, fetching the git repositories, and instructions to build and flash.

Host Setup

You should install drivers and support packages for your development host. Windows, Linux and Mac OS-X, are supported development hosts. Please see Get Started for the host setup instructions.

Getting the Repositories

This only needs to be done once:

$ git clone --recursive https://github.com/espressif/esp-idf.git
$ cd esp-idf
$ git checkout v4.3
$ git submodule update --init --recursive
$ ./install.sh
$ cd ..

$ git clone --recursive https://glab.espressif.cn/esp-matter-preview/esp-matter.git
$ cd esp-matter/connectedhomeip/connectedhomeip
$ source scripts/bootstrap.sh

Configuring the environment

This needs to be done everytime a new terminal is opened:

$ cd /path/to/esp-idf
$ . export.sh
$ cd /path/to/esp-matter/
$ . export.sh
$ cd examples/light/

$ export ESPPORT=/dev/cu.SLAB_USBtoUART (or /dev/ttyUSB0 or /dev/ttyUSB1 on Linux or COMxx on MinGW)

Building and Flashing the Firmware

Choose IDF target.

idf.py set-target esp32c3 (or esp32 or other supported targets)

• If IDF target has not been set explicitly, then esp32 is considered as default.
• The default device for esp32/esp32c3 is esp32-devkit-c/esp32c3-devkit-m. If you want to use another device, you can export ESP_MATTER_DEVICE_PATH after choosing correct target, e.g for m5stack device:

  $ export ESP_MATTER_DEVICE_PATH=/path/to/esp_matter/device_hal/device/m5stack
  

  • If the device that you have is of a different revision, and is not working as expected, you can create a new device and export your device path.
  • The other peripheral components like led_driver, button_driver, etc are selected based on the device selected.
  • The configuration of the peripheral components can be found in $ESP_MATTER_DEVICE_PATH/esp_matter_device.cmake.

Build and flash:

$ idf.py build
$ idf.py flash monitor

• Note: If you are getting build errors like:

  ERROR: This script was called from a virtual environment, can not create a virtual environment again
  

  Run:

  pip install -r $IDF_PATH/requirements.txt
  

Test Setup (Python Controller Setup)

Environment setup

$ cd esp-matter/connectedhomeip/connectedhomeip
$ ./scripts/build_python.sh -m platform
$ source out/python_env/bin/activate

Commissioning

Execute the controller and establish a secure session over BLE.

$ chip-device-ctrl
chip-device-ctrl > ble-scan
chip-device-ctrl > connect -ble 3840 20202021 12344321

• Discriminator: 3840 (configurable through menuconfig)
• Setup-pin-code: 20202021 (configurable through menuconfig)
• Node ID: Optional. If not passed in this command, then it is auto-generated by the controller and displayed in the output of connect. The same value should be used in the next commands. We have chosen a random node ID which is 12344321.

Add credentials of the Wi-Fi network you want the device to connect to.

chip-device-ctrl > zcl NetworkCommissioning AddWiFiNetwork 12344321 0 0 ssid=str:TESTSSID credentials=str:$TESTPASSWD breadcrumb=0 timeoutMs=1000
chip-device-ctrl > zcl NetworkCommissioning EnableNetwork 12344321 0 0 networkID=str:TESTSSID breadcrumb=0 timeoutMs=1000

Close BLE connection.

chip-device-ctrl > close-ble

Resolve DNS-SD name and update address of the node in the device controller.

chip-device-ctrl > resolve 0 12344321

Cluster Control

Use the cluster commands to control the attributes.

chip-device-ctrl > zcl OnOff On 12344321 1 0
chip-device-ctrl > zcl LevelControl MoveToLevel 12344321 1 0 level=10 transitionTime=0 optionMask=0 optionOverride=0
chip-device-ctrl > zcl LevelControl MoveToLevel 12344321 1 0 level=100 transitionTime=0 optionMask=0 optionOverride=0
chip-device-ctrl > zcl ColorControl MoveToSaturation 12344321 1 0 saturation=200 transitionTime=0 optionsMask=0 optionsOverride=0
chip-device-ctrl > zcl ColorControl MoveToHue 12344321 1 0 hue=150 direction=0 transitionTime=0 optionsMask=0 optionsOverride=0
chip-device-ctrl > zcl OnOff Toggle 12344321 1 0
chip-device-ctrl > quit