2.9. Build Your Own Image

2.9.1. Introduction

Note

You will need access to a Ubuntu 14.04 Linux computer with more than 4GB RAM and at least 64GB of available disk. Other Linux distributions may work, but Rigado tests against Ubuntu 14.04.

The Rigado Vesta Gateway is available from Distributors with a “Developer Image” pre-installed. Learn more about the “Developer Image” on the Out of Box page. Since the pre-loaded image may not include an application, library, or kernel feature required for your project, you may need to build your own image.

Other reasons to build your own image:

  • You can trim the unneeded packages from the build to reduce image size. Smaller image sizes reduce costs, especially if using a cellular network when deploying updates with DeviceOps.
  • You can trim the unneeded packages from the build to reduce exposure to security risks.
  • You can create updates to address security vulnerabilities to deploy with DeviceOps.

This process uses a popular build system called Yocto which is supported by excellent documentation.

Warning

You are responsible to maintain the security of your deployed gateway software. Rigado provides tools to help in this process, but does not provide security updates to your deployed gateways for you.

2.9.2. Rigado Vesta Gateway BSP

The Rigado Vesta Gateway Board Support Package (BSP) can be recreated from source code using the Yocto Build System. Please note that it will take 3 or more hours to build the “Developer Image”. This will greatly depend on the build machine being used to create the “Developer Image”. After the initial build, only the changes made to the build recipes will need to be built resulting in a much shorter build time. During the build, expect to see various warning messages in yellow text being displayed. This is okay. If an error occurs during the build process, the build will come to a halt and error messages in red will be displayed on the screen with the nature of the error. Upon successfully completion of the build, a short task summary will be displayed indicating the build succeeded. It will look something like the following:

NOTE: Tasks Summary: Attempted 4334 tasks of which 4326 didn't need to be rerun and all succeeded.

To get started follow the instructions outlined in the README.rst in the link below:

Vesta-Board-Support-Package.

For deploying the images created by the Yocto Build System to your gateway, please see one of the links below:

  • For development with a USB cable
  • At scale to your fleet of already deployed gateways using DeviceOps Rollout Management (login required).

2.9.3. Building Your Own Packages

While the “Developer Image” provided in the Rigado Gateway BSP is meant to include the most commonly asked for packages, you will want to add packages, remove packages or even create your own custom images as well. For customizing your image please refer to the Yocto Development Manual under the section header ‘Customizing Images’ as there are several different ways to create a custom image. For example, let’s say you wanted to use the “Developer Image” but also include mysql for python for testing without creating your own Yocto layer. Referring to the Yocto Development Manual under the heading ‘Customizing Image Using local.conf’, from your build directory you would simply open the file conf/local.conf and append the following line to the end of that file:

IMAGE_INSTALL_append = " mysql-python"

then rerun the command

# bitbake vesta-image-developer

As you continue developing your own custom package, the need will arise to compile your own source code. The Yocto Project Software Development Kit(SDK) Developer’s Guide also has step by step instructions on how to to do this. This guide also covers things like how to build the SDK toolchain, creating Autotools- and Makefile-based projects, and how to develop applications using Eclipse.

2.9.4. Creating a Custom Yocto Layer

Warning

You are responsible for taking the necessary security steps as needed.

Creating your own Yocto Layer will give you more control and flexibility on what is installed in the final image. The Rigado Vesta Gateway BSP comes with two images: vesta-image-developer and vesta-image-minimal. The intent of the vesta-image-developer image is to install the most commonly-requested packages on the Rigado Gateway. This allows the customer to quickly evaluate and prove out a concept with minimal effort. The intent of the vesta-image-minimal image is to keep the image small and create an image that a customer might build from.

The goal of this tutorial is to demonstrate how a customer may build from vesta-image-minimal and add those additional packages that are relevant to their specific application. In this tutorial we show how to create a new layer based off of vesta-image-minimal which then includes the bluez5 package.

To begin you will need to have completed the instructions in the README.rst in the Vesta-Board-Support-Package.

Note

To reduce build time, replace bitbake vesta-image-developer with bitbake vesta-image-minimal in the Vesta-Board-Support-Package instructions.

Once you have successfully built either vesta-image-developer or vesta-image-minimal, you will have the environment needed to be able to create a custom layer. If you take a look inside the vesta-gateway-bsp/sources directory, you will see the many different layers used in building the final images. In Yocto, layers can be identified by the meta- prefix.

Note

For more information on Yocto layers please see Yocto Layers. This is not required reading for this tutorial, but it is recommended.

Following the general instructions in the subsection “Creating Your Own Layer” from the Yocto Layers document linked above, the following steps describe how to create a meta-vesta-custom Yocto layer:

  1. Create the layer and conf folder needed inside of the the folder vesta-gateway-bsp/sources.

    user@ubuntu:~/vesta-gateway-bsp/sources# mkdir -p meta-vesta-custom/conf
    
  2. Create the file layer.conf inside the folder vesta-gateway-bsp/sources/meta-vesta-custom/conf and add the following code:

    # We have a conf and classes directory, add to BBPATH
    BBPATH .= ":${LAYERDIR}"
    
    # We have recipes-* directories, add to BBFILES
    BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
               ${LAYERDIR}/recipes-*/*/*.bbappend"
    
    BBFILE_COLLECTIONS += "vesta-custom"
    BBFILE_PATTERN_vesta-custom = "^${LAYERDIR}/"
    BBFILE_PRIORITY_vesta-custom = "7"
    LAYERVERSION_vesta-custom = "1"
    

    The meta-vesta-custom folder structure inside of the vesta-gateway-bsp/sources folder should look like this:

    meta-vesta-custom
    └── conf
        └── layer.conf
    

Now that you have your layer, you are ready to create an image recipe to include bluez on top of vesta-image-minimal. Recipes (.bb files) are fundamental components in the Yocto Project environment. Each software component built by the OpenEmbedded build system requires a recipe to define the component.

Note

For more information on creating recipes, see the Yocto Recipes subsection called Writing a New Recipe.

Next, add the recipe vesta-custom-image to include vesta-image-minimal along with the bluez recipes to your vesta-custom-image using the following steps:

  1. Create the following folder structure to hold the vesta-custom-image recipe:

    user@ubuntu:~/vesta-gateway-bsp/sources# mkdir -p meta-vesta-custom/recipes-vesta-custom/images
    
  2. Create a recipe file inside of meta-vesta-custom/recipes-vesta-custom/images called vesta-image-custom.bb and add the following code:

    require recipes-vesta/images/vesta-image-minimal.bb
    
    IMAGE_INSTALL_append += " \
    bluez5 \
    "
    

    Once completed, the meta-vesta-custom folder structure inside of the vesta-gateway-bsp/sources folder should look like this:

    meta-vesta-custom/
    ├── conf
    │   └── layer.conf
    └── recipes-vesta-custom
        └── images
            └── vesta-image-custom.bb
    

The next step is to enable your custom layer so that it will be used by the Yocto build system:

  1. Open vesta-gateway-bsp/build/conf/bblayers.conf and append your layer to the end of the BBLAYERS section by adding the line:

    ${BSPDIR}/sources/meta-vesta-custom \
    

    The vesta-gateway-bsp/build/conf/bblayers.conf should look something like this:

    POKY_BBLAYERS_CONF_VERSION = "2"
    
    BBPATH = "${TOPDIR}"
    BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"
    
    BBFILES ?= ""
    BBLAYERS = " \
      ${BSPDIR}/sources/poky/meta \
      ${BSPDIR}/sources/poky/meta-poky \
      \
      ${BSPDIR}/sources/meta-openembedded/meta-oe \
      ${BSPDIR}/sources/meta-openembedded/meta-multimedia \
      ${BSPDIR}/sources/meta-openembedded/meta-networking \
      ${BSPDIR}/sources/meta-openembedded/meta-python \
      \
      ${BSPDIR}/sources/meta-freescale \
      ${BSPDIR}/sources/meta-freescale-3rdparty \
      ${BSPDIR}/sources/meta-freescale-distro \
      \
      ${BSPDIR}/sources/meta-java \
      ${BSPDIR}/sources/meta-swupdate \
      ${BSPDIR}/sources/meta-vesta \
      \
      ${BSPDIR}/sources/meta-nodejs \
      ${BSPDIR}/sources/meta-nodejs-contrib \
      ${BSPDIR}/sources/meta-openembedded/meta-webserver \
      \
      ${BSPDIR}/sources/meta-vesta-custom \
    "
    

To build your new custom image, run the following command from the vesta-gateway-bsp/build directory:

user@ubuntu:~/vesta-gateway-bsp/build# bitbake vesta-image-custom

Once the build has finished, you will find your custom image in the folder tmp/deploy/images/vesta-general named vesta-image-custom-vesta-general.tar.bz2. To install your new image on the Rigado Gateway follow the instruction outlined in Installing a Development Build using USB.

2.9.5. Creating a Custom Yocto Recipe

In this tutorial, we will expand on our meta-vesta-custom layer from the Creating a Custom Yocto Layer section above and create a recipe to incorporate the c-button-led source code hosted on https://git.rigado.com/VestaExamples/c-button-led. Once you have completed this tutorial, you will have a custom image based off of the vesta-image-minimal image, in addition to the bluez package and an led-test application for exercising the user button and user LED. This tutorial does require that you have successfully completed the Creating a Custom Yocto Layer section above. Before you begin, your meta-vesta-custom folder structure should look like the following:

meta-vesta-custom/
├── conf
│   └── layer.conf
└── recipes-vesta-custom
    └── images
        └── vesta-image-custom.bb

The first step is to decide the proper place in the meta-vesta-custom layer where the new recipe should be placed. Referencing the different subdivisions in the Yocto Metadata section, the folder recipes-extended/ is an appropriate spot for our led-test recipe. According to the documentation, this directory contains non-essential applications that add features compared to the alternatives in core.

To create the appropriate folders, execute the following command from the directory vesta-gateway-bsp/sources/meta-vesta-custom:

user@ubuntu:~/vesta-gateway-bsp/sources/meta-vesta-custom# mkdir -p recipes-extended/led-test

Your folder structure should look like the following:

meta-vesta-custom/
├── conf
│   └── layer.conf
├── recipes-extended
│   └── led-test
└── recipes-vesta-custom
    └── images
        └── vesta-image-custom.bb

Next, in the meta-vesta-custom/recipes-extended/led-test folder, create a recipe file named led-test.bb and copy the following contents into it. These are the Yocto bitbake instructions used to compile and install the led-test application.

# Copyright (C) 2016 Rigado
SUMMARY = "led-test application that demos user LED and button"
LICENSE = "CLOSED"

SRCREV="da41f9f8bd4649ea3106720194fef06ee6656184"

SRC_URI = "git://git.rigado.com/VestaExamples/c-button-led.git;protocol=https"

S = "${WORKDIR}/git"

do_compile() {
    ${CC} ${LDFLAGS} led_test.c gpio-utils.c -o led-test
}

do_install() {
    install -d ${D}/usr/bin
    install -m 0755 led-test ${D}/usr/bin
}

COMPATIBLE_MACHINE = "(vesta|imx6ul)"

Listed below is a brief description of what each of these variables mean. For more information, search the Yocto documentation for a more detailed explanation of what each variable does and the different functions they can provide.

SUMMARY
The short (72 characters or less) summary of the binary package for packaging systems such as opkg, rpm or dpkg.
LICENSE
The list of source licenses for the recipe.
SRC_URI
The list of source files - local or remote.
SRC_REV
The commit id of the source code used to build the package.
S
The location in the Build Directory where unpacked recipe source code resides.
do_compile
Compiles the source code. The default behavior is to run a makefile if present. However, in this example the source code does not contain a proper makefile for the Yocto build system as it was designed to be compiled directly on the Gateway. Therefore we will override the do_compile with the proper commands to compile the application.
do_install
Copies files that are to be packaged into the holding area ${D}.
D
The location in the Build Directory where components are installed by the do_install task.
COMPATIBLE_MACHINE
A regular expression that resolves to one or more target machines with which a recipe is compatible.

The next step is to include the led-test recipe into our vesta-image-custom image. To do this, modify the file meta-vesta-custom/recipes-vesta-custom/images/vesta-image-custom.bb and append led-test to the bottom of the IMAGE_INSTALL_append variable. The vesta-image-custom.bb file should contain the recipe bluez from before and the newly added recipe called led-test.

require recipes-vesta/images/vesta-image-minimal.bb

IMAGE_INSTALL_append += " \
bluez5 \
led-test \
"

To build the updated vesta-image-custom image, run the following command from the vesta-gateway-bsp/build directory:

user@ubuntu:~/vesta-gateway-bsp/build# bitbake vesta-image-custom

Once the build has finished, you can find your custom image in the folder tmp/deploy/images/vesta-general named vesta-image-custom-vesta-general.tar.bz2. To install this new image on the Rigado Gateway, follow the instruction outlined in Installing a Development Build using USB. Now that your vesta-custom-image is installed on the Gateway, log in to the Gateway using one of the methods describe in the section Logging In. Once you have successfully logged in, run the following command to run the led-test application on the Gateway:

root@080030717-00055:~# led-test

Once the application is running, each time you press the user button, the user LED light will change the LED pattern.

2.9.6. Modify a Recipe Using a .bbappend File

According to the Yocto documentation, a Yocto bbappend file allows your layer to make additions or changes to the content of another layer’s recipe without having to copy the other recipe into your layer. Your .bbappend file resides in your layer, while the main .bb recipe file to which you are appending Metadata resides in a different layer.

In this tutorial, we will expand on our Creating a Custom Yocto Recipe section above and create a .bbappend file to modify the rigtools Metadata recipe that resides in the meta-vesta layer. For this example, we will use a .bbappend file to build in an older version of rigtools, version 2.0.0, then what is in the current release of meta-vesta. The current recipe for rigtools resides in the folder sources/meta-vesta/recipes-core/rigtools. There are two files in this folder rigtools.bb and rigtools.inc. The file rigtools.inc contains the instructions on how and where to fetch rigtools from and then what files to install into the Yocto build. The file rigtools.bb contains the SRCREV and SRCBRANCH variables that need to be overridden. The SRCREV variable specifies which commit id to use from the rigtools repository. The SRCBRANCH variable specifies which branch from the rigtools repository to pull from. In order to use the an older rigtools version, we will create a bbappend file to override SRCREV and SRCBRANCH variables. Follow the instructions below to create a vesta-image-custom build that contains rigtools v2.0.0.

Currently the directory structure of meta-vesta-custom should look like this:

meta-vesta-custom/
├── conf
│   └── layer.conf
├── recipes-extended
│   └── led-test
│       └── led-test.bb
└── recipes-vesta-custom
    └── images
        └── vesta-image-custom.bb

The first step is to create the necessary file and folder structure for the bbappend file.

user@ubuntu:~/vesta-gateway-bsp/sources/meta-vesta-custom# mkdir -p recipes-core/rigtools
user@ubuntu:~/vesta-gateway-bsp/sources/meta-vesta-custom# touch recipes-core/rigtools/rigtools.bbappend

Your folder structure should now look like this:

meta-vesta-custom/
├── conf
│   └── layer.conf
├── recipes-core
│   └── rigtools
│       └── rigtools.bbappend
├── recipes-extended
│   └── led-test
│       └── led-test.bb
└── recipes-vesta-custom
    └── images
        └── vesta-image-custom.bb

Next edit the rigtools.bbappend file with the correct SRCBRANCH and SRCREV information. These values can be obtained from https://git.rigado.com/vesta/rigtools/tree/v2.0.0. Remember the SRCBRANCH is the branch name and SRCREV is the commit id. Add the following two lines to the rigtools.bbappend file:

SRCREV = "313aef4435f7a03cfde79c2e480f3768d195e284"
SRCBRANCH ?= "v2.0.0"

Now that the appropriate bbappend file has been created, build the updated vesta-image-custom image by running the following command from the vesta-gateway-bsp/build directory:

user@ubuntu:~/vesta-gateway-bsp/build# bitbake vesta-image-custom

Once the build has finished, you can find your custom image in the folder tmp/deploy/images/vesta-general named vesta-image-custom-vesta-general.tar.bz2. To install this new image on the Rigado Gateway, follow the instruction outlined in Installing a Development Build using USB. Now that your vesta-custom-image is installed on the Gateway, log in to the Gateway using one of the methods describe in the section Logging In. Once you have successfully logged in, run the following command to verify that the current version of rigtools is correct:

root@080030717-00055:~# rigtools -V
Version: 2.0.0