How To Test Applications on MCUs

Overview

This guide explains how to set up automated testing for Qt Quick Ultralite (QUL) applications with Squish for MCU. It covers the setup flow for a Desktop AUT and highlights the additional steps required when testing on physical MCU hardware.

Follow the sections below when setting up automated testing for a new AUT. Use the jobinfo.json reference and Advanced MCU tool configuration sections for sophisticated use cases and additional configuration options.

Prerequisites

To automate testing of Qt Quick Ultralite (QUL) applications on microcontroller units (MCUs), the following software and hardware are required, with optional items clearly indicated:

1. Squish Enterprise license
2. Squish for MCU package for Linux or Windows
3. Supported MCU board, optionally with a debug probe
4. Serial/UART connection to the MCU board, or USB connection to the debug probe
5. MCU vendor tools for the MCU board (optional)

To get the most out of image-based test automation, we recommend installing and configuring one of the supported OCR engines too.

Supported MCU target boards for automated testing

For an MCU board to support automated testing of QUL applications, Qt Quick Ultralite provides Device Link implementation for that specific hardware. Device Link is required to enable communication between the host and the device and Squish for MCU leverages it to:

• inject user input (e.g. touch events)
• capture screenshots for image-based verification
• exchange performance and logging data needed for debugging and test execution

To determine whether a particular board supports test automation with Squish for MCU, consult the official Qt for MCUs platform support documentation, which is the authoritative reference. For MCU platforms without Device Link implementation, Qt for MCUs step-by-step porting guide contains instructions on how to implement Device Link support yourself.

Connecting the Device

For basic device connectivity and image-based automated testing, a serial/UART connection is sufficient. However, with a raw UART connection, some convenience features provided by Squish for MCU, such as flashing the AUT onto the device and resetting the AUT to its initial state before a test begins, are not available. These operations rely on MCU vendor tools, and we recommend using them together with a debug probe and USB connection for reliable communication.

Debug probes

Vendor-specific debug probes (e.g. an NXP board paired with an NXP probe) are preferable. As a third-party option, J-Link debug probes are supported, with some limitations for native debugger reset.

Installing MCU Vendor Tools

Installing MCU vendor tools is optional. Without these tools, however, some of the convenience features of Squish for MCU (notably flashing the AUT onto the MCU device and resetting the AUT) are not available. For testing with these features, only a subset of vendor tools is required rather than the full package as follows:

For an authoritative reference on the supported versions of these tools for each board, consult the Qt for MCUs list of prerequisites. The location of vendor tools on the PC can be set during Squish for MCU installation, and the installer also provides download links for convenience.

Configuring MCU Vendor Tool Paths

After Squish for MCU is installed, configure the MCU vendor tool paths in Squish IDE by going to "Edit > Server Settings > MCU Settings". For detailed information about configuring access to MCU vendor tools in the Squish IDE, see the MCU Settings pane.

Advanced configuration methods are described in Advanced MCU tool configuration.

Building the AUT with Device Link Enabled

Before Squish for MCU can control the AUT, the AUT must be built with Device Link enabled. For details, see Making your QUL AUT testable.

Packaging the Test Crate

A test crate is a .tar.gz archive that contains the files required to set up and run the AUT. The contents of the test crate depend on whether the AUT is built for a Desktop target or for a physical MCU target.

Create the test crate manually by packaging the required files described below into a .tar.gz archive. For a Desktop target, include all files required to run the application from the unpacked test crate. For example, on Windows, this may include additional DLLs if they are not already available through the system PATH. How these files are produced or provided depends on the toolchain and development environment used to build the AUT.

Setting up a Desktop AUT

A Desktop target is a Qt Quick Ultralite application built to run on a desktop platform. It can be used to create and record tests without a physical MCU device.

For Desktop targets, the AUT must be built as a Qt application with Device Link enabled. Since the Desktop target does not run on physical hardware, MCU vendor tools are not required.

The test crate must contain the Desktop AUT executable and a jobinfo.json file, and any additional files required to run the application.

For Desktop AUTs, these additional files can include Qt runtime dependencies, such as the QtCore, QtGui, or QtWidgets libraries, and the platform plugin for the target desktop platform, unless they are already available in the runtime environment.

For example, a jobinfo.json file for a Desktop AUT can look as follows:

{
    "deviceType": "qt",
    "elf": "awesome-aut.exe"
}

The elf field points to the AUT executable. On Windows, the executable usually has the .exe extension, while on Linux it typically has no file extension.

To set up the Desktop AUT in Squish IDE, create an MCU test suite and select Desktop (Default) from the device list.

Click Flash MCU Device to open the Flash Device dialog.

In the Flash Device dialog, select the previously created test crate and click Flash.

For a Desktop target, this step does not flash physical hardware. Instead, Squish registers the AUT so that it knows which application to start for Record and Replay. Squish also creates an internal cache associated with the AUT.

After this step completes, the Desktop AUT is ready to use with Record and Replay.

Test crate for MCU AUTs

For physical MCU targets, the test crate is expected to contain the following files:

• ELF file
• HEX file
• jobinfo.json

The ELF/HEX file should represent the AUT that is flashed onto the device. Squish requires that the AUT is built with Device Link enabled. See Making your QUL AUT testable, otherwise Squish can not hooking up the AUT.

The jobinfo.json file specifies the information required for flashing and running the AUT on a particular device. Vendor-specific examples are available in jobinfo.json reference.

Flashing and Running the AUT

After the test crate is ready, create an MCU test suite in Squish IDE, select the target device from the device list, and click Flash MCU Device to select and flash the test crate.

After flashing completes, the AUT is ready for Record and Replay. For the Desktop AUT setup flow, see Setting up a Desktop AUT.

For a full walkthrough of creating and recording tests, see Creating a Test Suite.

Reference

Advanced MCU tool configuration

Updating MCU tools and drivers with squishrunner

You can also update the MCU tool paths with the squishrunner command. This approach requires a currently running squishserver process.

The current configuration can be viewed with the following command:

$ ./squishrunner --info mcuSettings
St-Link     Programmer      /usr/local/st/stm32cubeclt_1.18.0/STM32CubeProgrammer/bin/STM32_Programmer_CLI
St-Link     GDBServer       /usr/local/st/stm32cubeclt_1.18.0/STLink-gdb-server/bin/ST-LINK_gdbserver
NXP         LinkServer      /usr/local/LinkServer_25.7.33
Esp         EnvScriptPath   /usr/local/esp/esp-idf/export.sh
Infineon    FlashUtility    /usr/local/openocd-5.7.0.3672-linux/openocd

The configuration can be changed through squishrunner with the --config command.

$ ./squishrunner --config mcuSettings <vendor>:<tool>=<value>

These vendor/tool settings are supported:

• St-Link:GDBServer
• St-Link:Programmer
• NXP:LinkServer
• Esp:EnvScriptPath
• Infineon:FlashUtility

For example:

$ ./squishrunner --config mcuSettings NXP:LinkServer=/usr/local/LinkServer_25.7.33

Updating locations of MCU tools and drivers in qul.ini

You can edit the qul.ini file to update, add, or remove MCU tool paths. This file is located in the Squish User Settings ver1/ Directory.

The following is an example qul.ini file. On Windows, backslashes must be escaped with a preceding backslash.

[St-Link]
GDBServer=C:\\MCUTools\\STM\\STLink-gdb-server\\bin\\ST-LINK_gdbserver.exe
Programmer=C:\\MCUTools\\STM\\STM32CubeProgrammer\\bin\\STM32_Programmer_CLI.exe

[LinkServer]
InstallPath=C:\\MCUTools\\NXP\\LinkServer

[Esp]
EnvScriptPath=C:\\MCUTools\\Espressif\\frameworks\\esp-idf-v5.3.1\\export.bat

[Infineon]
FlashUtility=C:\\MCUTools\\Infineon\\Auto Flash Utility 1.4

jobinfo.json Reference

{
    "deviceBaudRate": 115200,
    "deviceType": "mimxrt1050-evk",
    "flashInfo": {
        "chipName": "MIMXRT1052xxxxB",
        "connectScript": "RT1050_connect.scp",
        "partInfoDirectory": "cmake"
    },
    "elf": "awesome-aut.elf",
    "hex": "awesome-aut.hex"
}

{
    "deviceBaudRate": 115200,
    "deviceType": "stm32h750b-discovery",
    "flashInfo": {
        "externalLoader": "MT25TL01G_STM32H750B-DISCO.stldr"
    },
    "elf": "awesome-aut.elf",
    "hex": "awesome-aut.hex"
}

{
    "extra_esptool_args": {
        "chip": "esp32s2"
    }
}

{
    "deviceBaudRate": 115200,
    "flasherInfo": {
        "write_flash_args": [
            "--flash_mode",
            "dio",
            "--flash_size",
            "16MB",
            "--flash_freq",
            "80m"
        ],
        "flash_settings": {
            "flash_mode": "dio",
            "flash_size": "16MB",
            "flash_freq": "80m"
        },
        "flash_files": {
            "0x0": "bootloader/bootloader.bin",
            "0x10000": "qt_for_mcus_app.bin",
            "0x8000": "partition_table/partition-table.bin"
        },
        "bootloader": {
            "offset": "0x0",
            "file": "bootloader/bootloader.bin",
            "encrypted": "false"
        },
        "app": {
            "offset": "0x10000",
            "file": "qt_for_mcus_app.bin",
            "encrypted": "false"
        },
        "partition-table": {
            "offset": "0x8000",
            "file": "partition_table/partition-table.bin",
            "encrypted": "false"
        },
        "extra_esptool_args": {
            "after": "hard_reset",
            "before": "default_reset",
            "stub": true,
            "chip": "esp32s3"
        }
    }
}

{
    "deviceBaudRate": 115200,
    "deviceType": "tviic2d4mlite",
    "flashInfo": {
        "targetConfig": "traveo2_c2d_4m.cfg"
    },
    "elf": "awesome-aut.elf",
    "hex": "awesome-aut.hex"
}