Step 1: Build the Sample App

In this step, you build the Matter sample app and download it to an Espressif development kit. This smart-light sample app enables the mandatory Matter clusters for a smart light that supports color, including the On/Off, Level Control, and Color Control clusters.

The tutorial uses Vendor IDs assigned by the CSA for testing: 0xFFF1, 0xFFF2, 0xFFF3, 0xFFF4. The example commands use 0xFFF1. To build production products, you need a Vendor ID assigned by the Connectivity Standards Alliance (CSA).

Tutorial:
Build an ACK-enabled Matter Device
→
Step 1:
Build the Sample App
→
Step 2:
Provision the Device
→
Step 3:
Test the Device

Prerequisites

Before you start the tutorial, set up your development environment. Make sure that you download the Espressif package in Step 1: Download required packages.

Steps to build the sample app

Complete the following steps to build the sample app.

  1. Set up your app environment.
  2. Build the smart-light app.
  3. Flash the image.

Step 1.1: Set up your app environment

After you set up your development environment, configure and activate your app environment to build with Matter. The smart-light sample app installs to the Cyprus-SDK/smartlight-mtr-app directory.

To set up the app environment

  1. In an Ubuntu VM terminal window, navigate to the top-level Cyprus-SDK directory.
  2. To install packages required for the sample app, at the command prompt, enter the following commands.

Copied to clipboard.

source ./setup.sh
  1. Repeat steps 1–2 each time you open a new terminal instance.

Step 1.2: Build the smart-light app

Next, you build the smart-light app. The full build uses the test values for the build parameters. For more details, see Define build parameters.

To build the smart-light app

  1. In a new terminal window, at the command prompt, enter the following command.

Copied to clipboard.

source ./setup.sh
  1. Navigate to the Cyprus-SDK/smartlight-mtr-app directory.
  2. To start the build, at the command prompt, enter the following command.

Copied to clipboard.

idf.py build
  1. To verify successful command completion, confirm that you see the following output.

    Project build complete. To flash, run this command: /home/user/.espressif/python_env/idf4.3_py3.10_env/bin/python ../esp-dpk/external/esp-idf/components/esptool_py/esptool/esptool.py -p (PORT) -b 460800 --before default_reset --after no_reset --chip esp32c3 --no-stub write_flash --flash_mode dio --flash_size keep --flash_freq 80m 0xc000 build/partition_table/partition-table.bin 0xd000 build/ota_data_initial.bin 0xf000 ../esp-dpk/external/esp-idf/components/esp_wifi/esp32c3/phy_multiple_init_data.bin 0x10000 build/smartlight-mtr-app.bin or run 'idf.py -p (PORT) flash'

  2. Note the location of the binary files produced by the build. You flash these files to the development kit.
    The build places the following binary files in the build directory:
    • Cyprus-SDK/smartlight-mtr-app/build/partition_table/partition-table.bin
    • Cyprus-SDK/smartlight-mtr-app/build/ota_data_initial.bin
    • Cyprus-SDK/smartlight-mtr-app/build/smartlight-mtr-app.bin
    • Cyprus-SDK/smartlight-mtr-app/build/bootloader/bootloader.bin
  3. In a convenient place, such as Notepad on Windows or TextEdit on Mac, paste the binary files directory paths.

Step 1.3: Flash the image to the development kit

In this step, you write the app binary data to flash memory on the Espressif development kit. You can use one of the following Espressif tools to write to flash memory:

  • esptool.py – Read, write, and erase binary files to and from flash memory on the Espressif development kit. If your source and binary files are on separate platforms, use this tool. For more details, see Basic Commands: Write Binary Data to Flash.
  • idf.py – Build the software and copy the resulting binary files to flash. If your source and binary files are on the same system, use this option to debug and test the app.

The following steps use the idf.py tool.

To write the smart light image to the development kit

  1. In a new terminal window, at the command prompt, enter the following command.

Copied to clipboard.

source ./setup.sh
  1. Connect your Ubuntu VM or host machine to the development kit.
    For details, see Connect your host machine to the development kit.
  2. Navigate to the Cyprus-SDK/smartlight-mtr-app directory.
  3. To erase data from flash memory, at the command prompt, enter the following command.
    Set <port> to the serial port, such as /dev/ttyUSB0 on Ubuntu, /dev/tty.usbserial-USB0 on Mac or COM9 on Windows.

Copied to clipboard.

    idf.py -p <port> erase_flash
  1. To flash the binary images to the development kit, at the command prompt, enter the following command.
    You can specify the parameters in Cyprus-SDK/customer_profiles/smartlight-mtr-app /ack_build_config/build_config.cmake instead of the command line.
    Set <port> to the serial port.

Copied to clipboard.

    idf.py \
    -p <port> \
    -DAPPLICATION_VERSION_STRING='1.0.0' \
    -DBUILD_VERSION=0 \
    -DPACKAGE_NAME='com.amazon.ack.cyprus.esp32_c3f.0x010C.os' \
    -DPRODUCT_NAME='ACK' \
    -DVENDOR_NAME='ACK' \
    -DHARDWARE_VERSION=0 \
    -DHARDWARE_VERSION_STRING='hardware-version-0' \
    flash
Was this page helpful?

Last updated: frontmatter-missing