Build Apps for ACK-based Matter Devices

Follow these steps to build a device app that connects to Alexa and other Matter-enabled smart assistants.

The Alexa Connect Kit (ACK) SDK for Matter includes the following components:

• Smart-light sample app, found in the Cyprus-SDK/smartlight-mtr-app directory.
• Middleware components, found in the Cyprus-SDK/ace directory.
• Matter SDK, found in the Cyprus-SDK/ace/sdk/external/matter/repo directory. You can find the Matter version in Cyprus-SDK/ReleaseNotes.txt.

You can start with the smart-light app included with the SDK and modify it, or you can use your own app. If you want to get started with a tutorial, see Tutorial: Build an ACK-based Matter Device.

Prerequisites

Before you start, set up your development environment.

To build a device app with the ACK SDK for Matter, make sure you have the following items:

• A development kit for ACK SDK for Matter.
• Matter attributes: Vendor ID (VID), Product ID (PID), Vendor Name, Product Name, Device Type ID.
  For prototypes, you can use CSA-reserved test IDs for VID and PID. For production, use CSA-issued values. For Device Type IDs for your device, see Matter Device Library Specification.

Steps to build the device app

Complete the following steps to build the device app.

1. Set up your app environment.
2. Select Matter clusters for your device.
3. Define build parameters.
4. Build the device app.
5. Flash the image.

Step 1: Set up your app environment

After you set up your development environment, configure and activate your app environment to build with Matter.

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.

source ./setup.sh

3. Repeat steps 1–2 each time you open a new terminal instance.

Step 2: Select Matter clusters for your device

To customize the Matter clusters, attributes, and commands, use the ZAP tool, a user interface developed by the Connectivity Standards Alliance. ZAP uses JSON templates, called zap files, to define endpoints, clusters, attributes, and commands. You can start with the zap file included with ACK SDK for Matter, Cyprus-SDK/smartlight-mtr-app/smartlight-mtr-app.zap, or you can use any of the Matter examples on GitHub, such as all-clusters-app.zap. After you make updates, you can generate source code to integrate into your device app.

For more details, see Zap repo on GitHub.

To select Matter clusters for your device app

1. Open zap, and then open your zap file.
   For example, to update the clusters for the smart-light app, open the Cyprus-SDK/smartlight-mtr-app/smartlight-mtr-app.zap file.
2. To enable and disable cluster information, select the desired endpoint.
3. To enable a cluster, select Client, Server or Client & Server.
4. To disable a cluster, select Not Enabled.
5. To configure attributes and commands for a cluster, select the gear icon .
6. After you complete the updates, save the changes to a new or existing .zap file.
7. To generate source code to integrate into your app, choose Generate.

8. Select a directory to store the generated code.
   For example, for the smart-light app, select the Cyprus-SDK/smartlight-mtr-app/zap-generated directory.

   Tip: ZAP overwrites previously generated source code. To avoid losing previous versions, save the generated source code in a new directory.
9. Add the generated source code to your device app.
10. Update the Cyprus-SDK/smartlight-mtr-app/main/CMakeLists.txt file to include the new clusters.

Step 3: Define build parameters

You can specify build parameter values on the command-line interface when you build your app. Or, you can define the parameter values in a cmake file. You can find the entire set of build-time parameters and their descriptions in the Cyprus-SDK/customer_profiles/smartlight-mtr-app/ack_build_config/build_config.cmake file. Copy the file to your project directory, and then update the values as appropriate for your app.

The configuration file contains the following parameters and default values.

Step 4: Build the device app

In this step, you build the device app. You can run a clean build or build updates only. The build script detects changes that you made after the last successful build. If there are instances where your change doesn't build, perform a clean build.

Complete the following steps to build your app.

To build the app

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

source ./setup.sh

2. Navigate to the top-level directory for your device app.
   For the sample app, the directory is Cyprus-SDK/smartlight-mtr-app.
3. (Optional) To run a clean build, remove the build directory, or at the command prompt, enter the following command.

idf.py fullclean

3. To build your app, at the command prompt, enter the following command.
   You can include the build parameters on the command line, or let the build tool use the values in the cmake file. For more details, see Step 3: Define build parameters.

idf.py \
-DAPPLICATION_VERSION_STRING=<major.minor.patch> \
-DBUILD_VERSION=<version_number> \
-DPACKAGE_NAME='com.amazon.ack.cyprus.esp32_c3f.<device type id>.os' \
-DPRODUCT_NAME=<product name> \
-DVENDOR_NAME=<vendor name>
-DHARDWARE_VERSION=<hardware version> \
-DHARDWARE_VERSION_STRING=<hardware version string> \
build

4. To verify successful command completion, confirm that you see the following output.
   Note: You flash the image in Step 5: Flash the image.

   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/<app-nam>.bin or run 'idf.py -p (PORT) flash'

5. Note the location of the binary files produced by the build. You flash these files to the development kit.
   The build places the binary files in the build directory.
6. In a convenient place, such as Notepad on Windows or TextEdit on Mac, paste the binary files and their directory paths.

Step 5: Flash the image

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.

Flash from a development machine

If your Ubuntu VM, or Window or Mac host machine is directly connected to the serial port on the development kit, use the following instructions to copy your app image to the development kit.

To write the image to the development kit

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

source ./setup.sh

2. Connect your Ubuntu VM or host machine to the development kit.
   For details, see Connect your host machine to the development kit.
3. Navigate to your app source directory.
4. If your development environment is available on your VM or host machine, you can use the idf.py tool to build and flash the images to the development kit.
   At the command prompt, enter the following command.
   Set <port> to your serial port, such as /dev/ttyUSB0 on Ubuntu, /dev/tty.usbserial-USB0 on Mac or COM9 on Windows.

idf.py \
-p <port> \
-DAPPLICATION_VERSION_STRING=<major.minor.patch> \
-DBUILD_VERSION=<version_number> \
-DPACKAGE_NAME='com.amazon.ack.cyprus.esp32_c3f.<device type id>.os' \
-DPRODUCT_NAME=<product name> \
-DVENDOR_NAME=<vendor name>
-DHARDWARE_VERSION=<hardware version> \
-DHARDWARE_VERSION_STRING=<hardware version string> \
flash

5. Or, if your binary images are already built, you can use the esptool.py to flash the images to the development kit from your host machine.
   At the command prompt, enter the following command.
   • You can find Espressif tool in Cyprus-SDK/esp-dpk/external/esp-idf/components/esptool_py/esptool/esptool.py.
   • Include the binary files you saved from Step 4: Build the device app.
   • You can find the phy_multiple_init_data.bin file in Cyprus-SDK/esp-dpk/external/esp-idf/components/esp_wifi/esp32c3/phy_multiple_init_data.bin.
   • Set <port> to your serial port, such as /dev/ttyUSB0 on Ubuntu, /dev/tty.usbserial-USB0 on Mac or COM9 on Windows.
   Tip: If there is only one development kit connected to the host machine, the -p <port> option isn't required.

python3 <path to esptool.py> --chip esp32c3 \
-p <port> \
-b 921600 \
--before=default_reset \
--after=hard_reset write_flash \
--flash_mode dio \
--flash_freq 80m \
--flash_size 4MB \
0x0000 <path to bootloader .bin file> \
0xC000 <path to partition-table .bin file> \
0xD000 <path to ota_data_initial .bin file> \
0xF000 <path to phy_multiple_init_data .bin file> \
0x10000 <path to image .bin file>

Erase flash memory

To reset the development kit to a blank state, you can erase flash memory. The command removes all data from the development kit, including provisioning information and stored certificates.

The following steps use the idf.py tool. You can also erase flash memory with the esptool.py For more details, see Basic Commands: Erase Flash.

To erase flash memory from the development kit

1. Connect your Ubuntu VM or host machine to the development kit. For details, see Connect your host machine to the development kit.
2. In a terminal window, navigate to your app source directory.
3. At the command prompt, enter the following command.
   Set <port> to your serial port, such as /dev/ttyUSB0 on Ubuntu, /dev/tty.usbserial-USB0 on Mac or COM9 on Windows.
   Tip: If there is only one development kit connected to the host machine, the -p <port> option isn't required.

idf.py -p <port> erase_flash

Enable logs

Verbose logs are usually hidden by default on a device. To turn on system logs after a factory reset or flash erase, Connect your host machine to the development kit or ACK module, and then enter the following command on the device.

mack log system enable

To dump logs, enter the following command on the device.

mack log dump system/partner

Related topics

• Building Matter
• Espressif esptool.py Reference
• Provision ACK-based Matter Prototype Devices
• Commission ACK-based Matter Devices
• Certify ACK-based Matter Devices
• Manufacture ACK-based Matter Devices

Last updated: frontmatter-missing