Developing with Storyboard and Linux on the STM32MP15x Discovery Kit

The STM32MP157C-DK2 is a great Linux capable application processor and development kit which is a perfect embedded target host for Storyboard HMI-based products.

The Discovery Kit features an 800x480 capacitive touch screen to complement the powerful STM32MP157 Arm®-based dual Cortex®-A7 32 bits + Cortex®-M4 32 bits MPU.


The instructions for unboxing and creating the SD Card Image using STM instructions for the Starter Package can be found on the ST Microelectronics website here:

I used a Linux virtual machine for this but any supported Windows or Linux desktop environment should enable you to follow the step-by-step guide above and use the STM32CubeProgrammer tool to commission a micro SD card image.

This bootable SD Card image should launch into the ST Microelectronics out-of-box demo and run the base Wayland-based graphical environment.


The initial boot of the board may trigger some maintenance scripts and processes which will automatically redimension and expand the filesystem partitions one by one. This takes some minutes so be patient!

Once booted there is a serial console device created and available if you connect a network cable. On boot, if this is attached the board should get a DHCP address and register a default hostname.

You can SSH into the board (I prefer TeraTerm on Windows) using the hostname stm32mp1 and user root (blank password by default).


With the network link established we can take a first look around and begin to commission the board with Storyboard….

The OpenSTLinux system base image from the STM website resources used for this application note is  en.FLASH-stm32mp1-openstlinux-5-4-dunfell-mp1-20-11-12.tar.xz which was the latest available at the time of writing.

root@stm32mp1:~# uname -a

Linux stm32mp1 5.4.56 #1 SMP PREEMPT Wed Aug 5 07:59:52 UTC 2020 armv7l armv7l armv7l GNU/Linux

The filesystem is created by the STM32CubeProgrammer tool such that the ‘user’ applications are located in a separate partition on the SD Card.  This is mapped to the /usr/local tree in the root filesystem.


Step 1: Copy across the Storyboard runtime (to the target board)

Create a Crank folder under /usr/local along with a runtimes folder and apps folder where we will deploy our Storyboard applications:

root@stm32mp1:~# mkdir /usr/local/Crank

root@stm32mp1:~# mkdir /usr/local/Crank/runtimes

root@stm32mp1:~# mkdir /usr/local/Crank/apps

The Storyboard runtime for the STM32MP1 boards is linux-stmA5-armle-opengles_2.0-wayland-obj and located under the installation folder for Storyboard on the desktop.

Copy this folder and contents to /usr/local/Crank/runtimes on the target filesystem which can simply be done using a utility such as WinSCP for Windows or FileZilla.

And once copied grant the runtimes folder contents execute permissions (recursively) to keep it simple..

root@stm32mp1:~# chmod -R 0755 /usr/local/Crank/runtimes

root@stm32mp1:~# ls -la /usr/local/Crank

total 4

drwxr-xr-x 4 root root 1024 Feb  7 16:23 .

drwxr-xr-x 8 root root 1024 Feb  7 16:22 ..

drwxr-xr-x 7 root root 1024 Feb  7 16:23 apps

drwxr-xr-x 3 root root 1024 Feb  7 16:22 runtimes

Step 2: Create a launcher script for Storyboard

In the root of the Crank folder (/usr/local/Crank) on the target, we can create a script that sets up the execution environment for the Storyboard runtime and options for the application model we want to run at startup.

This is where we can use your own Storyboard application or perhaps one of the samples which ship with Storyboard. As the STM32MP157C-DK2 development board that I am using has an 800x480 LCD panel with touch screen and the processor variant features a GPU supporting OpenGL then we can use the splendid OpenGL3DModel sample which ships with Storyboard:


In this sample, we deploy the Storyboard application model and all associated assets have been exported as a GAPP file (OpenGL3DModel.gapp) and deployed to a folder OpenGL3DModel under the location /usr/local/Crank/apps



export RUNTIME_ROOT=/usr/local/Crank/runtimes/linux-stmA5-armle-opengles_2.0-wayland-obj



export SB_DEMO=1

export SB_APP=/usr/local/Crank/apps/OpenGL3DModel/OpenGL3DModel.gapp

killall sbengine

$RUNTIME_ROOT/bin/sbengine -vvvv -orender_mgr,multisample=0 $SB_APP


You can see in the command line options for sbengine we have added the -vvvv to the config. This will emit more verbose trace output to the Linux console and help us in diagnosing any issues. You can remove this trace verbosity option to minimize runtime overhead once you have everything set up and working.

Once the launcher script has been created we will again grant it execute permissions and we should be able to launch and run the application.

root@stm32mp1:~# chmod 0755 /usr/local/Crank/

root@stm32mp1:~# ls -la /usr/local/Crank

total 5

drwxr-xr-x 4 root root 1024 Feb  7 16:23 .

drwxr-xr-x 8 root root 1024 Feb  7 16:22 ..

drwxr-xr-x 7 root root 1024 Feb  7 16:23 apps

drwxr-xr-x 3 root root 1024 Feb  7 16:22 runtimes

-rwxr-xr-x 1 root root  328 Dec 18  2020

root@stm32mp1:~# cd /usr/local/Crank/

root@stm32mp1:/usr/local/Crank# ./

Step 3: Setup the board to auto-start the Storyboard application

In vanilla configuration, the filesystem is set up to load and run a demo application to show a simple desktop window and a launcher menu for various utilities and sample applications bundled with the board.

The default demo is built upon the Wayland display manager using a Weston shell and its behaviour and appearance are configured through the file /etc/xdg/weston/weston.ini.

We want to disable the launcher and also hide the bottom control panel so that Storyboard has the full-screen surface to work with.




### Crank - disable background
### Crank - disable panel

### Crank - disable launcher



# HDMI connector
# If the hdmi cable is plugged, weston uses the hdmi output (else dsi output).
# Use the command "systemctl restart weston@root" after pluging/unpluging the hdmi cable.

# DSI connector

Finally, we can modify the startup script to run our script instead of the existing Weston script.

The configuration is found in the file:


# found card
cards=`pacmd list-cards |  egrep -i 'alsa.card_name' | sed 's/ //g'| sed 's/alsa.card_name=\"//g'| sed 's/\"//g'`
for i in $cards;
        found=`echo $i | grep -n STM32MP | wc -l`
        if [ $found -eq 0  ];
                su.util-linux -l root -c 'pacmd set-card-profile $index output:analog-stereo'


Upon the next reboot, the board should automatically launch the Storyboard application specified in the script file.

root@stm32mp1:~# reboot now

Step 4: Exporting from Designer and running on the target using SCP

Once the standalone launcher is up and running we can now progress to configuring your development environment so that Storyboard GUI application changes can be deployed and run on the target board directly from Storyboard Designer using the SCP secure file transfer protocol over the SSH connection.

Create a new modified version of the launcher script which configures the interactive user environment for our default user (root) and which instead accepts as an argument ($1) the application to run rather than a hard-coded path.

This argument is passed by Storyboard automatically and now enables us to deploy and run this script created in the root of the Crank folder (/usr/local/Crank) .


# XDG_RUNTIME_DIR env var must be set so that the Wayland graphical 
# sub-system can locate the launching (root) user's specific data and 
# config plus a place to store temporary files
export XDG_RUNTIME_DIR=/run/user/0

export RUNTIME_ROOT=/usr/local/Crank/runtimes/linux-stmA5-armle-opengles_2.0-wayland-obj
export SB_DEMO=1

killall sbengine

$RUNTIME_ROOT/bin/sbengine -vvvv -orender_mgr,multisample=0 $1

Again this script needs first to be granted execute permissions before it can run and we can test that it functions correctly by manually (re-)launching the 3D Demo:

root@stm32mp1:~# chmod 0755 /usr/local/Crank/
root@stm32mp1:~# ls -la /usr/local/Crank
total 6
drwxr-xr-x 4 root root 1024 Feb  7 16:23 .
drwxr-xr-x 8 root root 1024 Feb  7 16:22 ..
drwxr-xr-x 7 root root 1024 Feb  7 16:23 apps
drwxr-xr-x 3 root root 1024 Feb  7 16:22 runtimes
-rwxr-xr-x 1 root root  328 Dec 18  2020
-rwxr-xr-x 1 root root  504 Dec 18  2020
root@stm32mp1:~# cd /usr/local/Crank/
root@stm32mp1:/usr/local/Crank# ./ apps/OpenGL3DModel/OpenGL3DModel.gapp

With a working script file we are now able to deploy the model and assets and Run the script directly from Storyboard using the Export Configuration dialog and the Post Transfer Script option:


The HMI design can be iterated then the application can be modified and run in seconds!

Was this article helpful?
0 out of 0 found this helpful