Guides

Integrated Agent v3.1

Suggest Edits

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.1 from ADA-3.0

In ADA-3.1, 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 ConnectedHomeIP SDK, the ADM is based on the tag v1.0.0.2.
  4. The ESP-IDF is upgraded to v4.4.6 to support Matter protocol.

First steps

  1. Obtain an Espressif dev kit. Any of the following would 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 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.

    Visibility:private
    Name:demo-esp 1.10
    Description:Demo ESP32 1.10
    Registration:AP-Mode
    Model:demo-esp32 or matter-demo-esp32 or demo-esp32c3 or demo-esp32s3
    Version:demo_esp 1.10
    Type:Wifi
    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 tls. 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=ada31 -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 ada31
docker attach ada31

  2. Use VirtualBox or other VM software to install an Ubuntu 22.04 LTS OS.
    Download VirtualBox: https://www.virtualbox.org/wiki/Downloads
    Install VirtualBox: https://www.virtualbox.org/manual/ch02.html

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 prerequisites for Espressif Standard Setup for Toolchain v4.4.6 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
  4. Create an esp directory and change directory. 
    cd $HOME
mkdir esp
cd esp
  5. Clone the Espressif IoT Development Framework. 
    git clone -b v4.4.6 --depth 1 --recursive https://github.com/espressif/esp-idf.git esp-idf-v4.4.6
  6. Create the IDF_PATH environment variable and persist the change in .bashrc. 
    export IDF_PATH=$HOME/esp/esp-idf-v4.4.6
echo "export IDF_PATH=\$HOME/esp/esp-idf-v4.4.6" >> ~/.bashrc
  7. Set up the Espressif tools using the following instructions: 
    cd $IDF_PATH
export IDF_GITHUB_ASSETS="dl.espressif.com/github_assets"
./install.sh
  8. 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.
  9. 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
  10. Create a chip directory and change directory. 
    cd $HOME 
mkdir chip
cd chip
  11. Clone the Matter SDK. 
    git clone -b v1.0.0.2 --depth 1 https://github.com/project-chip/connectedhomeip matter
cd matter
./scripts/checkout_submodules.py --shallow --platform esp32
  12. 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
  13. Set up the CHIP environment using the following instructions.
    It may fail due to network issues, please retry it until it is successful. 
    echo 'cython<3' > /tmp/constraints.txt
PIP_CONSTRAINT=/tmp/constraints.txt bash ./scripts/activate.sh
  14. Some Python libraries need to be installed into 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.1.3.tgz).
    ada stands for Ayla Device Agent.
    NOTE: If you do not have access to Ayla source code, please request for the access to Ayla Connection from Ayla Support team.
  2. Copy the Ayla code into your Ubuntu OS.
    1. Copy ada-esp-idf-src-3.1.3.tgz to your Docker container
      1. In a host terminal, copy ada-esp-idf-src-3.1.3.tgz to your Docker container. 
        docker cp /home/matt/Downloads/ada-esp-idf-src-3.1.3.tgz ada31:/root/esp
      2. In your Docker terminal, extract the archive file 
        cd $HOME/esp
tar zxvf ada-esp-idf-src-3.1.3.tgz
      3. Copy the ada-esp-idf-src-3.1 directory on top of the esp-idf-v4.4.6 directory. 
        cp -R ada-esp-idf-src-3.1/* esp-idf-v4.4.6

7. Build the Ayla host application

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

    1. Open a new terminal to compile non-Matter device.
    2. Change directory: 
      cd $IDF_PATH/examples/ayla_matter_demo
    3. Build, flash, and monitor: 
      idf.py set-target esp32 # or esp32c3 or esp32s3 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
    3. 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

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 --mqtt.aylanetworks.com, replace with the OEM model from the template, and 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 to run 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 pass 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 argen command generates QR Code, use browser to access the QR code URL to get the QR Code. The discriminator and passcode are used for chip-tool setup 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 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, 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. Host Application

Example Application

Please refer to 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 10 months ago