Integrated Agent v4.0

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.

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 and will be supported in future versions.
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.

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 (ada-esp-idf-4.0.dca2b32230-beta.tgz) — contact the Ayla Support team if you do not already have it.
• 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.

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. (BLE and LAN modes will be supported in the future, so you may omit those options for now.)

Build and Run

GCC / Ubuntu / Docker

This section provides directions for building an Ayla ESP32 Solution v4.0 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, 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.

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. Whether you want to install Docker engine on Windows, Mac, or a virtual machine, you can get help from the official Docker documentation. 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

4.Prepare the Docker compilation environment

• Clone the ESP‑IDF v5.5.4 repository:

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:

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

• Prepare the local resource package (ada-esp-idf-4.0.dca2b32230-beta.tgz):

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:

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:

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:

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 ADA 4.0 firmware inside the Docker container:

cd /opt/esp-idf-v5.5.4/
./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:

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

Expected result: The build completes without errors, the device flashes successfully, and make monitor shows the demo application starting up.

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

exit

5. 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

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. Install prerequisites for Espressif Standard Setup for Toolchain v5.5.4 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

4. Create an esp directory and change to it:

cd $HOME
mkdir esp
cd esp

5. Clone the Espressif IoT Development Framework:

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:

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:

I (35) boot: ESP-IDF v5.5.4 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.

6. Install Ayla Source Code

1. Download the Ayla source code (ada-esp-idf-4.0.dca2b32230-beta.tgz). ada stands for Ayla Device Agent.

   📘

   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:

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

3. Extract the archive file:

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

7. Build the Ayla Host Application

Open a new terminal to compile an ADA 4.0 firmware. Change directory:

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

Due to the upgrade of the new ADA version, in addition to the original idf.py compilation, we also support make compilation.

• 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

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.