Overview

This topic provides all the necessary information to get started on the Espressif platforms supported by Qt Quick Ultralite.

Compatible versions

Qt Quick Ultralite for ESP32 platforms has been tested using Espressif IoT Development Framework (ESP-IDF) version 5.3.

Installing prerequisites

Make sure you have all the prerequisites installed before preparing the ESP-IDF environment.

Espressif ESP32-S3-BOX-3

• Qt Quick Ultralite 2.12.0
• Qt Quick Ultralite Espressif ESP32-S3-BOX-3 platform package
• Espressif ESP32-S3-BOX-3
• Espressif IoT Development Framework (ESP-IDF)

Flashing prebuilt binaries

Qt for MCUs offers a selection of prebuilt binaries showing various demos and examples. To flash these, follow the flashing instructions.

Preparing the environment

Setting up ESP-IDF

Follow the Get Started guide from Espressif to setup the environment for development.

Setting up the environment

Before building the application, set the following environment variables:

export QUL_ROOT=$HOME/Qt/QtMCUs/2.12.0

set QUL_ROOT=C:\Qt\QtMCUs\2.12.0

Building the application

Exporting the Qt Quick Ultralite application

Export the application code using the qmlprojectexporter:

$QUL_ROOT/bin/qmlprojectexporter \
/path/to/your/project.qmlproject \
--boarddefaults=$QUL_ROOT/platform/boards/espressif/esp32s3-box3-idf/cmake/BoardDefaults_16bpp.qmlprojectconfig \
--toolchain GNU \
--platform esp32s3-box3-idf \
--outdir /path/to/project_output_dir \
--project-type esp-idf \
--generate-entrypoint \
--platform-metadata $QUL_ROOT/platform/boards/espressif/esp32s3-box3-idf/esp32s3-box3-idf_16bpp_Linux_xtensagcc-metadata.json

%QUL_ROOT%\bin\qmlprojectexporter ^
C:\path\to\your\project.qmlproject ^
--boarddefaults=%QUL_ROOT%\platform\boards\espressif\esp32s3-box3-idf\cmake\BoardDefaults_16bpp.qmlprojectconfig ^
--toolchain GNU ^
--platform esp32s3-box3-idf ^
--outdir C:\path\to\project_output_dir ^
--project-type esp-idf ^
--generate-entrypoint ^
--platform-metadata %QUL_ROOT%\platform\boards\espressif\esp32s3-box3-idf\esp32s3-box3-idf_16bpp_Windows_xtensagcc-metadata.json

If the Qt Quick Ultralite application uses selectors for different variants, add them with the --selector argument for qmlprojectexporter. For example, the Qt Quick Ultralite Thermostat Demo uses the following selectors:

--selector normal,small

The default configuration for Espressif platforms is to export Qt Quick Ultralite libraries that are built with MinSizeRel configuration. If you have built Qt Quick Ultralite libraries with a different build configuration (such as Debug), override the build type by adding --qul-build-type argument to the qmlprojectexporter command:

--qul-build-type Debug

Several examples shipped with Qt Quick Ultralite do not have main() function in the application code. Use the --generate-entrypoint argument while exporting these examples, unless you are adding a main() function. For more info about writing a main() function initializing Qt Quick Ultralite, see Running Qt Quick Ultralite in applications.

When exporting examples with --include-metadata-extra-target argument, make sure the --outdir is not inside the example source directory.

See the qmlprojectexporter documentation, QmlProject Manual, and Generating projects for Espressif IoT Development Framework (ESP-IDF) for more information about qmlprojectexporter, QmlProject, and ESP-IDF project generation.

Working with the ESP-IDF project

The exported Qt Quick Ultralite application is an ESP-IDF project, where the application is one of the components. The details of the project structure and how to work with it can be found here.

Building the ESP-IDF project

1. Set up the ESP-IDF environment: Linux Windows

   . $HOME/esp/esp-idf/export.sh

   Launch the ESP-IDF Command Prompt or ESP-IDF PowerShell Environment.

2. Build and flash the application: Linux Windows

   cd /path/to/project_output_dir
   idf.py build
   idf.py flash

   cd C:\path\to\project_output_dir
   idf.py build
   idf.py flash

Debugging

Reading debug messages

ESP-IDF provides a monitor tool that can be used to read debug messages. Use the following command to launch the tool:

idf.py monitor

Using a debugger

ESP-IDF supports debugging applications. Use one of the following commands: to launch the debugger:

• idf.py gdb runs GDB in the command prompt.
• idf.py gdbgui runs a graphical GDB UI in a browser.
• idf.py gdbtui runs GDB text user interface in the command prompt.
• idf.py openocd launches a debug server that you can connect to with GDB.

Board-specific information

The currently supported Espressif targets are listed below. For more information on all the targets supported by Qt Quick Ultralite, see Supported target boards and development hosts.

Tier 2: Verified targets

Resource cache policy

By default, an application's resource data is copied to SDRAM on startup. In order to retain these resources in flash and not load them to RAM on startup, add the following QmlProject option to your qmlproject file:

MCU.Config {
    resourceCachePolicy: "NoCaching"
}

Alternatively, it can be enabled only for individual images like this:

ImageFiles {
    files: [
        "big/button.png"
    ]
    MCU.resourceCachePolicy: "NoCaching"
}