Zephyr is an RTOS for embedded systems. It provides a fully preemptible tickless kernel, both cooperative and preemptive threading, semaphores and queues.

Qt Quick Ultralite offers tools which enable easy integration with a pre-existing Zephyr project. The Qt Quick Ultralite Zephyr module is a west module that runs qmlprojectexporter during the Zephyr CMake configure step, maps the Zephyr board to a Qt Quick Ultralite platform, and adds the generated sources to the build as a Zephyr library. The module is configured through Kconfig and provides the west build-qul-libs command for building the Qt Quick Ultralite target libraries.

Supported architectures, platforms and Zephyr versions

Qt Quick Ultralite supports the following hardware:

In addition, Qt Quick Ultralite supports Zephyr's host-based simulator board, which runs Zephyr as an application on the development host:

Prerequisites

You need to install the following prerequisites to start working with the Qt Quick Ultralite Zephyr module:

• Qt for MCUs 2.12.3
• Qt Quick Ultralite platform package (see supported platforms)
• Zephyr 4.4.0
• A toolchain for the target:
  • Zephyr SDK 1.0.1
  • GNU Compiler Collection (GCC) for native_sim
• CMake 3.21.1 or newer
• Ninja 1.10.0 or newer
• Python 3.12 or newer

Workflow

The overall workflow for creating and compiling a Qt Quick Ultralite application is as follows:

Setting up a new application

This section covers setting up the Zephyr application that runs Qt Quick Ultralite. To create the Qt Quick Ultralite application, see Qt Design Studio on MCUs documentation.

Creating a Zephyr application directory

Qt Quick Ultralite runs in a Zephyr thread of its own that the Zephyr application creates. The thread runs the Qt Quick Ultralite event loop through Qul::Application::exec() and is self-contained; the rest of the Zephyr application runs alongside it. The application that creates the thread consists of a CMakeLists.txt file, a prj.conf file, and the application sources.

Create a directory for the west workspace, and the application directory app with its src subdirectory under it:

mkdir myproject
cd myproject
mkdir -p app/src

mkdir myproject
cd myproject
mkdir app\src

Obtaining the Qt Quick Ultralite Zephyr module repository

The Qt Quick Ultralite Zephyr module is distributed as a git bundle file included in the Qt Quick Ultralite installation:

<QT_INSTALL>/QtMCUs/2.12.3/platform/boards/zephyr/qtultralight-zephyr-module.bundle

Use the bundle to create a local copy of the module repository, then make that copy available from a git server that your west workspace can reach:

git clone --origin bundle <path/to/qtultralight-zephyr-module.bundle> qtultralight-zephyr-module
cd qtultralight-zephyr-module
git branch -m main
git remote add origin <your-git-server-url>/qtultralight.git
git push origin main

Use the same server URL as the url-base value for the qt remote in app/west.yml, which is created in the next step.

Each Qt Quick Ultralite release includes an updated bundle. To move to a new Qt Quick Ultralite version, repeat these steps with the bundle from that release and update the copy on your git server. Then run west update in existing west workspaces to pull the new commit.

Creating app/west.yml

These steps keep the west manifest in the application directory, which makes app the manifest repository as well. A manifest repository that is separate from the application works the same way. For the workspace topologies that west supports, see west workspaces.

Create the west manifest in app/west.yml. Set url-base for the qt remote to the git server URL you pushed the Qt Quick Ultralite Zephyr module repository to in the previous step. Add the Qt Quick Ultralite Zephyr module as a project in it, with import: true so that west also reads the module's own manifest, which declares the build-qul-libs extension command:

manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
    - name: qt
      url-base: https://your.git.server/path

  projects:
    - name: zephyr
      remote: zephyrproject-rtos
      revision: v4.4-branch
      import: true

    - name: qtultralight
      remote: qt
      repo-path: qtultralight.git
      revision: main
      path: qtultralight
      import: true

  self:
    path: app

The repository that the qtultralight project points to is a thin wrapper. It contains only the Zephyr integration: the Kconfig definitions, the Zephyr CMake files, and the west build-qul-libs command. Qt Quick Ultralite itself is not part of it, so west update clones the wrapper alone.

The host tools such as qmlprojectexporter, the platform sources, and the target libraries come from a Qt Quick Ultralite installation that is kept outside the west workspace. The module locates that installation through QUL_ROOT.

Initializing and updating the workspace

west init -l app
west update

Creating app/CMakeLists.txt

Create a simple CMakeLists.txt file in app/ that lists the application sources:

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(myapp)

target_sources(app PRIVATE src/qul_main.cpp)

The generated project also includes the platform port's zephyr-linker-sources.cmake, which adds the Qt Quick Ultralite linker sections to the Zephyr-generated linker script.

Creating app/prj.conf

Create app/prj.conf to enable the module and point it at the qmlproject file:

CONFIG_QUL=y
CONFIG_QUL_QMLPROJECT_FILE="path/to/your/qul_application.qmlproject"

CONFIG_QUL_QMLPROJECT_FILE accepts an absolute path, a path relative to the application directory, or a path starting with ~.

These two options are the minimal configuration. See the Kconfig reference for a full list of Qt Quick Ultralite specific Kconfig values.

Creating app/src/qul_main.cpp

Create the application entry point in app/src/qul_main.cpp. This source file provides the thread that runs Qt Quick Ultralite. The QML root item header is generated from the .qmlproject file at build time and is available on the include path automatically:

#include "MainScreen.h"

#include <qul/application.h>
#include <qul/qul.h>
#include <zephyr/kernel.h>

#define QUL_THREAD_STACK_SIZE 16384
#define QUL_THREAD_PRIORITY   5

static void qul_thread_entry(void *, void *, void *)
{
    Qul::initHardware();
    Qul::initPlatform();

    Qul::Application app;
    static MainScreen item;
    app.setRootItem(&item);
    app.exec();
}

K_THREAD_DEFINE(qul_tid, QUL_THREAD_STACK_SIZE,
                qul_thread_entry, NULL, NULL, NULL,
                QUL_THREAD_PRIORITY, 0, 0);

K_THREAD_DEFINE creates the Zephyr thread at boot. The thread entry point initializes the hardware and the platform before it starts the Qt Quick Ultralite event loop.

Setting QUL_ROOT

The Qt Quick Ultralite Zephyr module requires a Qt for MCUs installation to work. Set the QUL_ROOT environment variable to the installation directory, so that the module finds the host tools, the platform sources, and the libraries:

export QUL_ROOT=$HOME/Qt/QtMCUs/2.12.3

set QUL_ROOT=C:\Qt\QtMCUs\2.12.3

You can also set QUL_ROOT by passing it to the west build command, after --:

west build -b <board> app -- -DQUL_ROOT=$HOME/Qt/QtMCUs/2.12.3

west build -b <board> app -- -DQUL_ROOT=C:\Qt\QtMCUs\2.12.3

Configuration

The Qt Quick Ultralite Zephyr module adds Kconfig options that configure how Qt Quick Ultralite is built into the Zephyr application. Set the options in the application's prj.conf, or through the interactive Kconfig interface:

west build -b <board> app -t menuconfig

Where <board> is the Zephyr board target and -b is the short form of --board. The menuconfig target runs the CMake configure step, which needs the board target. Once the build directory exists, west reuses the board from the CMake cache and you can leave out -b <board>.

The Qt Quick Ultralite options are under Modules > qtultralight. Changes are saved to build/zephyr/.config and take effect on the next west build. For the complete list of options, see the Kconfig reference.

The Qt Quick Ultralite application itself is configured in its .qmlproject file and in the platform's BoardDefaults_*.qmlprojectconfig file, see QmlProject manual and Defining default variables for the platform. The module locates the Qt Quick Ultralite installation and the platform sources through CMake variables and environment variables, see CMake variable reference and Environment variable reference.

Building

By default, Qt Quick Ultralite uses the prebuilt libraries from the installation. To build the libraries yourself, see Building the Qt Quick Ultralite libraries.

Build the application by running west build with the target board:

west build -b <board> app

Where <board> is the Zephyr board target. For the board target to use, see the board-specific page listed in Supported architectures, platforms and Zephyr versions.

The module maps the board target to a Qt Quick Ultralite platform through the QUL_ZEPHYR_BOARDS variable. Each platform port lists the board targets that it supports in its zephyr-boards.cmake file, and the module selects the port whose list contains the board target verbatim.

Rebuilding after changes

When you change the QML files or the .qmlproject file of the Qt Quick Ultralite application, you only need to rebuild the Zephyr project. qmlprojectexporter automatically re-exports the Qt Quick Ultralite application if any changes are detected.

Flashing

For hardware boards, flash the built application with west:

west flash

Building the Qt Quick Ultralite libraries

By default, Qt Quick Ultralite uses the prebuilt libraries from the installation, which are built in the MinSizeRel or Release configuration. To build your own libraries, run west build-qul-libs. The following example builds them in the Debug configuration:

west build-qul-libs --board <board> --build-type Debug

Where <board> is the Zephyr board target, the same value as for west build.

The command builds the Qt Quick Ultralite platform and core libraries and installs them into <build-dir>/qul_install. It does not build the application. After the libraries are installed, the command reconfigures the Zephyr build directory so that the next west build picks up the new libraries.

The command supports the following options:

The build directory is expected to be configured for the same board as the library build. If --board does not match the board recorded in the build directory, the command stops with an error.

DeviceLink

DeviceLink exchanges touch, performance, and log data between the device and a host. Enable it in the application's prj.conf:

CONFIG_QUL_DEVICELINK=y

The module then applies the platform port's DeviceLink devicetree overlay and Kconfig fragment, and selects the matching platform metadata. DeviceLink is a compile-time feature, so run west build-qul-libs after changing the option.

For more information, see Porting DeviceLink communication.

Kconfig reference

The following options are available when CONFIG_QUL is enabled. Set them in the application's prj.conf or through west build app -t menuconfig.

CMake variable reference

Pass these variables to west build after --, for example west build -b <board> app -- -DQUL_ROOT=<path/to/qul>.

Environment variable reference

Porting Qt Quick Ultralite to a Zephyr platform

You can port Qt Quick Ultralite to a Zephyr platform by following the Qt Quick Ultralite Platform Porting Guide. In the reference ports, the following parts have been implemented using Zephyr APIs:

• currentTimestamp() calls k_uptime_get().
• Touch support is done using the Zephyr Input API.
• Qt Quick Ultralite Queues use Zephyr message queues.
• Semaphores are used to suspend and resume Qt Quick Ultralite thread operation.
• qul_malloc(), qul_realloc(), and qul_free() call k_malloc(), k_realloc(), and k_free(), so the Qt Quick Ultralite dynamic allocations come from the Zephyr kernel heap. Size that heap with CONFIG_HEAP_MEM_POOL_SIZE to cover the allocations that the application makes, such as the UI tree, image buffers, and font data. For the allocator API, see Memory allocation in Qt Quick Ultralite platform abstraction.
• Display interrupt is set up and enabled using Zephyr:

  void setInterruptPriorities()
  {
      IRQ_CONNECT(LCDIF_IRQn, 3, displayIRQHandler, NULL, 0);
      irq_enable(LCDIF_IRQn);
  }

• LCD screen pinmux is initialized using Zephyr pin control API

  #define LCDIF_DEV DT_NODELABEL(lcdif)
  
  void initializeLcdPinmux()
  {
      PINCTRL_DT_DEFINE(LCDIF_DEV);
  
      pinctrl_apply_state(PINCTRL_DT_DEV_CONFIG_GET(LCDIF_DEV), PINCTRL_STATE_DEFAULT);
  }

Zephyr Kconfig options

A platform port that is used with the module provides the Zephyr Kconfig options that Qt Quick Ultralite requires on the target in its qul_module.conf file. The module appends that file to EXTRA_CONF_FILE before Kconfig runs, which applies the options to the application build.

For the options that the reference ports require, see Required Kconfig options on the board pages.