Integrated Agent v3.3

The Ayla ESP32 Solution includes example host application source code, an Ayla Integrated Agent, and Ayla extensions to the Espressif IoT Development Framework (ESP-IDF). Together, these components provide an Ayla edge solution for the ESP32, ESP32-C3, or ESP32-S3 module. See Integrated Agent and Edge Connectivity for background.

Who This Guide Is For

This guide is intended for developers who are setting up, building, flashing, and validating the Ayla Integrated Agent on supported ESP32 development kits. By the end of this guide, you should have a working non-Matter demo application connected to Ayla services, with DSN/OEM configuration completed and basic device registration verified.

Guide Overview

This guide walks through the following end-to-end process:

1. Prepare account access and reserve a DSN.
2. Create the Ayla template and import properties.
3. Set up a Ubuntu, Docker, or VM development environment.
4. Install ESP-IDF and the Ayla source code.
5. Build and validate the hello_world example.
6. Build, flash, and monitor the Ayla demo application.
7. Configure DSN, OEM, and Wi-Fi information.
8. Register the device.
9. Optionally configure In-Field Provisioning.
10. Review the host application configuration.

Changes in Ayla ESP32 Solution v3.3 from v3.2

In v3.3, the major changes are as follows:

1. The source package provides two examples: ayla_demo and ayla_matter_demo. ayla_demo demonstrates how to implement a non-Matter device, and ayla_matter_demo demonstrates how to implement a Matter device.
2. An ADM component is provided. It is a helper component that the firmware application uses to support the Matter protocol.
3. The Matter device is built on top of the Ayla Integrated Agent and the CHIP SDK. The CHIP SDK is built on tag v1.3.0.0. Due to some compilation issues, the repository has been forked to https://github.com/Ayla-Professional-Service/csa_matter.git, and a new tag, ada-csa-v1.3.0.0, includes the necessary fixes.
4. The ESP-IDF is upgraded to v5.5.2.
5. In-Field Provisioning is introduced in this version. This feature allows a device to receive and apply its DSN and authentication key pair online, rather than during factory manufacturing. See In-Field Provisioning for details.

Prerequisites

Before you begin, make sure you have the following:

• A supported ESP32 development kit.
• Access to the Ayla Customer Dashboard or the Ayla Developer Portal.
• Access to the Ayla source package (contact Ayla Support if you do not already have it).
• A Ubuntu 22.04 LTS environment, either native, in a VM, or in Docker.
• A USB serial cable and a known serial port on your development machine.
• Your OEM ID, OEM model, and, once reserved, your DSN and key information.
• Basic familiarity with Linux shell commands and the ESP-IDF build system.

Prepare Ayla Account, DSN, and Template

Complete the following steps in order to prepare your Ayla account, reserve a DSN, and create the device template.

1. Obtain an Espressif development kit. Any of the following will work:
   • ESP32-DevKitC
   • ESP32-C3-DevKitM-1
   • ESP32-C3-DevKitC-02
   • ESP32-S3-DevKitC-1
2. Create an Ayla user account. If you do not already have an account, contact the Ayla Support team to request a user account with admin or developer access rights.
3. Reserve a DSN. To reserve a DSN:

   📘

   NOTE:

   If you do not have access to the Ayla Customer Dashboard, request a DSN from your Ayla Solution Engineer or the Ayla Support team.

   • Sign in to the Ayla Customer Dashboard.
   • In the left navigation pane, click Factory Actions.
   • Click the Reserve DSN button.
   • For Model, select AY008ESP1.
   • Click Submit, and then download the associated XML file. You will need the DSN value and key from the downloaded file.
4. Create the device template. Sign in to the Ayla Developer Portal and create a template using the values in the table below. The template version is different from the Ayla ESP32 Solution version. The OEM model describes the application and platform: use demo-esp32 or matter-demo-esp32 for the ESP32-WROOM-32E module, demo-esp32c3 for ESP32-C3 modules, or demo-esp32s3 for ESP32-S3 modules.
   Use the following template values when creating the demo template:

   Field	Value
   Visibility	private
   Name	demo-esp 1.10
   Description	Demo ESP32 1.10
   Registration	AP-Mode
   Model	demo-esp32, matter-demo-esp32, demo-esp32c3, demo-esp32s3, demo-esp32c5, or demo-esp32c6
   Version	demo_esp 1.10
   Type	Wifi
   To learn how to create templates, see the Ayla Developer Portal User Guide.

5. Select the new template and click the Properties tab.
6. Copy and paste the following properties into a text file (for example, properties.csv), and import the file using the Import button:

   base_type,direction,name,scope,mime_type,ack_enabled,host_sw_version,track_only_changes
   boolean,output,Blue_button,user,text/plain,FALSE,FALSE,FALSE
   boolean,input,Blue_LED,user,text/plain,FALSE,FALSE,FALSE
   string,input,cmd,user,text/plain,FALSE,FALSE,FALSE
   decimal,input,decimal_in,user,text/plain,FALSE,FALSE,FALSE
   decimal,output,decimal_out,user,text/plain,FALSE,FALSE,FALSE
   boolean,input,Green_LED,user,text/plain,FALSE,FALSE,FALSE
   integer,input,input,user,null,TRUE,FALSE,FALSE
   string,output,log,user,text/plain,FALSE,FALSE,FALSE
   boolean,input,node_batch_hold,user,null,FALSE,FALSE,FALSE
   integer,output,output,user,text/plain,FALSE,FALSE,FALSE
   string,output,schedule_out,user,text/plain,FALSE,FALSE,FALSE
   file,input,stream_down,user,text/plain,FALSE,FALSE,FALSE
   integer,output,stream_down_len,user,text/plain,FALSE,FALSE,FALSE
   integer,output,stream_down_match_len,user,text/plain,FALSE,FALSE,FALSE
   file,output,stream_up,user,text/plain,FALSE,FALSE,FALSE
   integer,input,stream_up_len,user,text/plain,FALSE,FALSE,FALSE
   string,output,version,user,null,FALSE,TRUE,TRUE

7. Add schedules to the template. The names should be "sched1" through "sched5", and the direction should be to-device.
8. Select the SUNRISE/SUNSET SUPPORTED option for the schedules.
9. Under Available Connects, make sure that the LAN Connect and Auto-sync options are selected. Do not select BLE Connect unless you will use the BLE Local Control feature, as it requires additional memory. Do not select Matter Connect unless you will use the Matter Local Control feature, as it also requires additional memory.

Build and Run

GCC / Ubuntu / Docker

This section provides instructions for building the Ayla ESP32 Solution v3.3 using a GCC, Ubuntu, or Docker development environment. Ubuntu 22.04 LTS is recommended, and it can run natively, in a VM, or in a Docker container.

1. Choose Your Development Environment

Choose one of the following environments:

• Native Ubuntu 22.04 LTS.
• Ubuntu 22.04 LTS in a VM.
• Ubuntu 22.04 LTS in a Docker container.

2. Identify the ESP32 Serial Port

1. List the serial ports on your computer (for example, ls /dev/tty*).
2. Connect an ESP32 board to your computer using a serial cable.
3. List the serial ports again. The new serial port that appears is the one to use (for example, /dev/ttyUSB0).

3. Set Up Your Ubuntu Environment

If you are using native Ubuntu, skip to the next step.

If you are using a VM, use VirtualBox or other VM software to install Ubuntu 22.04 LTS. See Download VirtualBox and Install VirtualBox.

If you are using Docker, install Docker Engine on your Windows, Mac, or Linux host OS, then create a 64-bit Ubuntu container. Pass the ESP32 serial device into the container when you create it, replacing /dev/ttyUSB0 below with the serial port you identified on your host system:

docker run --net=host --name=ada33 -w /root -it --device=/dev/ttyUSB0 ubuntu bash

You are now user root, and the current working directory is /root. To exit the container, type exit. To restart and reattach to the container, run:

docker ps -a
docker start ada33
docker attach ada33

4. Prepare Your Development Environment

Update the package list in your Ubuntu OS:

sudo apt update

Install miscellaneous packages:

sudo apt install nano screen iputils-ping net-tools

5. Install ESP-IDF v5.5.2

1. Install the prerequisites for the Espressif Standard Setup for Toolchain v5.5.2 for Linux:

   sudo apt install bison ccache cmake dfu-util flex git gperf \
     libffi-dev libssl-dev libusb-1.0-0 ninja-build python3 \
     python3-pip python3-venv wget

2. Create an esp directory and change to it:

   cd $HOME
   mkdir esp
   cd esp

3. Clone the Espressif IoT Development Framework:

   git clone -b v5.5.2 --depth 1 --recursive \
     https://github.com/espressif/esp-idf.git esp-idf-v5.5.2

4. Create the IDF_PATH environment variable and persist the change in .bashrc:

   export IDF_PATH=$HOME/esp/esp-idf-v5.5.2
   echo "export IDF_PATH=\$HOME/esp/esp-idf-v5.5.2" >> ~/.bashrc

5. Set up the Espressif tools:

   cd $IDF_PATH
   export IDF_GITHUB_ASSETS="dl.espressif.com/github_assets"
   ./install.sh

6. Set Up the Matter SDK (Optional)

The previous steps are sufficient to develop a non-Matter device. Complete the following steps only if you plan to develop a Matter device. The CHIP repositories provide an installation guide here.

1. Install the prerequisites for CHIP:

   sudo apt install g++ gcc git libavahi-client-dev libcairo2-dev \
     libdbus-1-dev libgirepository1.0-dev libglib2.0-dev libreadline-dev \
     libssl-dev ninja-build pkg-config python3-dev python3-pip \
     python3-venv unzip

2. Create a chip directory and change to it:

   cd $HOME
   mkdir chip
   cd chip

3. Clone the Matter SDK:

   git clone -b ada-csa-v1.3.0.0 --depth 1 \
     https://github.com/Ayla-Professional-Service/csa_matter.git matter
   cd matter
   ./scripts/checkout_submodules.py --shallow --platform esp32

4. Create the CHIP_PATH environment variable and persist the change in .bashrc:

   export CHIP_PATH=$HOME/chip/matter
   echo "export CHIP_PATH=\$HOME/chip/matter" >> ~/.bashrc

5. Set up the CHIP environment:

   echo 'cython<3' > /tmp/constraints.txt
   PIP_CONSTRAINT=/tmp/constraints.txt bash ./scripts/activate.sh

Note: This step may fail due to network issues. Retry it until it succeeds.

6. Install the Python libraries required by the ESP-IDF Python environment for the Matter device:

   source $IDF_PATH/export.sh
   pip install stringcase==1.2.0 lark==1.1.2

7. Open a Shell Terminal to Build the Firmware App

Open a new terminal, load the ESP-IDF (or Matter) environment, and then build the firmware from the selected example directory.

To build a non-Matter firmware, load only the ESP-IDF environment:

source $IDF_PATH/export.sh

To build a Matter firmware, load both environments in this order:

source $CHIP_PATH/scripts/activate.sh
source $IDF_PATH/export.sh

8. Test the Development Environment with the "hello_world" Example

1. Open a new terminal to compile the non-Matter device, and change directory:

   cd $IDF_PATH/examples/get-started/hello_world

2. Set the target to match your devkit (esp32, esp32c3, or esp32s3), then customize the configuration. The defaults should be fine:

   idf.py set-target esp32
   idf.py menuconfig

3. Build, flash, and monitor:

   idf.py build
   idf.py flash
   idf.py monitor

The output appears similar to the following example:

   Toolchain path: /root/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc
   Toolchain version: crosstool-ng-1.22.0-80-g6c4433a
   Compiler version: 5.2.0
   ...
   Hello world!
   This is ESP32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
   Restarting in 10 seconds...
   Restarting in 9 seconds...
   ...

Press Ctrl + ] to exit the monitor.

9. Test the CHIP Environment with the all-clusters-app Example (Matter Only)

1. Open a new terminal to compile the Matter device, and change directory:

   cd $CHIP_PATH/examples/all-clusters-app/esp32

2. Set up the compile environment:

   idf.py set-target esp32
   idf.py menuconfig

3. Build, flash, and monitor:

   idf.py build
   idf.py flash
   idf.py monitor

10. Install the Ayla Source Code

Download the Ayla source code (ada-esp-idf-src-3.3.tgz). ada stands for Ayla Device Agent.

1. If you are using Docker, copy the archive from a host terminal into your Docker container:

   docker cp /home/matt/Downloads/ada-esp-idf-src-3.3.tgz ada33:/root/esp

2. In your Docker (or Ubuntu) terminal, extract the archive:

   cd $HOME/esp
   tar zxvf ada-esp-idf-src-3.3.tgz

3. Copy the ada-esp-idf-src-3.3 directory on top of the esp-idf-v5.5.2 directory:

   cp -R ada-esp-idf-src-3.3/* esp-idf-v5.5.2

11. Build the Ayla Host Application

Build the Ayla demo host application (non-Matter):

1. Open a new terminal to compile the non-Matter device, and change directory:

   cd $IDF_PATH/examples/ayla_demo

2. Set the target, then build, flash, and monitor. Set the target to esp32, esp32c3, esp32s3, esp32c5, or esp32c6, as appropriate for your devkit:

   idf.py set-target esp32
   idf.py build
   idf.py erase_flash
   idf.py flash
   idf.py monitor

Build the Ayla matter demo host application (Matter only):

1. Open a new terminal to compile the Matter device, and change directory:

   cd $IDF_PATH/examples/ayla_matter_demo

2. Set the target, then build, flash, and monitor:

   idf.py set-target esp32
   idf.py build
   idf.py erase_flash    # only needed the first time
   idf.py flash
   idf.py monitor

Flash Firmware Error Troubleshooting

You may encounter the following error when flashing firmware to the device:

esptool.py v4.7.0
Serial port /dev/ttyUSB0
Connecting.....
Chip is ESP32-D0WD (revision v1.0)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: ac:67:b2:71:94:50
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Changed.
Configuring flash size...
 
A fatal error occurred: bootloader/bootloader.bin requires chip revision in
range [v3.0 - v3.99] (this chip is revision v1.0). Use --force to flash anyway.

This error indicates that the firmware was built for a minimum ESP32 chip revision that does not match the connected board. Confirm the target device, ESP-IDF configuration, and minimum chip revision settings before flashing again. Do not use --force unless you have confirmed the firmware is compatible with the connected hardware.

The table below summarizes common issues encountered in this section:

12. Configure DSN and OEM Info

1. Confirm your OEM ID and OEM model. These values are assigned by Ayla and used throughout this section.
2. Request the required DNS CNAME entry from Ayla. The Ayla agent uses the OEM model and OEM ID to build the DNS CNAME and connects to the appropriate Ayla MQTT server. The DNS CNAME entry will look similar to <oem-model>-<OEM-ID>-mqtt.aylanetworks.com, using the OEM model from the template and your assigned OEM ID. Request the DNS entry through your support contact or by emailing the Ayla Support team.
3. Configure the DSN and authentication key. These commands are required for both non-Matter and Matter devices:

   conf set id/dev_id AC000W000000001
   conf set id/key MIIB... (long number)
   reset    # allow the device to reread the configuration

4. Configure the OEM ID, OEM model, and OEM key:

   oem 000000000                                            # replace with your Ayla OEM ID
   oem model demo-esp32                                     # replace with the OEM model from the template
   oem key 0123456789abcdef0123456789abcdef demo-esp32       # replace with your OEM secret
                                                              # and the OEM model from the template

5. Configure the Wi-Fi profile:

   wifi profile ap ssid Ayla-DevKit

Configure Matter Parameters (Matter Only)

The Ayla Matter demo has embedded default Matter parameter configuration, so it does not need the commands below. Your own product needs to configure this information.

The Certification Declaration (CD) is embedded in the firmware binary and is issued by the CSA after the device passes Matter certification. Replace the default CD in demo_matter.c with your own.

1. Configure the PAI and DAC certificates and key:

   matter set pai-cert "Your product PAI certificate"
   matter set dac-cert "Your product DAC certificate"
   matter set dac-priv-key "Your product DAC certificate private key"

2. Configure the spake parameters, either with separate commands:

   matter set discriminator 1234
   matter set spake-iter-cnt 1000
   matter set spake-salt "spake-salt in base64"
   matter set spake-verifier "spake-verifier in base64"

Or by using the qrgen sub-command, which automatically generates the spake parameters and pairing QR code parameters based on the configured DSN and OEM model:

   matter qrgen

Note: The matter qrgen command generates a QR code.

3. Disable setup mode:

   setup_mode disable

4. Display the QR code (Matter only):

   matter qrshow

Note: The matter qrshow command generates the QR code. Use a browser to access the QR code URL to view it. The discriminator and passcode are used by chip-tool to set up the device.

   vendor:         65521 (0xfff1)
   product:        32769 (0x8001)
   discovery mask: 0x02
   discriminator:  1234
   passcode:       20202021
   pairing code:   10054912339
   QR payload:     MT:-24J0KQS02-10648G00
   QR code URL:    https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A-24J0KQS02-10648G00

5. Confirm the device connection behavior. Use the Aura Mobile App to add your device: the Aura Mobile App, running on Android or iOS, communicates with your ESP32 device over Bluetooth to add the device to your local network and register it to your Ayla user account. See Using BLE to Set Up Wi-Fi for ESP32 or Using Matter to Set Up Wi-Fi for ESP32. If you do not want to use the Aura App, you can use chip-tool instead (Matter only).

Use chip-tool for Matter Wi-Fi Setup (Matter Only)

1. Build the chip-tool program:

   cd $HOME/matter/examples/chip-tool
   source $HOME/matter/scripts/activate.sh
   gn gen out/debug
   ninja -C out/debug

2. Use chip-tool to set up your Matter device:

   ./out/debug/chip-tool pairing ble-wifi <node-id> <ssid> <password> <passcode> <discriminator>

Note: The passcode and discriminator are displayed in the matter qrshow command result.

Example, setting up the Ayla Matter demo:

   ./out/debug/chip-tool pairing ble-wifi 1 TEST 12345678 20202021 1234

Note: For your own device, you will need to set the PAA trust store path, for example:

   ./out/debug/chip-tool pairing ble-wifi 1 TEST 12345678 53725857 3549 \
     --paa-trust-store-path /var/paa-root-certs/

13. Register Your Device

Provide the DSN, OEM model, and Ayla account information to Ayla Support or your Solution Engineer so the device can be registered to the correct account and template.

In-Field Provisioning

In-Field Provisioning (IFP) allows a device to receive or apply its DSN and authentication credentials outside the factory provisioning flow. Instead of requiring all device credentials to be assigned during manufacturing, an OEM provisioning key is used to authorize the device hardware identity and associate it with the correct Ayla OEM and model information. This approach can simplify manufacturing workflows and support provisioning later in the device lifecycle.

To use In-Field Provisioning, complete the following steps:

Step 1: Get an OEM Provisioning Key Pair

Each OEM must create at least one provisioning key pair. In production environments, consider creating separate provisioning keys for each contract manufacturer or production line so that individual keys can be revoked without affecting other manufacturing partners.

Create a working directory for the provisioning key files:

mkdir ifp
cd ifp

Create the key pair using the following commands:

openssl genpkey -out private_key.pem -outform PEM -algorithm RSA
openssl rsa -in private_key.pem -out public_key.pem -pubout

Step 2: Upload the Key

Using public_key.pem created in the previous step, create a JSON file containing the fields oem and public_key, with the newlines in the public key escaped as \n. For example, save the following script as create_keyfile.py:

#! /usr/bin/env python3
# coding: utf-8
import json
 
oem_id = '0dfc7900'  # replace with your OEM ID
key_in = 'public_key.pem'
obj_out = 'keyfile.json'
 
with open(key_in, 'r') as fp:
    lines = fp.read()
 
obj = {'public_key': lines, 'oem': oem_id}
out = json.dumps(obj, separators=(',', ':'))
 
with open(obj_out, 'w') as fp:
    fp.write(out)

The resulting keyfile.json will be about 494 bytes and will look like this (shown here on multiple lines for readability, but written as a single line):

{"public_key":"-----BEGIN PUBLIC KEY-----\nMIIBI...\nAB\n-----END PUBLIC KEY-----\n","oem":"0dfc7900"}

To upload the key, you will need to authenticate as an OEM admin user. Authenticate as an OEM admin user and save the returned authorization token. The token is used in the AUTH variable in the upload request:

curl -v -X POST -H "Content-Type: application/json" \
  -d '{"user":{"application":{"app_secret":"<app-secret>","app_id":"<app-id>"},"password":"<password>","email":"<email>"}}' \
  'https://<user-service-host>/users/sign_in.json'

The authentication string returned is used in this example:

AUTH="AUTHORIZATION: auth_token <your-hex-auth-token-string>"
ADS=ads-dev.aylanetworks.com
 
curl -i -X POST -H "$AUTH" -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    --data-binary @keyfile.json https://$ADS/apiv1/provisions

The response will be a provisioning key ID similar to this:

{"provision":{"provision_key":"<base64>"}}

Note the key ID and retain it for use in signing and configuring the modules.

Step 3: Sign the Hardware ID in Manufacturing Scripts

Until manufacturing scripts support hardware ID signing directly, use the following example script to generate an OEM signature for a hardware ID. Production manufacturing flows should integrate equivalent logic into the approved factory tooling. Save the following as signing.sh:

#! /bin/bash
 
if [ $# -lt 4 ]
then
    echo "usage: $0 <oem_id> <keyid> <private-key> <hwid>" >&2
    exit 1
fi
 
OEM_ID=$1
KEY_ID=$2
KEY_FILE=$3
HW_ID=$4
 
random_string=`openssl rand -base64 6`
 
string_to_sign="$OEM_ID $HW_ID $KEY_ID $random_string"
 
echo oem_signature:
echo -n $string_to_sign | \
    openssl rsautl -sign -inkey $KEY_FILE | \
    base64 -w 0
echo

./signing.sh 0dfc7900 your-key-id private_key.pem mac-123456789abc
oem_signature:
NPgDlS9lQM...AOZ2bQ==

The oem_signature will be a string 344 bytes long. This value and the key ID can be pasted into the host application's command line in setup mode as follows.

Step 4: Apply the Signature in Setup Mode

In setup mode, apply the generated OEM signature and provisioning key ID, then configure the OEM model and Wi-Fi profile before restarting the device:

conf set id/oem/key NPgDlS9lQM...AOZ2bQ==
conf set id/oem/key/id your-key-id
oem model your-model-name
setup_mode disable
reset
wifi profile 0 ssid wifi-name key wifi-password join

Host Application

The host application configures the ESP-IDF build and provides the runtime logic required for the Ayla demo application. Use this section to confirm that the required subsystems, watchdog behavior, and demo application settings are enabled before building production-derived firmware. For detailed information about the demo application, see the Example Application page.

Host Application Configuration

The host application is responsible for configuring the ESP-IDF build to include the proper subsystems with the correct settings. An example configuration is provided with the demo host application.

For proper operation of the client health check code, the task watchdog reset feature should be enabled. It should be configured to panic if not reset within 25 seconds. You can test this with the "crash hang" command found in the demo code.