Building a Storyboard Container

If you are evaluating Storyboard or the Torizon platform you will likely have seen our pre-built container images configured to run on the Toradex Torizon platform. After you’ve played around with the image a bit, you will likely want to build your own container. Docker is a very flexible and configurable platform so I’m going to show you what we’ve done internally for our container and you can use that as inspiration or a base for your container going forward. To begin you will require the followirng pieces:

Once you have these pieces in place you can connect your development platform and start to build your docker file. At this point, it’s assumed that you were able to successfully run our pre-built Docker container on your hardware. If you’ve haven’t done that yet I’d suggest doing that now so you can validate a working scenario on the platform before creating your own.

This is the Recipe file from the standard i.MX8 container.

ARG IMAGE_ARCH=arm64v8
FROM torizon/$IMAGE_ARCH-debian-wayland-base-vivante:buster

RUN apt-get -y update && apt-get install -y --no-install-recommends \
    apt-utils \
    libwayland-dev \
    net-tools \
    procps \
    mtdev-tools \
&& apt-mark hold dash && apt-get -y upgrade && apt-mark unhold dash \
&& apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*

RUN mkdir -p /usr/crank

COPY --chown=777 crank /usr/crank/

CMD /usr/crank/docker_sbengine.sh

It’s fairly simple, it defines the Architecture of the container and bases it off of the debian wayland image with vivante driver. The Run options define the dependencies required in the container and pull them down. Then a directory is created for the Storyboard content under /usr/crank, apply access permissions and copy the contents of a folder called “crank” into the container. Finally, we execute a script that was copied over into our new crank directory.

The content of the crank directory is as follows:

The content within crank/apps/VitalsHD/ is our medical demo which can be found in our public SVN repository. This is where you will export your own application, in the case of our recipe we require the application to be exported and copied at build time but you could just as easily configure your recipe to fetch the latest version of your application from your source control which is probably a more common configuration for production containers. The same applies to the /crank/runtimes/ runtimes directory, here we contain the version of the Storyboard runtime engine for your platform. Similar to the application directory we copy that in during build time but you could fetch this from a remote location if you so choose.

The last element we need to talk about is the script “docker_sbengine.sh”. This script contains the following content. This is where you configure the engine parameters for your board

#!/bin/bash
#Crank Software's Torizon demo

#Variable Setup
crank_dir=/usr/crank
scp_dir=$crank_dir/scp
sbengine_ext=.gapp
runtime=/usr/crank/runtimes/linux-imx8yocto-armle-opengles_2.0-wayland-obj
sb_binary=$runtime/bin/sbengine
sb_app=VitalsHD/1280x720.gapp
demo_app=$crank_dir/apps/$sb_app
sb_options='-orender_mgr,fullscreen -omtdev,device=/dev/input/event1'

#ENV Variables
export SB_PLUGINS=$runtime/plugins
export LD_LIBRARY_PATH=$runtime/lib:$LD_LIBRARY_PATH
export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libwayland-egl.so.1

#Verify that SCP directory exists, and check if .gapp file is stored in it.
#If a .gapp file exists run sbengine on this app, otherwise execute demo
launcher
scp_app=$(find /usr/crank/scp -name *.gapp -print -quit)
echo $scp_app
if [ -z $scp_app ]; then
    echo "Starting Crank Demo Application..."
    echo $sb_app    $sb_binary $sb_options $demo_app
else
    echo "Starting Storyboard SCP Application..."
    echo $scp_app    $sb_binary $sb_options $scp_app
fi

The script isn’t overly complicated but it does a few things. As I mentioned earlier you should consult the running your application section in our help center to learn more. However, I’ve highlighted the line which declares the “sb_options” variable. This is where we set up any engine parameters required to configure or tune the engine to our platform. As of right now, we are specifying the application to run in full-screen mode and use the mtdev plugin to read the touch device exposed as /dev/input/event1. This device might be enumerated as a different device depending on your system or the display that you’ve connected so you should check the devices exposed on the host system and once you’ve confirmed you have the right one add it to the script. This device will be exposed to the container from the host hardware based on the container’s run command. One common thing you might want to do is to expose the engine to receiving commands on a particular port. To do this you can leverage the SBIO over TCP functionality. So add the following option to your line which will expose tcp port number 55555.

-ogreio,channel=tcp://55555

Your sb_options line should now look like this.

sb_options='-orender_mgr,fullscreen -omtdev,device=/dev/input/event1 -ogreio,channel=tcp://55555'

You can experiment with adding other options or configurations but now we should try to build and run our container. Connect to your development hardware and copy the crank folder with your runtime, demo application and launch script to the hardware. Beside the crank directory create a file called “Dockerfile” without an extension. Add the lines from our i.MX8 docker recipe to the file, save it and close it. You can then build the container with the following docker command.

docker build -t '<dockerhub repo><image name>:<tag>' .

Once you’ve built the container you can launch it with the following command.

docker run -it --privileged -p 55555:55555 -v /home/torizon/crank/scp:/usr/crank/scp -v /dev:/dev -v /tmp:/tmp <dockerhub repo><image name>:<tag>

The -p flag will expose port 55555 within the container as port 55555 on the host machine. Finally, make sure to update the final path to your built image in the launch command.

From there you container should launch and if you want you’ll be able to send Storyboard IO events over a TCP socket connection.