Guides

Integrated Agent V3.3

The Ayla ESP32 solution includes example host application source code, an Ayla Wi-Fi Integrated Agent, and Ayla extensions to the Espressif Development Framework (ESP-IDF). These pieces link together to provide an Ayla edge solution for an ESP32, ESP32-C3 or ESP32-S3 module. See Integrated Agent and Edge Connectivity.

Changes in ADA-3.3 from ADA-3.2

In ADA-3.3, the major changes are as follows:

  1. It provides two examples in the source package, ayla_demo and ayla_matter_demo. ayla_demo demonstrates how to implement a non-Matter device. ayla_matter_demo demonstrates how to implement a Matter device.
  2. ADM component is provided. It is a helper component for the firmware app to support the Matter protocol.
  3. Matter device is constructed on top of ADA and the CHIP SDK. The CHIP SDK is based on the tag v1.3.0.0. Because there are some compiling issues, the repository is forked to https://github.com/Ayla-Professional-Service/csa_matter.git and a new tag ada-csa-v1.3.0.0 has the fixes.
  4. The ESP-IDF is upgraded to v5.5.2.
  5. A new feature is introduced in this version in field provision that can apply the DSN and authentication key pairs online rather than in the factory.

First Steps

  1. Obtain an Espressif dev kit. Any of the following would work:

  2. Create an Ayla user account.
    If you do not have an account already, please contact Ayla Support team to get user account with admin or developer access rights.

  3. Reserve a DSN.
    To reserve a DSN, follow these steps:

    1. Sign in to the Ayla Customer Dashboard.
    2. On the left navigation pane, click Factory Actions.
    3. Click the Reserve DSN button.
    4. For Model, select AY008ESP1.
    5. Click Submit and then download the associated XML file. You will need the DSN value and key from the downloaded file.
      📘

      NOTE:

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

  4. Create a template.
    Sign in to the Ayla Developer Portal and create a template with the details provided in the following table. Note that the template version is different from the ADA version.
    The OEM model describes the application and platform, it could be demo-esp32 or matter-demo-esp32 for the ESP32-WROOM-32E module, demo-esp32c3 for the ESP32-C3 modules, and demo-esp32s3 for the ESP32-S3 modules.

    FieldValue
    Visibilityprivate
    Namedemo-esp 1.10
    DescriptionDemo ESP32 1.10
    RegistrationAP-Mode
    Modeldemo-esp32 or matter-demo-esp32 or demo-esp32c3 or demo-esp32s3 or demo-esp32c5 or demo-esp32c6
    Versiondemo_esp 1.10
    TypeWifi

    To learn how to create templates, please refer to 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 (e.g. 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 be using the BLE Local Control feature, as it requires additional memory.
    • Do not select Matter Connect unless you will be using the Matter Local Control feature, as it requires additional memory.

Build and Run

GCC/Ubuntu/Docker

This section provides directions for building an Ayla ESP32 Solution v3.1 using a GCC/Ubuntu/Docker development environment. The recommendation is to use Ubuntu version 22.04 LTS. Running Ubuntu natively or in a VM is supported.

1. Install Ubuntu 22.04 LTS OS in VM

(Skip this step If you use native Ubuntu)

  1. Use Docker to install an Ubuntu 22.04 LTS container.

    1. Determine the computer-to-ESP32 serial port.

      1. List the serial ports on your computer (e.g. 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 on the list is the one to use (e.g. /dev/ttyUSB0).

    2. Install a Docker Engine on your Windows, Mac, or Linux host OS.

      1. Create a Docker 64-bit Ubuntu container.

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

        You are user root, and the current working directory is /root. To exit your Docker container, type exit. To restart and re-attach to your Docker container, type the following:

        docker ps -a
docker start ada33
docker attach ada33

  2. Use VirtualBox or other VM software to install an Ubuntu 22.04 LTS OS.

2. Prepare your development environment

  1. Update the package list in your Ubuntu OS:

    sudo apt update

  2. Install miscellaneous packages:

    sudo apt install nano screen iputils-ping net-tools

  3. Install the ESP-IDF environment.

    1. Install prerequisites for 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
    1. Create an esp directory and change directory:
    cd $HOME
mkdir esp
cd esp
    1. 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
    1. 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
    1. Set up the Espressif tools using the following instructions:
    cd $IDF_PATH
export IDF_GITHUB_ASSETS="dl.espressif.com/github_assets"
./install.sh

  4. Set up Matter SDK.
    The previous steps are ready to develop a non-Matter device. The following steps are only needed to develop a Matter device. CHIP repositories provide an installation guide here.

    1. Install 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
    1. Create a chip directory and change directory:
    cd $HOME
mkdir chip
cd chip
    1. 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
    1. 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
    1. Set up the CHIP environment using the following instructions.
      It may fail due to network issues, please retry until it is successful:
    echo 'cython<3' > /tmp/constraints.txt
PIP_CONSTRAINT=/tmp/constraints.txt bash ./scripts/activate.sh
    1. Some Python libraries need to be installed into the ESP-IDF Python environment for the Matter device:
    source $IDF_PATH/export.sh
pip install stringcase==1.2.0 lark==1.1.2

3. Open a Shell Terminal to Build the Firmware App

To compile a firmware, open a new terminal and export the Matter or IDF environment variable.

  1. Compile a Non-Matter firmware:

    source $IDF_PATH/export.sh

  2. Compile a Matter firmware, the export sequence is important:

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

4. Test the Development Environment with "hello_world" Example

  1. Open a new terminal to compile non-Matter device.

  2. Change directory:

    cd $IDF_PATH/examples/get-started/hello_world

  3. Customize configuration (Defaults should be fine).
    Set target to either esp32, esp32c3, or esp32s3, depending on your devkit:

    idf.py set-target esp32
idf.py menuconfig

  4. 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 `Ctl` + `]` to exit the monitor.

5. Test the CHIP Environment with all-clusters-app Example

  1. Open a new terminal to compile Matter device.

  2. Change directory:

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

  3. Set up compile environment:

    idf.py set-target esp32
idf.py menuconfig

  4. Build, flash, and monitor:

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

6. Install Ayla Source Code

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

    📘

    NOTE:

    If you do not have access to Ayla source code, please request access to Ayla Connection from Ayla Support team.

  2. Copy the Ayla code into your Ubuntu OS.

    1. Copy ada-esp-idf-src-3.3.tgz to your Docker container
      1. In a host terminal, copy ada-esp-idf-src-3.3.tgz to your Docker container. 
        docker cp /home/matt/Downloads/ada-esp-idf-src-3.3.tgz ada33:/root/esp
      2. In your Docker terminal, extract the archive file 
        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

7. Build the Ayla Host Application

  1. Build the Ayla demo host application (Skip this step if you want to support Matter)

    a. Open a new terminal to compile non-Matter device.

    1. Change directory:
    cd $IDF_PATH/examples/ayla_demo
    1. Build, flash, and monitor:
    idf.py set-target esp32 # or esp32c3 or esp32s3 or esp32c5 or esp32c6 as appropriate
idf.py build
idf.py erase_flash
idf.py flash
idf.py monitor

  2. Build the Ayla matter demo host application:

    1. Open a new terminal to compile Matter device.
    2. Change directory:
    cd $IDF_PATH/examples/ayla_matter_demo
    1. Build, flash, and monitor:
    idf.py set-target esp32
idf.py build
idf.py erase_flash # only needed first time
idf.py flash
idf.py monitor

  3. You may encounter the following error when flashing firmware to a 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.
CMake Error at run_serial_tool.cmake:66 (message):
 
  /home/yzl/.espressif/python_env/idf5.2_py3.10_env/bin/python;;/home/yzl/esp/esp-idf-v5.2.1/components/esptool_py/esptool/esptool.py;--chip;esp32
  failed.
 
 
 
FAILED: CMakeFiles/flash /home/yzl/esp/esp-idf-v5.2.1/examples/ayla_matter_demo/build/CMakeFiles/flash
cd /home/yzl/esp/esp-idf-v5.2.1/components/esptool_py && /usr/bin/cmake -D IDF_PATH=/home/yzl/esp/esp-idf-v5.2.1 -D "SERIAL_TOOL=/home/yzl/.espressif/python_env/idf5.2_py3.10_env/bin/python;;/home/yzl/esp/esp-idf-v5.2.1/components/esptool_py/esptool/esptool.py;--chip;esp32" -D "SERIAL_TOOL_ARGS=--before=default_reset;--after=hard_reset;write_flash;@flash_args" -D WORKING_DIRECTORY=/home/yzl/esp/esp-idf-v5.2.1/examples/ayla_matter_demo/build -P /home/yzl/esp/esp-idf-v5.2.1/components/esptool_py/run_serial_tool.cmake
ninja: build stopped: subcommand failed.
ninja failed with exit code 1, output of the command is in the /home/yzl/esp/esp-idf-v5.2.1/examples/ayla_matter_demo/build/log/idf_py_stderr_output_15527 and /home/yzl/esp/esp-idf-v5.2.1/examples/ayla_matter_demo/build/log/idf_py_stdout_output_15527
📘

Error Solution

You need to change the chip version to be between v3.0 and v3.99.

8. Configure DSN and OEM Info

  1. Request a DNS CNAME entry from Ayla.
    Ayla agent uses OEM-model and OEM ID to make the DNS CNAME, and connects with the appropriate Ayla MQTT server. The DNS CNAME entry will be like <oem-model>-<OEM-ID>-mqtt.aylanetworks.com , replace <oem model> with the OEM model from the template, and <OEM ID> with your assigned OEM ID. The DNS entry can be requested through your support contact or by e-mail to Ayla Support team.

  2. Provision the device DSN and OEM credentials.
    Configure the device DSN and the same OEM model used in the template. The commands are required by both non-Matter device and Matter device:

    conf set id/dev_id AC000W000000001
conf set id/key MIIB... (long number)
reset (to allow device to reread config)
oem 000000000 (replace with your Ayla OEM ID)
oem model demo-esp32 (replace with OEM model from template)
oem key 0123456789abcdef0123456789abcdef demo-esp32 (replace with your OEM secret and the OEM model from the template)
wifi profile ap ssid Ayla-DevKit

  3. Configure Matter parameter (Only for Matter device):
    Ayla matter demo has embedded default matter parameter configuration — it doesn't need the below configure commands. Your product needs to configure the below info.

    1. The Certification Declaration (CD) is embedded in the firmware binary. It is issued by CSA after the device passes the Matter certification. Please replace the default CD in the file demo_matter.c.
    2. 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"
    3. Configure spake parameters:

      1. By using 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"

      2. By using the qrgen sub-command, it will automatically generate the unique spake parameters and the pairing QR code parameters based on the configured DSN and OEM model for the device:

        matter qrgen
      📘

      NOTE:

      The matter qrgen command generates QR code.

  4. Disable setup mode:

    setup_mode disable

  5. Display QR code (Only for Matter device)

    📘

    NOTE:

    The matter qrgen command generates QR Code. Use a browser to access the QR code URL to get the QR Code. The discriminator and passcode are used for chip-tool to set up the device.

    matter qrshow

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

  6. Use Aura Mobile App to add your device.
    The Aura Mobile App running on Android or iOS communicates with your ESP32 device (via Bluetooth) to add the device to your local network, and then register the device to your Ayla user account. For instructions, see Using BLE to set up Wi-Fi for ESP32 or Using Matter to set up Wi-Fi for ESP32. If you don't want to use Aura App, you could use chip-tool to setup Matter device — see the next step.

  7. Use chip-tool to do Matter Wi-Fi setup (Only for Matter device):

    1. Build chip-tool programme first: 
      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 setup 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.
      Setup Ayla Matter demo example:

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

      NOTE:

      For your device, you need to set the PAA path, for example:

      ./out/debug/chip-tool pairing ble-wifi 1 TEST 12345678 53725857 3549 --paa-trust-store-path /var/paa-root-certs/
    3. Register your device.
      Get the DSN used for your device and provide your Ayla account. Request Ayla Support team to register the device for you.

9. In-Field Provision

The In-Field Provisioning (IFP) feature is used in Ayla Integrated Agents and host apps that use the agent.

TODO: need some main concept on IFP.

If you want to use this feature, follow the steps below:

  1. Getting an OEM Provisioning Key Pair

Each OEM must create one (or more) provisioning keys for this feature. It may be desirable to have a separate key for each contract manufacturer so that they can be rescinded individually later.

To create a directory:

mkdir ifp
cd ifp

To create a key pair, use the following commands:

openssl genpkey -out private_key.pem -outform PEM -algorithm RSA
openssl rsa -in private_key.pem -out public_key.pem -pubout
  1. Uploading the Key

Using public_key.pem created in the previous step, make a JSON file containing the fields "oem" and "public_key" but with the newlines in the public key escaped as \n. One way to do this is with the following Python script (e.g. produce.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)      #Signing the Hardware ID

The resulting file keyfile.json will be about 494 bytes and look like this (but on 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 with the cloud.

Use the command to obtain your authentication:

curl -v -X POST -H "Content-Type: application/json" -d '{"user": {"application": {"app_secret": "aura_0dfc7900-eUo-3Se7R25Z_QLeEiXqYkQDUNA", "app_id": "aura_0dfc7900-id"}, "password": "your_password", "email": "your_email"}}' 'https://user-dev.aylanetworks.com/users/sign_in.json'

The authentication string is put in the AUTH variable 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 like this:

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

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

  1. Signing the Hardware ID in Manufacturing Scripts

At this writing, the manufacturing scripts are not yet modified to handle signing hardware IDs. The following bash script (e.g. signing.sh) demonstrates the steps needed:

#! /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

Here's an example use where the hardware-ID is 'mac-123456789abc':

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

The oem_signature will be a string 344 bytes long. This and the key ID can be pasted into the command line of the host app in setup mode as follows:

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

10. Host Application

Example Application

Please refer to the Example Application page for detailed information about the demo application.

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. This can be tested with the "crash hang" command found in the demo code.

Updated 1 day ago