Create a Crank image | ConnectCore 8X

Digi Embedded Yocto provides integrated support for Crank Storyboard software:

Storyboard Engine. A recipe installs the software to build firmware ready for your device.
Storyboard applications. A recipe adds your application to the firmware and launch it at boot time.
Crank image and update package. Two recipes to create images and update packages with Storyboard Engine and applications.

Add Crank software to your image

With Digi Embedded Yocto, you can:

Build the Crank image, dey-image-crank, or update package, dey-image-crank-swu, that Digi Embedded Yocto offers with your Storyboard application as a starting point to creating images with Crank software.
Or add the Storyboard Engine and your applications to your own image.

To add Storyboard software you must:

1. Add the Storyboard Engine to your image
2. Add Storyboard applications to your image
3. Build your firmware

1. Add the Storyboard Engine to your image

Download and install the Storyboard software. See https://info.cranksoftware.com/free-trial.

Create a tarball with engines.

Go to the Storyboard_Engine directory inside the Storyboard software installation path:
```
$ cd <storyboard_installation_path>/Storyboard_Engine
```

Compress the available engines inside crank-sbengine-7.2.tar.gz:

$ dir="$(printf '%s' *)"; tar -C "${dir}" -czvf crank-sbengine-7.2.tar.gz --transform 's,^,crank-sbengine-7.2/,' $(ls -A "${dir}")
dir="$(find . -maxdepth 1 -type d -name '[^.]?*' -printf %f -quit)"; tar -C "${dir}" -czvf crank-sbengine-7.2.tar.gz --transform 's,^,crank-sbengine-7.2/,' $(ls -A "${dir}")

Get the sha256 of the generated crank-sbengine-7.2.tar.gz:
```
$ sha256sum crank-sbengine-7.2.tar.gz
```

Configure the tarball path and sha256. Edit your conf/local.conf to specify where the tarball you have just created is located in your file system and its sha256:
```
CRANK_ENGINE_TARBALL_PATH = "file:///path/to/storyboard/engine/tarball/crank-sbengine-7.2.tar.gz"
CRANK_ENGINE_TARBALL_SHA256 = "<crank-sbengine-7.2.tar.gz_sha256>"
```
The crank-sbengine_7.2.bb selects the required engine inside the tarball and installs it.
If you have a recipe to generate your own image, you can integrate the Storyboard Engine without modifying it from your project configuration. This step is not required to build the Digi Embedded Yocto offered image dey-image-crank.

Edit your project’s conf/local.conf file and add this package to the list of packages to install:
```
IMAGE_INSTALL:append = " crank-sbengine"
```
Note the required white space when appending a value to an array variable using the :append override syntax.

2. Add Storyboard applications to your image

You can include your Storyboard applications using the Crank support already included in Digi Embedded Yocto.

The crank-demos_7.2.bb recipe installs the application and configures it to launch on boot. You can use crank_demos-7.2.bb as a reference to implement your own recipe or configure it to add your application to the firmware.

To add your Storyboard application using crank_demos-7.2.bb recipe, follow these steps:

Export your application or applications using Storyboard Designer. See Storyboard Resource Export Configuration Editor.

Compress your applications in a tarball called crank_demos-7.2.tar.gz. Each application must be inside each own directory and all of them inside another called crank_demos-7.2. For example, a valid structure is:

crank_demos-7.2.tar.gz
    |
    + -- crank_demos-7.2/
          |
          + -- App1/
          |
          + -- App2/
          |
          + -- App3/

Configure the required Storyboard application parameters. Edit your conf/local.conf to set the following parameters:
- CRANK_DEMOS_TARBALL_PATH: Absolute path to your Storyboard applications tarball, crank_demos-7.2.tar.gz.
  
  CRANK_DEMOS_TARBALL_PATH = "file:///path/to/storyboard/applications/tarball/crank_demos-7.2.tar.gz"
- CRANK_DEMOS_TARBALL_SHA256: Sha256 of the Storyboard applications tarball. Get its sha256 by executing:
  
  $ sha256sum crank-demos-7.2.tar.gz
  
  CRANK_DEMOS_TARBALL_SHA256 = "<crank_demos-7.2.tar.gz_sha256>"
- CRANK_DEMO_PATH: Path to the *.gapp file in the device to launch on boot. The recipe installs applications inside /usr/data/crank/apps each one in its directory. For example, for App1/app1.gapp:
  
  CRANK_DEMO_PATH = "${datadir}/crank/apps/App1/app1.gapp"
- CRANK_DEMO_OPTIONS: Storyboard engine options required to launch the application in CRANK_DEMO_PATH. See Storyboard Engine Plugin Options for more information. For example:
  
  CRANK_DEMO_OPTIONS = "-orender_mgr,multisample=0"
Add your the Storyboard application package to your image.

Edit your project’s conf/local.conf file and add the package to the list of packages to install. For example, to add the Crank demo:
```
IMAGE_INSTALL:append = " crank-demos"
```
Note the required white space when appending a value to an array variable using the :append override syntax.

3. Build your firmware

Once all these parameters are configured, you can build the image or a software update package.

Digi Embedded Yocto provides two recipes to build firmware with Storyboard support:

The dey-image-crank.bb creates the images with the configured Storyboard Engine and applications.
```
$ bitbake dey-image-crank
```
See Build images and Update firmware.
The dey-image-crank-swu.bb generates the corresponding software update package.
```
$ bitbake dey-image-crank-swu
```
See Build a software update package and Update firmware using SWU packages.

You can use these recipes or your own ones to create your firmware.