Skip to content

Building for ESP32

This document covers building Ioto for ESP32 using the ESP IDF.

Please read the Building for general background first.

Requirements

Ioto on the ESP32 has the following requirements:

  • ESP32 device
  • At least 2MB PSIRAM

Please read Supported Hardware for a complete list.

Building Ioto for ESP32

This build sequence assumes you have your development environment setup on Linux or MacOS with the ESP-IDF installed. See ESP-IDF Setup for details.

To begin open a terminal and create a directory for your project and the Ioto component. Choose any name you like for the project directory.

1
2
3
mkdir -p myproject
cd myproject
mkdir components

Next, add the ESP IDF to your environment. 

1
. ~/path-to-esp-idf/export.sh

Download Ioto

Navigate to the Builder site and select Products in the sidebar menu and click on the download link for the Ioto Evaluation.

Product List

Extract the Ioto source code into the components directory. Then rename the ioto-VERSION* directory to ioto**.

1
2
3
4
cd components
tar xvfz ioto-VERSION.tgz
mv ioto-* ioto
cd ..

Sample apps

The Ioto source distribution includes several ESP32 sketch example apps. Each example includes the necessary configuration files that are copied from the relevant app directory into build tree.

Name Directory Description
blink apps/blink Blink a GPIO LED within the Ioto agent framework
demo apps/demo Create a demo counter and synchronize with the local and cloud databases

The default app is the blink app which is ideal to test if you have ESP and Ioto successfully installed and configured. You can select an app by providing an APP=NAME option to the make command.

To prepare for building the app and Ioto, invoke make with your selected app. The components/ioto/apps directory contains master copies of the Ioto demonstration apps. When you select an app, the code and configuration are copied to the ./main and ./fs directories.

1
make -C components/ioto esp32

or

1
make -C components/ioto APP=blink esp32

This command will perform the following steps:

  • Create the blink app at main/main.c
  • Create the app CMakeLists.txt
  • Create the file system partitions.csv
  • Create the app sdkconfig.defaults
  • Initialize the components/ioto for the blink app
  • Create some test certificates that may be required by the app

Configuration

Next, ensure your ESP target device is defined. For example, to set the target to esp32-s3:

1
idf.py set-target esp32-s3

The default build configuration is defined via the sdkconfig.defaults file. You can tailor the configuration by running:

1
idf.py menuconfig

The Ioto services are enabled via the Ioto menu config option. Navigate to 

1
2
Components config ---> 
Ioto

Then enable the desired services. This will update the ioto.json5 and regenerate the sdkconfig and include/ioto-config.h files.

Check your sdkconfig that the following settings are defined:

Key Value Description
CONFIG_ESP_MAIN_TASK_STACK_SIZE 8192 Main task stack size (in words)
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ 240 CPU frequency setting to the fastest setting
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240 y CPU frequence alias
CONFIG_ESPTOOLPY_FLASHSIZE 8MB Flash memory size
CONFIG_ESPTOOLPY_FLASHSIZE_8MB y Flash size alias

The full list is in components/ioto/apps/NAME/sdkconfig.defaults

Building with idf.py

Building is done using the ESP-IDF idf.py command rather than using the normal Ioto generic Makefiles which are used when building natively on Linux or MacOS.

To build for ESP32, run:

1
idf.py build

Update the Board Flash

To update your device with the built application:

1
idf.py -p PORT flash

Where PORT is set to the USB/TTY serial port connected to your device.

Monitoring Output

You can view the ESP32 and Ioto trace via the ESP32 monitor:

1
idf.py monitor

The app will turn the LED On/Off every 2 seconds and trace the LED status to the monitor.

Local Management

If the selected app enables the embedded web server, files will be served from the ./site directory. The Ioto embedded web server is configured via the web.json5 configuration file which is then copied to the state* directory.

Tech Notes

The stack size is configured to be 32K for the main app task and for spawned fiber tasks. Observationally, the minimum stack for the core Ioto is ~14K.

Ioto uses its own optimized printf implementation which uses less stack (<1K) and is more secure, being tolerant of errant NULL arguments.

The PlatformIO and Arduino build frameworks are not (yet) supported.