Create an NXP MCUXpresso IDE project

This topic offers step-by-step instructions to create an NXP MCUXpresso IDE project, and integrate your application and platform sources.

You'll need the MCUXpresso SDK version 2.12.1 or newer that includes both the MCUXpresso IDE and ARM GCC toolchains. You can either use the SDK offered by Qt Online Installer, or download the SDK by yourself.

If you want to build the SDK yourself, install the following components:

  • All toolchains (this ensures that both ARM GCC and MCUXpresso files are included)
  • FreeRTOS
  • VG-Lite GPU Library

Create a new project

Extract the SDK to a directory of your choice, and follow these instructions:

  1. Launch MCUXpresso IDE and install the downloaded SDK:
    • Ensure that you can see the SDK view by selecting Window > Show View > Installed SDKs
    • Go to Installed SDKs.
    • Right-click on the view and select Import folder.... If you have the SDK as an archive, you can also choose Import archive....
    • Select the folder/archive and click Open to import the SDK into the IDE.
  2. Create a new project for i.MX RT1170 EVKB using File > New > Create a new C/C++ Project.
    • Select evkbmimxrt1170 board and click Next.
    • In the next screen, select MIMXRT1176DVMAA device package. The project should have the following settings:
      • Cores: cm7 core is set to Standalone Role.
      • Board: Default board files
      • Project Type: C++ Project
      • Project Options: SDK Debug Console is set to UART. Both Copy sources and Import other files are selected.

      Select also the components on the following list:

      • Operating Systems
        1. FreeRTOS kernel
      • Drivers
        1. anatop_ai
        2. clock
        3. common
        4. dcdc_soc
        5. elcdif
        6. gpio
        7. i2c
        8. iomuxc
        9. lcdifv2
        10. lpuart
        11. memory
        12. mipi_dsi
        13. nic301
        14. pmu
        15. pxp
        16. soc_mipi_csi2rx
        17. xip_device
      • CMSIS Include
        1. CMSIS_Include_CM
        2. MIMXRT1176_CMSIS
        3. MIMXRT1176_system
      • Utilities
        1. assert
        2. debug_console
        3. lpuart_adapter
        4. serial_manager
        5. serial_manager_uart
      • Board Components
        1. display-hx8394
        2. display-rm68191
        3. display-rm68200
        4. xip_board
        5. xmcd
      • Abstraction Layer
        1. dc-fb-common
        2. dc-fb-elcdif
        3. dc-fb-lcdifv2
        4. display-common
      • Software Components
        1. display-mipi-dsi-cmd
        2. lists
        3. video-common
      • Project Template
        1. Board Support > SDK Project Template > evkbmimxrt1170
      • Other
        1. Device > Startup > MIMXRT1176_startup

      Click Next to proceed to the next screen.

    • In Advanced project settings change the following settings:
      • Set Floating Point type: FPv5-D16 (Hard ABI)
      • Language standard: GNU C++14 (-std=gnu++14)

      Click Finish to complete the project setup.

Configure the pins and import extra SDK components

  1. Configure the NXP i.MX RT1170 pins using the ConfigTools > Pins option. For more information, refer to Configure NXP i.MX RT1170 pins.
  2. Import extra SDK components:
    • Right-click the project and select Import.
    • Select File System.
    • Add <SDK_PATH>/components/gt911 for the From directory field and select fsl_gt911.h/*.c files.
    • Add <PROJECT_NAME>/gt911 for the Into folder field and click Finish.
    • Import the following directories (including the files and subdirectories in them) from <SDK_PATH>/middleware/vglite into <PROJECT_NAME>/vglite:
      • inc
      • VGLite
      • VGLiteKernel
    • Import startup_MIMXRT1176_cm7.S from <SDK_PATH>/devices/MIMXRT1176/gcc into <PROJECT_NAME>/startup. Remove startup/startup_mimxrt1176_cm7.c/.cpp from the project.

Export the platform sources

  1. Run the following command to export the platform sources:
    export QUL_ROOT=/path/to/QtMCUs/2.7.1
    $QUL_ROOT/bin/qmlprojectexporter --platform-metadata $QUL_ROOT/lib/QulPlatformTargets_mimxrt1170-evkb-freertos_32bpp_Linux_armgcc-export.json --outdir <DESTINATION_FOLDER> --project-type cmake --no-export-qml
    set QUL_ROOT=C:\path\to\QtMCUs\2.7.1
    %QUL_ROOT%\bin\qmlprojectexporter.exe --platform-metadata %QUL_ROOT%\lib\QulPlatformTargets_mimxrt1170-evkb-freertos_32bpp_Windows_armgcc-export.json --outdir <DESTINATION_FOLDER> --project-type cmake --no-export-qml
  2. Import the exported platform sources into your project:
    • Create a new folder named platform under the project.
    • Right-click on the folder name and select Import -> File System.
    • Browse the platform sources folder in the Import dialog.
    • Select all files and folders except FreeRTOSConfig.h, which is already generated by the IDE.
    • Open platform/boards/nxp/mimxrt1170-evkb-freertos/platform_config.h and comment out #define QUL_ENABLE_PERFORMANCE_LOGGING to disable performance logging.

    Note: To enable performance logging, you must have #define INCLUDE_uxTaskGetStackHighWaterMark 1 in the FreeRTOSConfig.h. You must also define QUL_STACK_SIZE with a value that matches the stack size of Qt Quick Ultralite application task (set to 32768 by default).

    As of Qt Quick Ultralite 2.7.1 platform sources expect the following definitions to be defined:


    Either add these definitions or replace them in platform/boards/nxp/mimxrt1170-evkb-freertos/platform_irq.c and platform/boards/nxp/mimxrt1170-evkb-freertos/platform_touch.cpp.

Develop the application backend

  1. Create UI communicator struct

    The backend enables the application's UI to communicate with the platform and get the required information from the hardware. In this case, the communicator gets the status of the on-board LED. The following diagram describes the workflow between the two components:

    1. Right-click the source folder in the Project Explorer and select New > Class.
    2. Add UICommunicator to the Class name field. Rename the Header and Source to uicommunicator.h and uicommunicator.cpp respectively, and click Finish.
    3. Open uicommunicator.h and modify it to look like the following:
      #ifndef UICOMMUNICATOR_H
      #define UICOMMUNICATOR_H
      #include <qul/singleton.h>
      #include <qul/property.h>
      #include <qul/eventqueue.h>
      struct UICommunicator : public Qul::Singleton<UICommunicator>
          friend struct Qul::Singleton<UICommunicator>;
          enum Command { LED1State };
          Qul::Property<bool> led1Status;
          void sendFromUI(Command command, bool commandData);
          void receiveToUI(Command command, bool commandData);
          UICommunicator(const UICommunicator &);
          UICommunicator &operator=(const UICommunicator &);
      struct CommandEvent
          UICommunicator::Command command;
          bool commandData;
      class CommandEventQueue : public Qul::EventQueue<struct CommandEvent, Qul::EventQueueOverrunPolicy_Discard, 10>
          void onEvent(const CommandEvent &commandEvent);
      namespace UI {
      void sendToThread(bool led1Data);
      #endif // UICOMMUNICATOR_H

      The header declares the UICommunicator struct, which inherits Qul::Singleton, enabling easy integration with UI code. For more information, refer to Singleton class reference. The header also declares the Command enumeration that defines a list of commands, and the CommandEventQueue to manage the queue. The enumeration enables communication between the UI and the application. The header also declares the led1Status property to indicate the status of the on-board LED. This property is accessible in the QML context, to determine the color of the button. The UICommunicator class also has the sendFromUI and receiveToUI functions to send and receive commands. It also has the CommandEventQueue to communicate with the UI thread in a thread-safe way. Instead of calling receiveToUI from the application thread, the the commands are added to the CommandEventQueue. The Qt Quick Ultralite thread processes the queue by calling receiveToUI.

    4. Open uicommunicator.cpp and modify it to look like the following:
      #include "uicommunicator.h"
      #include "app_thread.h"
      void UICommunicator::sendFromUI(Command command, bool commandData)
      void UICommunicator::receiveToUI(Command command, bool commandData)
          switch (command) {
          case LED1State:
      void CommandEventQueue::onEvent(const CommandEvent &commandEvent)
          UICommunicator::instance().receiveToUI(commandEvent.command, commandEvent.commandData);
      static CommandEventQueue commandEventQueue;
      void UI::sendToThread(bool led1Data)
          CommandEvent commandEvent;
          commandEvent.command = UICommunicator::LED1State;
          commandEvent.commandData = led1Data;

      The UICommunicator class initializes led1Status to false. Its sendFromUI() member function sends a boolean value indicating the LED's new state to the application thread. The receiveToUI() member function uses the command argument to determine if the property must be updated. Next, the CommandEventQueue class overrides the onEvent() function, which calls receiveToUI() on the UICommunicator instance with the command and commandData parameters. In addition, a static instance of CommandEventQueue is created, which is used by the UI::sendToThread() function to post events. UI::sendToThread() constructs a CommandEvent from the given boolean value and adds it to the commandEventQueue for processing. It is called from application thread when the LED's state is changed.

Export the UI sources

  1. Export the UI sources using the qmlprojectexporter tool.

    Before exporting UI sources, add the UICommunicator interface to the UI project:

    • Open path/to/YourProject.qmlproject
    • Add the following inside Project:
      InterfaceFiles {
          files: ["path/to/mcuxpresso/project/source/uicommunicator.h"]
    export QUL_ROOT=/path/to/QtMCUs/2.7.1
    export QMLPROJECT_FILE=/path/to/YourProject.qmlproject
    export BOARDDEFAULTS=$QUL_ROOT/platform/boards/nxp/mimxrt1170-evkb-freertos/cmake/BoardDefaults_32bpp.qmlprojectconfig
    $QUL_ROOT/bin/qmlprojectexporter $QMLPROJECT_FILE --platform=mimxrt1170-evkb-freertos --toolchain=GCC --boarddefaults=$BOARDDEFAULTS --outdir=$APPLICATION_EXPORT_DIR
    set QUL_ROOT=C:\path\to\QtMCUs\2.7.1
    set QMLPROJECT_FILE=C:\path\to\YourProject.qmlproject
    set BOARDDEFAULTS=%QUL_ROOT%\platform\boards\nxp\mimxrt1170-evkb-freertos\cmake\BoardDefaults_32bpp.qmlprojectconfig
    %QUL_ROOT%\bin\qmlprojectexporter.exe %QMLPROJECT_FILE% --platform=mimxrt1170-evkb-freertos --toolchain=GCC --boarddefaults=%BOARDDEFAULTS% --outdir=%APPLICATION_EXPORT_DIR%
  2. Import the UI sources into the ui_sources top-level directory:
    • Right-click on project name in Project Explorer.
    • Go to New -> Folder.
    • On the New Folder wizard, click on Advanced and select Link to alternate location.
    • Browse the <DESTINATION_FOLDER>\ui_sources folder, generated in the earlier step.
    • Click Finish.

    Note: By creating a link to the exported sources directory, changes to the UI made in Qt Design Studio get updated automatically to the project when qmlprojectexporter is run.

Configure the MCUXpresso IDE project

  1. Select your project and select File > Properties to make the following changes:
    • Select C/C++ General > Paths and Symbols > Source Location and add the following to the list:
      • ui_sources
      • platform
      • gt911
      • vglite
    • Add include paths from IDE-Import-Instructions.txt to the C++ include directories list under C/C++ General > Paths and Symbols > Includes. Check Add to all configurations and Add to all languages. For this application, add the following include directories:
      • <QUL_ROOT>/include
      • <QUL_ROOT>/src/3rdparty/qoi
      • <QUL_ROOT>/src/3rdparty/minihdlc
      • <QUL_ROOT>/src/3rdparty/nanopb
      • platform/common from workspace
      • platform/boards/nxp/mimxrt1170-evkb-freertos from workspace
      • platform/boards/nxp/mimxrt1170-evkb-freertos/display from workspace
      • gt911 from workspace
      • vglite/inc from workspace
      • vglite/VGLite/rtos from workspace
      • vglite/VGLiteKernel from workspace
      • vglite/VGLiteKernel/rtos from workspace
      • ui_sources from workspace
    • Select C/C++ General > Paths and Symbols > Symbols and add the following preprocessor definitions:
      • For all configurations and languages:
        • CPP_NO_HEAP This disables the default malloc and free implementations by introducing empty implementations in cpp_config.cpp.
        • USE_SDRAM
        • Change XIP_BOOT_HEADER_DCD_ENABLE to 1.
        • Remove __MCUXPRESSO.
      • For GNU C++
    • Select C/C++ Build > Settings > Tool Settings > MCU C++ Linker > Libraries and add the following libraries to the list:
      • QulCore_cortex-m7-hf-fpv5-d16_Linux_armgcc_MinSizeRel
      • QulMonotypeUnicodeEngineShaperDisabled_cortex-m7-hf-fpv5-d16_Linux_armgcc_MinSizeRel
      • QulMonotypeUnicode_cortex-m7-hf-fpv5-d16_Linux_armgcc_MinSizeRel
      • QulPNGDecoderLodePNG_cortex-m7-hf-fpv5-d16_Linux_armgcc_MinSizeRel
      • QulShapes_cortex-m7-hf-fpv5-d16_Linux_armgcc_MinSizeRel
      • QulCore_cortex-m7-hf-fpv5-d16_Windows_armgcc_MinSizeRel
      • QulMonotypeUnicodeEngineShaperDisabled_cortex-m7-hf-fpv5-d16_Windows_armgcc_MinSizeRel
      • QulMonotypeUnicode_cortex-m7-hf-fpv5-d16_Windows_armgcc_MinSizeRel
      • QulPNGDecoderLodePNG_cortex-m7-hf-fpv5-d16_Windows_armgcc_MinSizeRel
      • QulShapes_cortex-m7-hf-fpv5-d16_Windows_armgcc_MinSizeRel

      Note: Libraries must be in the order listed. Otherwise, the linker may complain about missing symbols due to the wrong linking order.

    • Select C/C++ Build > Settings > Tool Settings > MCU C++ Linker > Libraries and add <Qt-install-dir>/QtMCUs/<QUL-version>/lib to the list of library search paths.
    • Select C/C++ Build > Settings > Tool Settings > MCU C++ Linker > Miscellaneous > Linker flags and add -specs=nosys.specs.
    • Select C/C++ Build > Settings > Tool Settings > MCU C++ Linker > Managed Linker Script and uncheck Manage linker script, and add ../platform/boards/nxp/mimxrt1170-evkb-freertos/cmake/armgcc/MIMXRT1176xxxxx_cm7_flexspi_nor_sdram.ld to the Linker script field.
    • Select C/C++ Build > Settings > Tool Settings > MCU C++ Linker > General and uncheck the No startup or default libs option.
  2. Open source/FreeRTOSConfig.h and make the following changes:
    • configTICK_RATE_HZ 200 -> 1000
    • configMINIMAL_STACK_SIZE 90 -> 256
    • configTOTAL_HEAP_SIZE 10240 -> 512 * 1024 * 15
    • Add #define ucHeap __HeapBase
    • Comment out or remove #define xPortSysTickHandler SysTick_Handler
  3. Open source/cpp_config.cpp and make the following changes:
    • Add
      #include <FreeRTOS.h>
      #include <portable.h>
      #include <task.h>
    • Replace all malloc() and free() calls with pvPortMalloc() and vPortFree() calls respectively.

      Note: Do not rename the function definitions inside #ifdef CPP_NO_HEAP.

    • If you want, you can also replace the empty malloc() and free() implementations with calls to FreeRTOS memory allocation functions.

Finalize the application backend

  1. Open source/<project-name>.cpp and replace the contents with the following code:

    Note: Replace YOUR_UI_APP with exported UI application name.

    #include <app_thread.h>
    #include <YOUR_UI_APP.h>
    #include <qul/application.h>
    #include <qul/qul.h>
    #include <platforminterface/log.h>
    #include <FreeRTOS.h>
    #include <task.h>
    #include <board.h>
    static void Qul_Thread(void *argument);
    static void App_Thread(void *argument);
    int main()
        if (xTaskCreate(Qul_Thread, "Qul_Thread", 32768, 0, 4, 0) != pdPASS) {
            Qul::PlatformInterface::log("Task creation failed!.\r\n");
        if (xTaskCreate(App_Thread, "App_Thread", 200, 0, 4, 0) != pdPASS) {
            Qul::PlatformInterface::log("Task creation failed!.\r\n");
        // Should not reach this point
        return 1;
    static void Qul_Thread(void *argument)
        (void) argument;
        Qul::Application _qul_app;
        static struct ::YOUR_UI_APP _qul_item;
    static void App_Thread(void *argument)
    extern "C" {
    void vApplicationStackOverflowHook(TaskHandle_t xTask, signed char *pcTaskName)
        (void) xTask;
        (void) pcTaskName;
    void vApplicationMallocFailedHook(void)

    main() initializes the board and creates the following two tasks:

    • Qul_Thread to run UI
    • App_Thread to handle the LED commands, and signal UI to update the button color based on the LED status.
  2. Right-click source folder and select New > Header File. Name it as app_thread.h and add the following:
    #ifndef APP_THREAD_H_
    #define APP_THREAD_H_
    namespace App {
    void run();
    void sendToThread(bool ledStatus);
    } // namespace App
    #endif /* APP_THREAD_H_ */
  3. Right-click the source folder and select New > Source File. Name it as app_thread.cpp and add the following code:
    #include "app_thread.h"
    #include "uicommunicator.h"
    #include "board.h"
    #include <fsl_gpio.h>
    #include <FreeRTOS.h>
    #include <queue.h>
    namespace App {
    static QueueHandle_t appQueue = NULL;
    void run()
        // enable SW7/WAKE UP button interrupt
        USER_LED_INIT(0U); // initialize LED to be off
        appQueue = xQueueCreate(20, 1);
        bool ledState;
        while (true) {
            if (pdTRUE == xQueueReceive(appQueue, &ledState, portMAX_DELAY)) {
                if (ledState)
    void sendToThread(bool ledStatus)
        if (appQueue) {
            xQueueSend(appQueue, &ledStatus, 0);
    } // namespace App
    extern "C" void BOARD_USER_BUTTON_IRQ_HANDLER(void)
        bool ledStatus = 0x1 ^ GPIO_PinRead(BOARD_USER_LED_GPIO, BOARD_USER_LED_GPIO_PIN);
        if (App::appQueue)
            xQueueSendFromISR(App::appQueue, &ledStatus, NULL);

    This file defines a simple app thread and all its related functions. First, appQueue is defined to store commands that toggle the board's LED state (on or off). The App::run function is the main loop of the app_thread. It enables interrupts for the user button on the board, initializes one of the board LEDs to be off, and creates a queue for the thread. After this, the thread enters an infinite loop waiting for the commands to toggle the LED state. This status is then sent to UI (Qt Quick Ultralite) thread.

    Next, we have App::sendToThread function which posts the given led state to the appQueue. Last, there is an IRQ handler for the user button. When the button is pressed, it checks the current state of the LED and posts an inverse of that state to the appQueue.

Your application is now ready. Build and flash it to the NXP i.MX RT1170 board to test that everything works as intended.

Note: If the application does not seem to respond to touch, try pressing the SW7/WAKEUP button on the board.

Available under certain Qt licenses.
Find out more.