Integrated Agent v3.0

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 or ESP32-C3 module. See Integrated Agent and Edge Connectivity.

Changes in ADA-3.x from ADA-1.13

In ADA-3.0, the agent is changed to use MQTT with the cloud service, which provides lower latency and better connection status in the cloud. More of the platform code is now included in the agent to simplify the host application.

Important changes are as follows:

  1. The DNS hostname used to contact the service has changed from (or to Note the change from -device to -mqtt.
    If updating a device, the new DNS entry should be requested through your support contact or by e-mail to Ayla Support team.
  2. The configuration APIs, adap_conf_get() and adap_conf_set() are no longer required to be provided by the host application. This simplifies the configuration work for the application. The host application must still set up the NVS partition. This is shown in examples/ayla_demo.
  3. Several CLI changes have been made in examples/ayla_demo.
    The "nvs-set", "nvs-get", "nvs-dump", and "nvs-erase" commands have been removed and replaced with the "conf" command.
    The "time-get" and "time-set" commands have been replaced with the "time" command.
    The "esp-reboot" command has been removed in favor of the "reset" command.

First steps

  1. Obtain an Espressif dev kit. Any of the following would work: ESP32-DevKitC,

  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. 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 for the ESP32-WROOM-32E module, and demo-esp32c3 for the ESP32-C3 modules.

    Name:demo-esp 1.10
    Description:Demo ESP32 1.10
    Model:demo-esp32 or demo-esp32c3 or demo-esp32s3
    Version:demo_esp 1.10
    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.

  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.

Build and Run


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

  1. Download Ayla source code (ada-esp-idf-src-3.0.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. 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).
  3. Install a Docker Engine on your Windows, Mac, and/or Linux host OS.
  4. Create a Docker 64-bit Ubuntu container.
$ docker run --net=host --name=ada17 -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 ada17
$ docker attach ada17

  1. Prepare your development environment:

    1. Update the package list in your Ubuntu Docker instance:
      # apt update
    2. Install miscellaneous packages:
      # apt install nano screen iputils-ping
    3. Install prerequisites for Espressif Standard Setup of Toolchain v4.3.2 for Linux.
      # apt install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing
      If using Ubuntu 20.04, install using the following command:
      #  apt install gcc git wget make libncurses-dev flex bison gperf python3 python3-pip python3-setuptools python3-serial python3-cryptography python3-future python3-pyparsing
      If using Ubuntu 20.04, link using:
      # ln -s /usr/bin/python3 /usr/bin/python
    4. Create an esp directory, and change directory:
      # mkdir esp
      # cd esp
    5. Clone the Espressif IoT Development Framework:
      # git clone -b v4.4.2 --recursive esp-idf-v4.4.2
    6. Create the IDF_PATH environment variable, and persist the change in .bashrc:
      # export IDF_PATH=$HOME/esp/esp-idf-v4.4.2
      # echo "export IDF_PATH=\$HOME/esp/esp-idf-v4.4.2" >> ~/.bashrc
    7. Set up the Espressif tools using the following instructions:
      1. cd $IDF_PATH
      2. export IDF_GITHUB_ASSETS=""
      3. ./ 'esp32;esp32c3;esp32s3'
      4. . ./
      5. The above adds to the PATH environment variable. Persist the change in .bashrc:
      # echo "export PATH=$PATH" >> ~/.bashrc
  2. Test the development environment with the hello_world example:

    1. Change directory:
      # cd $IDF_PATH/examples/get-started/hello_world
    2. Customize configuration. (Defaults should be fine.)
      Set target to either esp32, esp32c3, or esp32s3, depending on your devkit.
      # set-target esp32 # menuconfig
    3. Build, flash, and monitor:
      # build
      # flash
      # monitor
      Output appears similar to this:
      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.
  3. Install Ayla source code:

    1. In a host terminal, copy ada-esp-idf-src-3.0.tgz to your Docker container:
      $ docker cp /home/matt/Downloads/ada-esp-idf-src-3.0.tgz ada16:/root/esp
    2. In your Docker terminal, extract the archive file:
      # cd /root/esp
      # tar zxvf ada-esp-idf-src-3.0.tgz
    3. Copy the ada-esp-idf-src-3.0 directory on top of the esp-idf-v4.4.2 directory:
      # cp -R ada-esp-idf-src-3.0/* ./esp-idf-v4.4.2
  4. Configure and build the Ayla agent and host application:

    1. Change directory:

      # cd $IDF_PATH/examples/ayla_demo
    2. Build, flash, and monitor:

      # set-target esp32 # or esp32c3 or esp32s3 as appropriate
      # build
      # erase_flash
      # flash
      # monitor
    3. Request a DNS CNAME entry from Ayla for the OEM-model and your OEM ID to point to the appropriate Ayla MQTT server. The DNS CNAME entry will be like, 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.

    4. Provision the device DSN and OEM credentials. Configure the same OEM model used in the template.

        # 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
        # setup_mode disable

Register your device

The Aura Mobile App running on iOS or Android 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.

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.