Integrated Agent v4.0.1

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

Who This Guide Is For

This guide is for developers setting up, building, flashing, and validating the Ayla Integrated Agent on an ESP32‑C3, ESP32‑C5, or ESP32‑C61 development kit. By the end of this guide, you will have a working demo application (ledevb, mda_demo, or mgmt_demo) built and flashed to your devkit, with DSN/OEM configuration completed and the device submitted for registration.

This guide covers both v4.0 and v4.0.1 in a single flow. Nearly every step is identical between the two versions; the handful of places where a command or detail differs are labeled (v4.0) or (v4.0.1). If a step has no label, it applies the same way to both versions.

Which Version Are You Building?

Guide Overview

This guide walks through the following process, in order:

1. Prepare your Ayla account, reserve a DSN, and create a device template.
2. Choose and set up a development environment (native Ubuntu, a Ubuntu VM, or Docker).
3. Install ESP‑IDF and build the hello_world example to validate your toolchain.
4. Install the Ayla source code and build, flash, and monitor an Ayla demo application.
5. Configure DSN and OEM information on the device.
6. Register the device with Ayla.

Changes in ADA‑4.0

In ADA‑4.0, the major changes are as follows:

1. ADA 4.0 runs on top of ESP‑IDF v5.5.4. ADA 4.0 refactors the agent kernel, transforming the agent's core from the hybrid protocol to the native MQTT protocol, and removes some deprecated features.
2. ADA 4.0 provides sufficient ADA 3.x APIs to support the porting of ADA 3.x firmware. The principle is to port ADA 3.x firmware to ADA 4.0 with minimal modifications to the firmware application.
3. ADA 4.0 provides three sample programs: ledevb, mda_demo, and mgmt_demo.
   • ledevb is the ADA 3.x sample demo_ledevb, which has been ported to ADA 4.0.
   • mda_demo is similar to ledevb, but based on the newly defined MDA API – a set of API interfaces based on message publishing and pushing, used for handling the sending and receiving of datapoints.
   • mgmt_demo is a stripped‑down example from which the network connection management part has been removed, retaining only the property sending and receiving part and OTA. Its main purpose is to provide OEM device management functions for devices that have their own network management (Matter devices, and Thread devices will be supported in the future).
4. LAN mode and file property feature support are broken in this version. See "What's New in ADA 4.0.1" below for the current status of LAN mode.
5. For building new products, you may consider using the pure MDA API, which allows dropping support for ADA 3.x APIs and can reduce the firmware size.

What's New in ADA 4.0.1

ADA 4.0.1 is the first version of the Integrated Agent shipped to customers. It builds on ADA 4.0 with:

• ESP‑IDF upgraded to v5.5.5.
• MQTT LAN mode. A new mechanism for LAN-based communication over MQTT. This is currently available on the device side only — the corresponding cloud-side support is not yet ready.
• Trusted root certificate updating. Devices can update their trusted root certificate store. This is currently available on the device side only — the corresponding cloud-side support is not yet ready.
• Bug fixes and stability improvements.

  📘

  NOTE

  Step-by-step configuration instructions for MQTT LAN mode and trusted root certificate updating are not yet included in this guide — they will be added once the corresponding CLI commands and Kconfig options are finalized and confirmed.

Prerequisites

Before you begin, make sure you have:

• A supported ESP32‑C3, ESP32‑C5, or ESP32‑C61 development kit and a USB serial cable.
• Access to the Ayla Networks Dashboard and the Ayla Developer Portal.
• Access to the Ayla source package for your version — contact the Ayla Support team if you do not already have it:
  • (v4.0) ada-esp-idf-4.0.dca2b32230-beta.tgz
  • (v4.0.1) ada-esp-idf-4.0.1.98f285c9b0-beta.tgz
• A Ubuntu 24.04 LTS environment available to you — native, in a VM, or via Docker.
• Your assigned OEM ID and OEM model, and, once reserved, your DSN and key information.

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. This section is the same for both versions.

1. Obtain an Espressif development kit. Any of the following will work

• ESP32‑C3‑DevKitM‑1
• ESP32‑C5‑DevKitC‑1
• ESP32‑C61‑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, follow these steps:

• Sign in to the Ayla Networks Dashboard.
• On 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 a device 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 mda-esp32c3-dev for the ESP32‑C3 module, mda-esp32c5-dev for the ESP32‑C5 modules, and mda-esp32c61-dev for the ESP32‑C61 modules.

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 (e.g. properties.csv), and import the file using the Import button.

base_type,direction,name,scope,track_only_changes,host_sw_version,ack_enabled,mime_type,passthrough,type
boolean,output,Blue_button,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
boolean,input,Blue_LED,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
string,input,cmd,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
decimal,input,decimal_in,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
decimal,output,decimal_out,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
boolean,input,Green_LED,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
integer,input,input,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
string,output,log,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
integer,output,output,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
boolean,input,p_bool_in,user,FALSE,FALSE,FALSE,null,TRUE,TemplateProperty
boolean,output,p_bool_out,user,FALSE,FALSE,FALSE,null,TRUE,TemplateProperty
decimal,input,p_dec_in,user,FALSE,FALSE,FALSE,null,TRUE,TemplateProperty
decimal,output,p_dec_out,user,FALSE,FALSE,null,null,TRUE,TemplateProperty
integer,input,p_int_in,user,FALSE,FALSE,FALSE,null,TRUE,TemplateProperty
integer,output,p_int_out,user,FALSE,FALSE,null,null,TRUE,TemplateProperty
string,input,p_str_in,user,FALSE,FALSE,null,null,TRUE,TemplateProperty
string,output,p_str_out,user,FALSE,FALSE,null,null,TRUE,TemplateProperty
string,output,schedule_out,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
file,input,stream_down,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
integer,output,stream_down_len,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
integer,output,stream_down_match_len,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
file,output,stream_up,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
integer,input,stream_up_len,user,FALSE,FALSE,FALSE,null,FALSE,TemplateProperty
string,output,version,user,TRUE,TRUE,FALSE,null,FALSE,TemplateProperty

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

GCC / Ubuntu / Docker

This section provides directions for building an Ayla ESP32 Solution using a GCC, Ubuntu, or Docker development environment. Ubuntu 24.04 LTS is recommended, and it can run natively, in a VM, or in a Docker container. Steps are the same for both versions except where a (v4.0) or (v4.0.1) label appears.

1. Choose Your Development Environment

Choose one of the following, and then continue with the matching subsection below:

• Docker — if you want an isolated, reproducible build environment.
• Ubuntu Virtual Machine — if you want to run Ubuntu 24.04 LTS inside a VM on Windows or macOS.
• Native Ubuntu 24.04 LTS — if your development machine already runs Ubuntu 24.04 LTS.

  📘

  NOTE

  Steps 3 onward apply the same way regardless of which environment you choose.

2. Identify the ESP32 Serial Port

1. List the serial ports on your computer before connecting the board (for example, ls /dev/tty* on Linux/macOS, or check Device Manager on Windows).
2. Connect your ESP32‑C3, ESP32‑C5, or ESP32‑C61 board to your computer with a USB serial cable.
3. List the serial ports again. The new port that appears is the one to use (for example, /dev/ttyUSB0).

   ⚠️

   WARNING

   Do not continue until you have identified the serial port. You will need it for the Docker container command below, or for flashing directly if you are using native Ubuntu or a VM.

3. Docker

Before using Docker to compile the Ayla solution, you need to have your own Docker engine ready. Choose your preferred Docker engine from the links below:

• Ubuntu / Debian (Docker Engine): https://docs.docker.com/engine/install/ubuntu/
• macOS (Docker Desktop): https://docs.docker.com/desktop/setup/install/mac-install/
• Windows (Docker Desktop + WSL2): https://docs.docker.com/desktop/setup/install/windows-install/
  Verify that Docker is working:

docker run --rm hello-world

Prepare the Docker compilation environment

• Clone the ESP‑IDF repository:
  (v4.0.1)

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

(v4.0)

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

If the clone is incomplete due to network issues, run the following command until it is complete (substitute your version's folder name):

  cd esp-idf-v5.5.5/
  git submodule update --init --recursive

• Prepare the local resource package:
  (v4.0.1)

  cp /mnt/hgfs/YOUR_SHARE_PATH/ada-esp-idf-4.0.1.98f285c9b0-beta.tgz .
  tar xzvf ada-esp-idf-4.0.1.98f285c9b0-beta.tgz

(v4.0)

  cp /mnt/hgfs/YOUR_SHARE_PATH/ada-esp-idf-4.0.dca2b32230-beta.tgz .
  tar xzvf ada-esp-idf-4.0.dca2b32230-beta.tgz

• Create a Dockerfile:

  mkdir docker
  cd docker/
  vim Dockerfile

Copy the following content into the Dockerfile and save it. This is the same for both versions.

  FROM ubuntu:24.04
 
  RUN apt-get update && apt-get install -y\
   bison\
   ccache\
   cmake\
   dfu-util\
   flex\
   git\
   gperf\
   libffi-dev\
   libssl-dev\
   libusb-1.0-0\
   ninja-build\
   python3-pip\
   python3-venv\
   python3\
   vim\
   wget\
   && pip3 install --break-system-packages PyYAML\
   && rm -rf /var/lib/apt/lists/* /root/.cache/pip

• Build the Docker image (same for both versions):

  docker build --tag ayla-mda-dev-esp-idf-ada-40 .
  cd

• Create and run the Docker container. Replace /dev/ttyUSB0 with the serial port you identified in Step 2. The container-side paths (/opt/ada-4.0, the image tag) stay the same for both versions — only the host-side source folder name changes:
  (v4.0.1)

  docker run -it --rm \
     -v $(pwd)/ada-esp-idf-4.0.1.98f285c9b0-beta:/opt/ada-4.0 \
     -v $(pwd)/esp-idf-v5.5.5:/opt/esp-idf-v5.5.5 \
     -v $(pwd)/.espressif:/opt/.espressif \
     -e IDF_PATH=/opt/esp-idf-v5.5.5 \
     --device=/dev/ttyUSB0 \
     ayla-mda-dev-esp-idf-ada-40:latest

(v4.0)

  docker run -it --rm \
     -v $(pwd)/ada-esp-idf-4.0.dca2b32230-beta:/opt/ada-4.0 \
     -v $(pwd)/esp-idf-v5.5.4:/opt/esp-idf-v5.5.4 \
     -v $(pwd)/.espressif:/opt/.espressif \
     -e IDF_PATH=/opt/esp-idf-v5.5.4 \
     --device=/dev/ttyUSB0 \
     ayla-mda-dev-esp-idf-ada-40:latest

• Compile the firmware inside the Docker container (substitute your version's IDF path):

  cd /opt/esp-idf-v5.5.5/
  ./install.sh
  . export.sh
  cd ../
  cd ada-4.0/
  make APP=ledevb IDF_TARGET=esp32c3   # APP=mda_demo or mgmt_demo

• Flash the firmware and view the device (same for both versions):

  make IDF_TARGET=esp32c3 erase-flash   # IDF_TARGET=esp32c5 or esp32c61
  make APP=ledevb IDF_TARGET=esp32c3 flash
  make monitor

• After compilation and flashing are complete, exit the container:

  exit

4. Ubuntu Virtual Machine or Native Ubuntu

If you are using a VM, use VirtualBox or other VM software to install an Ubuntu 24.04 LTS OS:

• Download VirtualBox: https://www.virtualbox.org/wiki/Downloads
• Install VirtualBox: https://www.virtualbox.org/manual/ch02.html

Prepare your development environment on Ubuntu 24.04

The following steps are the same for both versions except the ESP-IDF clone and environment variable, which are labeled.

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 prerequisites:
   (v4.0.1) For Toolchain v5.5.5 for Linux:

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

(v4.0) The same package list applies for Toolchain v5.5.4 for Linux.

4. Create an esp directory and change to it:

   cd $HOME
   mkdir esp
   cd esp

5. Clone the Espressif IoT Development Framework:
   (v4.0.1)

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

(v4.0)

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

6. Set the IDF_PATH environment variable and persist the change in .bashrc:
   (v4.0.1)

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

(v4.0)

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

7. Set up the Espressif tools:

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

Open a shell terminal and load the ESP-IDF environment

Open a new terminal, and load the ESP-IDF environment variables into it. You will need to repeat this in every new terminal you use to build firmware:

source $IDF_PATH/export.sh

Test the development environment with the "hello_world" example

1. Open a new terminal to compile hello_world. Change directory:

   cd $IDF_PATH/examples/get-started/hello_world

Customize configuration (defaults should be fine).

2. Set target to either esp32c3, esp32c5, or esp32c61, depending on your devkit:

   idf.py set-target esp32c3
   idf.py menuconfig

3. Build, flash, and monitor:

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

4. The output appears similar to the following. This capture is from a v4.0.1 / IDF v5.5.5 build — if you're building v4.0, your log will show ESP-IDF v5.5.4 instead, and the rest of the output will be the same shape:

   I (35) boot: ESP-IDF v5.5.5 2nd stage bootloader
   I (35) boot: compile time Jul 29 2026 11:40:56
   I (35) boot: chip revision: v0.4
   I (35) boot: efuse block revision: v1.3
   I (39) boot.esp32c3: SPI Speed      : 80MHz
   I (43) boot.esp32c3: SPI Mode       : DIO
   I (46) boot.esp32c3: SPI Flash Size : 2MB
   I (50) boot: Enabling RNG early entropy source...
   I (55) boot: Partition Table:
   …
   Hello world!
   This is esp32c3 chip with 1 CPU core(s), WiFi/BLE, silicon revision v0.4, 2MB external flash
   Minimum free heap size: 331296 bytes
   Restarting in 10 seconds...
   Restarting in 9 seconds...
   Restarting in 8 seconds...
   Restarting in 7 seconds...
   Restarting in 6 seconds...

Press Ctrl + ] to exit the monitor.

5. Install Ayla Source Code

1. Download the Ayla source code for your version. ada stands for Ayla Device Agent.
   • (v4.0.1) ada-esp-idf-4.0.1.98f285c9b0-beta.tgz
   • (v4.0) ada-esp-idf-4.0.dca2b32230-beta.tgz

     📘

     NOTE

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

2. Copy the Ayla code into your Ubuntu OS. For example:
   (v4.0.1)

   cd $HOME
   cp /home/matt/Downloads/ada-esp-idf-4.0.1.98f285c9b0-beta.tgz .

(v4.0)

   cd $HOME
   cp /home/matt/Downloads/ada-esp-idf-4.0.dca2b32230-beta.tgz .

3. Extract the archive file:
   (v4.0.1)

   tar zxvf ada-esp-idf-4.0.1.98f285c9b0-beta.tgz

(v4.0)

   tar zxvf ada-esp-idf-4.0.dca2b32230-beta.tgz

6. Build the Ayla Host Application

Open a new terminal to compile the firmware. Change directory into the folder you extracted in the previous step:

(v4.0.1)

cd ada-esp-idf-4.0.1.98f285c9b0-beta/

(v4.0)

cd ada-esp-idf-4.0.dca2b32230-beta/

In addition to the original idf.py compilation, make compilation is also supported. These commands are identical for both versions.

• Using idf.py:

  APP=ledevb idf.py set-target esp32c3   # APP=ledevb or mda_demo or mgmt_demo; target esp32c5 or esp32c61 as appropriate
  APP=ledevb idf.py build
  APP=ledevb idf.py erase_flash
  APP=ledevb idf.py flash
  idf.py monitor

• Using make:

  make APP=ledevb IDF_TARGET=esp32c3      # APP=mda_demo or mgmt_demo
  make IDF_TARGET=esp32c3 erase-flash     # IDF_TARGET=esp32c5 or esp32c61
  make APP=ledevb IDF_TARGET=esp32c3 flash
  make monitor

Flash Firmware Error Troubleshooting

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

A fatal error occurred: bootloader/bootloader.bin requires chip revision in
range [v0.4 - v0.99] (this chip is revision v0.3). Use --force to flash anyway.

This means the firmware was built for a minimum chip revision that does not match the connected board. Confirm your target device and ESP-IDF configuration 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 in this section:

7. Configure DSN and OEM Info

This section is the same for both versions.

1. Confirm your OEM ID and OEM model — these are assigned by Ayla and used throughout this step.
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 with the appropriate Ayla native MQTT server. The DNS CNAME entry will be like <oem-model>-<oem-id>-nmqtt.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 email to the Ayla Support team.
3. Provision the device DSN and OEM credentials. Configure the device DSN and the same OEM model used in the template:

   conf set id/dev_id AC000W000000001
   conf set id/key MIIB... (long number)
   oem 000000000                    # replace with your Ayla OEM ID
   oem model xxx-esp32c3            # replace with OEM model from template
   oem key 0123456789abcdef0123456789abcdef   # replace with your OEM secret and the OEM model from the template
   setup_mode disable               # close your device setup_mode

8. Register Your Device

Provide the DSN, OEM model, and your Ayla account information to the Ayla Support team so they can register the device for you.