Storyboard Integration with MCUXpresso and NXP RT10XX EVK

To follow this tutorial, you need the following:

The folder where the package that contains this tutorial is referred to as the <PACKAGE_DIR>. The folder for the support files is based on the type of package that is installed.

<PACKAGE_DIR>/integration-support-files/<BOARD_TYPE>

Where <BOARD_TYPE> is one of RT1050, RT1060 or RT1064.

The support files folder is referred to as <SUPPORT_FILES_DIR> from this point forward.

Also, before integrating the engine into a project, reading the Storyboard documentation is advised.

The MCUXpresso IDE can be downloaded from this website. To download the product, a user account must be created on the NXP website. Once the product has been downloaded, install it on the system.

The NXP SDKs are created through the Dashboard tool and are customizable for a particular IDE toolchain and feature set. The following steps are needed to create the correct setup:

Open MCUXpresso and import the NXP SDK for the RT10xx EVK by pointing at the downloaded NXP SDK zip file. This can be done by clicking on the 'Installed NXP SDK's' tab in the MCUXpresso IDE and dragging and dropping the NXP SDK ZIP file to the view.

The SDK can also be extracted to a convenient folder to add additional files from the SDK to our project later on. This folder is referred to as <RT10xx_NXPSDK_ROOT> later in this tutorial.

Once the RT10xx EVK SDK has been installed, we are ready to configure the project. We base this on an existing sample project for simplicity:

Build the freertos_sbengine project, download the image to the board by selecting the “Debug” link in the “MCUXpresso IDE - Quick Start Panel” which is usually located in the bottom right corner of the IDE. This step is to ensure everything is installed and configured correctly before making modifications.

Copy the files contained in the <SUPPORT_FILES_DIR>/board folder to the project folder board. Click “yes” when prompted to overwrite the pin.c and pin.h files.

Additional driver files need to be added to the project to provide graphics and touchscreen support. The folder where the driver source files are located depends on the target hardware being used. For the RT1050 target hardware this folder is:

For the RT1060 hardware, this folder is:

For the RT1064 hardware, this folder is:

This folder is referred to as <SDK_DRIVER_ROOT_DIR>.

To manually configure the additional SDK drivers required, add (copy to project rather than link) the following files to the drivers folder in the project workspace:

Create a project folder called touchpanel. Copy the following files into the touchpanel folder:

To add the touchpanel include paths to the compiler include search paths, right click on the project and select “Properties”. In the properties pane, expand the “C/C++Build” tree item in the pane that is on the left-hand side of the screen. From the expanded tree item, select “Settings”.  In the settings pane on the right-hand side, expand the tree item “MCU C Compiler” and select ”Includes”.

Add the following folders to the “Include paths (-I)” pane using the icon with a “+” symbol in it:

“${workspace_loc:/${ProjName}/touchpanel}”

Right-click on the touchpanel folder and select the menu item “Properties” from the popup menu.

From the properties dialog, select the entry “C/C++ Build” from the list on the left-hand side.  Uncheck the box marked “Exclude resource from build”.

The Storyboard Engine requires a different memory manager configuration than the default one used by FreeRTOS. To enable this, remove or delete heap_4.c from the project folder amazon-freertos/FreeRTOS/portable and add in heap_3.c which implements a FreeRTOS allocation API on top of malloc() and free() library calls.

Copy the heap_3.c file from:

and add this file to the project folder amazon-freertos/FreeRTOS/portable.

Finally create a project folder called configuration. There is a specific memory configuration file for the board that is being used. If the board is a RT1050, the memory configuration file is:

<SUPPORT_FILES_DIR>/configuration/MCUXpresso/MIMXRT1052xxxxx_flexspi_nor.ld

If the board is a RT1060, the memory configuration file is:

<SUPPORT_FILES_DIR>/configuration/MCUXpresso/MIMXRT1062xxxxx_flexspi_nor.ld

If the board is a RT1064, the memory configuration file is:

<SUPPORT_FILES_DIR>/configuration/MCUXpresso/MIMXRT1064xxxxx_flexspi_nor.ld

Copy the memory configuration file to the configuration folder in the project.

In the linker settings, switch from a managed linker configuration to using the linker file that was copied into the project. To do this, right click on the project and select “Properties”. In the properties pane expand the “C/C++Build” tree item in the pane that is on the left-hand side of the screen. From the expanded tree item, select “Settings”. In the settings pane on the right-hand side, expand the tree item “MCU C Linker” and select ”Managed Linker Script”. Uncheck the checkbox “Manage linker script” and set the following settings based on board type:

RT1050

Linker script = MIMXRT1052xxxxx_flexspi_nor.ld

Script path= ../configuration

RT1060

Linker script = MIMXRT1062xxxxx_flexspi_nor.ld

Script path= ../configuration

RT1064

Linker script = MIMXRT1064xxxxx_flexspi_nor.ld

Script path= ../configuration

At this point, a build clean and build all should be performed on the project and those operations should complete successfully.

The next step is to export an application from Storyboard Designer. This is done here because the header is needed to complete the compile once the Storyboard Engine is integrated into the project. The header for the Storyboard application is exported now for use later.

For more information on exporting a model from Storyboard Designer, read the Exporting and Running on your Embedded Target chapter in the Storyboard Designer documentation.

The C/C++ header file that is exported contains all the model definitions, scripts, fonts, and other graphical assets used by the Storyboard application in binary form. Once the target platform has been configured with Storyboard engine, display, and input support, updates to the Storyboard model can be exported to the sbengine_model.h C/C++ header file in the project directly.

Configuring the resources for export

To export for an embedded target configuration we need to create a custom resource export configuration. To do this, click on the resource export configuration editor toolbar button. It is shown in this image:

In the new editor, create a virtual filesystem configuration for the resources. This can be done by first creating a new configuration. To do this, click on the “New” button pictured below:

You can name your custom resource configuration anything you want. In this example we set options for a virtual filesystem, so we use the name “vfs” to help identify what the custom configuration was created for. In the dialog that appears, type “vfs” into the name and click on the “OK” button. After clicking on the “OK” button, the editor should look like this

Note that the default sizes for the “Font Glyph Map Width” and the “Image Map Width” are tied to the width of the application, so these values may be different.

For the purpose of this tutorial, a couple of options need to be changed. The first option is “Storage Type”. This option needs to be set to “Virtual Filesystem”.  It looks like this:

The second option to change is the “Image Export Format” option. For the purposes of deploying to this target, set this option to “Direct RGB8888”. This tells the runtime to draw images directly out of storage and not use any heap for decoding the image. When that option is set, it looks like this:

Freetype font manager setup

To use the Freetype font engine to render fonts, set the “Font Export Format” to “TTF”. It looks like this:

Storyboard bitmap font manager setup

To use the Storyboard bitmap font engine to render fonts, set the “Font Export Format” to “Bitmap”. It looks like this:

When “Bitmap” is selected as the “Font Export Format”, the number of bits to use for the alpha values representing the pixels of the glyph can be chosen. The default is 8-bits per pixel in the glyph.  The other options are 4-bits, 2-bits and 1-bit. Reducing the number of bits that are used to represent the alpha values representing the pixels of the glyph reduces the size of the glyph structures, but it also reduces the quality of the rendered font.

Once a choice has been made about the font manager to be used to render font glyphs, save the configuration and close the editor.

Exporting the model C/C++ header file

Open the export dialog by clicking on the following button in the main Designer toolbar:

The main areas to change on the dialog are to set the “Packager” setting to “Storyboard Embedded Resource Header C/C++” and the “Resource Export Configuration” dialog to “vfs”.  After changing those the dialog will look like this:

Note that if the Freetype font manager is used, the “Bitmap Fonts Header” section is disabled.

Click the “Apply” button and the “Run” button. If you are not exporting the model directly into your MCUXpresso project, you should make a note of the location of the sbengine_model.h file.

The first step to integrating the engine into the project is to copy the engine binaries to the project by doing the following:

The FreeRTOSConfig.h file in the source folder needs to have the following configuration defines changed from this:

#define configFRTOS_MEMORY_SCHEME               4
#define configUSE_TIME_SLICING                  0
#define configENABLE_BACKWARD_COMPATIBILITY     0
#define configTICK_RATE_HZ                      ((TickType_t)200)
#define configUSE_NEWLIB_REENTRANT              0

to this:

#define configFRTOS_MEMORY_SCHEME               3
#define configUSE_TIME_SLICING                  1
#define configENABLE_BACKWARD_COMPATIBILITY     1
#define configTICK_RATE_HZ                      ((TickType_t)1000)
#define configUSE_NEWLIB_REENTRANT              1

SKIP_SYSCLK_INIT
XIP_BOOT_HEADER_DCD_ENABLE=1
GRE_TARGET_OS_freertos
GRE_TARGET_CPU_cortexm7
GRE_TARGET_TOOLCHAIN_mcuxpresso
GRE_FEATURE_VFS_RESOURCES

SDK_DEBUGCONSOLE=0

SDK_DEBUGCONSOLE=1

gre
greal
sbimage
sbvfs
gre-plugin-animation
gre-plugin-ccallback
gre-plugin-poly
gre-plugin-circle
gre-plugin-timer
gre-plugin-logger
gre-plugin-sbimage-soil
render-plugin-swrender
swrender
soil
logging-util

gre
greal
sbimage
sbvfs
gre-plugin-animation
gre-plugin-lua
gre-plugin-poly
gre-plugin-circle
gre-plugin-timer
gre-plugin-logger
gre-plugin-screen-path
gre-plugin-greio
gre-plugin-sbimage-soil
render-plugin-swrender
logging-util
greio
sblua
soil
swrender
png
sbz

font-plugin-freetype
sbfreetype

font-plugin-sbfont

-mno-unaligned-access

#include “HelloWorld.h”

void sbengine_main_task(void *argument);

if (xTaskCreate(hello_task, "Hello_task", configMINIMAL_STACK_SIZE + 10, NULL, hello_task_PRIORITY, NULL) != pdPASS)

if (xTaskCreate(sbengine_main_task, "sbengine", 8192, NULL, configMAX_PRIORITIES / 2, NULL) != pdPASS)

#include "board.h"
#include "peripherals.h"

/*!
 * @brief Application entry point.
 */
int main(void)
{
	/* Init board hardware. */
	BOARD_ConfigMPU();
	BOARD_InitPins();
	BOARD_InitSemcPins();
	BOARD_InitBootPeripherals();
	BOARD_BootClockRUN();
	BOARD_InitDebugConsole();
     :

void sbengine_input_task(void *argument);#include “HelloWorld.h”

if (xTaskCreate(sbengine_input_task, "StoryboardInput", 2048, NULL, configMAX_PRIORITIES / 2, NULL) != pdPASS)
    {
        PRINTF("Task creation failed!.\r\n");
        while (1);
    }    

Deploying and debugging on the target

Build the freertos_sbengine project, download the image to the board by selecting the “Debug” link in the “MCUXpresso IDE - Quick Start Panel” which is usually located in the bottom right corner of the IDE.

After following these steps, you should be able to integrate the Storyboard engine into your RT10xx EVK project, deploy and flash it to the target.

For more information about Storyboard on the RT10xx EVK you can visit the Crank Help Center.  If you require further assistance, contact support@cranksoftware.com.

In most cases, it is not necessary to build the source to the Storyboard abstraction layer. Compiling the source to this library is only needed if there are changes being made to the OS priority settings or to the system tick rate. This appendix outlines how to build the source code of the Storyboard abstraction layer that is shipped as part of this package.

greal

This package ships with two demo applications that can be imported into Storyboard Designer.

To import these projects into Storyboard Designer, select File->Import->General->Existing Projects into Workspace. In the dialog that pops up, navigate to the “Select Root Directory” box to the folder <PACKAGE_DIR>/Demos/applications and select the two applications that are populated in the “Projects” list.

Make sure the “Copy projects into workspace” checkbox is selected and then click on “Finish”.

The projects are now in your Storyboard Designer workspace.

The table below lists a comparison of the features supported by the different configurations of the Storyboard Engine. Differences between the configurations have been highlighted in bold.

(1) Only where OpenGL hardware support is available

(2) Playback support only due to the virtual filesystem