Yocto Environment for chargebyte's Linux platforms

This is a wrapper repository for chargebyte GmbH's Yocto BSP and distribution open-source layers. For problems and inquiries: https://chargebyte.com/support

Table of Contents

1. Introduction
2. Background
   2.1 Layers
   2.2 "Wrapper" Repository
3. Build with Yocto
   3.1 System Requirements
   3.2 Setting up the Yocto build environment
   3.3 Adding or removing layers
   3.4 Building an Image
   3.5 Flashing an Image
4. Appendix
   A.1 How to change kernel configurations

Introduction

This document helps you to get started with creating a Linux image based on board support packages (BSP) of EVAcharge SE, Tarragon and Charge SOM - the hardware platforms offered by chargebyte GmbH. It defines what the layers included in this Yocto Project are, and how you can use them to create a basic Linux distribution, which you can then extend by adding further packages specific to your application.

If you are new to Yocto, it is recommended to read the Yocto Overview and Concepts Manual. To get a quick introduction to Yocto, this Software Overview might be helpful. For further documentation on the Yocto Project, including information about dealing with BSP layers and working with the Yocto Project's build system BitBake, check the Yocto Project Documentation.

Background

Layers

As the Yocto Project is based on the concept of layers, the following table lists all the layers used to create a basic distribution based on chargebyte’s Linux platforms.

Layer	Description	Repository
poky	Build tool and metadata included in a reference distribution	https://git.yoctoproject.org/poky
meta-freescale	Layer containing NXP hardware support metadata	https://git.yoctoproject.org/cgit/cgit.cgi/meta-freescale
meta-openembedded	Collection of layers to supplement OE-Core with additional packages	https://github.com/openembedded/meta-openembedded
meta-security	Collection of security-related layers e.g. for TPM support	https://git.yoctoproject.org/meta-security
meta-rauc	Layer controlling and performing secure software updates for embedded Linux	https://github.com/rauc/meta-rauc
meta-qt5	Layer for Qt5 components	https://github.com/meta-qt5/meta-qt5
meta-nymea	Layer for nymea.io	https://github.com/nymea/meta-nymea
meta-chargebyte	BSP layer for EVAcharge SE, Tarragon & Charge SOM	https://github.com/chargebyte/meta-chargebyte
meta-chargebyte-distro	Distribution adaptations layer	https://github.com/chargebyte/meta-chargebyte-distro

This layering approach increases flexibility to expand your project. You can add layers, which in turn would add packages essential for the distribution you want to build. Layers are usually available as repositories. Information on how to include or remove layers will be given in Section 3.3. Note that no charging capabilities will be included in the Linux distribution created by this setup.

"Wrapper" Repository

This "wrapper" repository has been created to facilitate downloading the above-mentioned layers/repositories on your local machine. It contains a manifest file called default.xml that holds information about the repositories representing the layers needed to build a distribution, and which branches to be checked out from these repositories. The process of extracting information from the manifest file and checking out the branches of the mentioned repositories is done by using repo commands. Installation and usage of the repo utility will be explained in Section 3.2. The manifest file for this repository looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <default sync-j="4" revision="kirkstone"/>

  <!-- remote repository definitions -->
  <remote fetch="https://git.yoctoproject.org" name="yocto"/>
  <remote fetch="https://github.com/openembedded" name="oe"/>
  <remote fetch="https://github.com/chargebyte" name="chargebyte"/>
  <remote fetch="https://github.com/rauc" name="rauc"/>
  <remote fetch="https://github.com/meta-qt5" name="qt5"/>
  <remote fetch="https://github.com/nymea" name="nymea"/>

  <!-- project definitions -->
  <project remote="yocto"        revision="kirkstone"                                name="poky"                     path="source"/>
  <project remote="yocto"        revision="kirkstone"                                name="meta-freescale"           path="source/meta-freescale"/>
  <project remote="oe"           revision="kirkstone"                                name="meta-openembedded"        path="source/meta-openembedded"/>
  <project remote="yocto"        revision="kirkstone"                                name="meta-security"            path="source/meta-security"/>
  <project remote="chargebyte"   revision="kirkstone"                                name="meta-chargebyte"          path="source/meta-chargebyte"/>
  <project remote="chargebyte"   revision="kirkstone"                                name="meta-chargebyte-distro"   path="source/meta-chargebyte-distro"/>
  <project remote="rauc"         revision="2eb0d2af94c63f4bc5b52e5f7c5a36000bfd7016" name="meta-rauc"                path="source/meta-rauc"/>
  <project remote="qt5"          revision="kirkstone"                                name="meta-qt5"                 path="source/meta-qt5"/>
  <project remote="nymea"        revision="kirkstone"                                name="meta-nymea"               path="source/meta-nymea"/>
  <project remote="chargebyte"   revision="kirkstone"                                name="chargebyte-bsp"           path="chargebyte-bsp">
    <linkfile dest="build/conf" src="conf"/>
  </project>

</manifest>

The attributes revision and path represent the source branch and the destination where the branch´s content will be placed on the local machine, respectively. You can set the revision to be either a branch name, by which you can continuously receive branch updates, or a particular commit in the repository. The tag linkfile links two folders together. It has two attributes; one is src which is a folder in the repository, and the other is dest representing the destination folder on the local machine, which will always have the content of the source folder i.e., mirror it.

Apart from the manifest file, the repository also has a configuration folder. This folder contains a local.conf file which contains variables and machine configurations you can alter to affect the resulting distribution and a bblayers.conf file which gives information about the layers included for building. Adding or removing layers can be done through this file, provided that the added layer, e.g., the cloned repository, is found on the local machine in the path described in this file.

Build with Yocto

System Requirements

Some packages are required by the build host to be able to cover all build scenarios using the Yocto Project. In this section of the Yocto Reference Manual you can find some helpful instructions based on the Linux distribution you are using. If you are using a host other than Linux, this section of the Yocto Project Development Tasks Manual can help you setting up your host system for using Yocto.

Setting up the Yocto build environment

To be able to build an image with Yocto, the following setup should be followed:

1. To make use of the manifest file, you have to install repo to get your Yocto environment ready. The repo utility was originally created to ease Android development. It makes it easy to reference several Git repositories within a top-level project, which you can then clone to your local machine all at once.

mkdir ~/bin
curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

You need to also make sure that ~/bin is added to your PATH variable (Usually the directory is added automatically in Ubuntu).

echo 'export PATH="$PATH":~/bin' >> ~/.bashrc

2. Now you can use the repo tool to check out all the repositories listed in the manifest file.

mkdir yocto
cd yocto
repo init -u https://github.com/chargebyte/chargebyte-bsp -b kirkstone
repo sync

After the command repo sync is executed, you should be able to find three folders in the created yocto directory:

1. source: Where all the repositories representing the layers are cloned.
2. chargebyte-bsp: A clone of the 'wrapper' repository containing the manifest file and configurations folder.
3. build: A link to the conf folder in chargebyte-bsp

Adding or removing layers

Adding a layer can be done either:

Manually

1. Download the layer as a tarball or by cloning a repository.
2. Copy the folder where the layer is downloaded.
3. Paste it in the yocto/source folder.
4. Edit the yocto/build/conf/bblayers.conf file to include the new layer with the right path.

or Automatically

1. Edit the manifest file chargebyte-bsp/default.xml, so that it contains information about the source of the new layer
2. Issue the command repo sync. Note that all other layers will be synced as well, so any unsaved changes to your layers will be lost.
3. Edit the yocto/build/conf/bblayers.conf file to include the new layer with the right path.

You can then execute the command bitbake-layers show-layers to make sure that the new layer is now included.

To remove a layer, you can simply alter the bblayers.conf file by removing the layer path to make sure that the build system does not consider this layer while generating an image.

Building an Image

To correctly set configurations related to the hardware platforms Tarragon and EVAcharge SE, the following table gives you insight about the images you can build:

MACHINE	SUBMACHINE	PROJECT	CUSTOMER	Resulting image
evachargese	""	bsp	""	Basic BSP image for EVAcharge SE
evachargese	""	bsp	developer	BSP image for EVAcharge SE with additional developer packages
tarragon	""	bsp	""	Basic BSP image for Tarragon
tarragon	""	bsp	developer1	BSP image for Tarragon with additional developer packages
chargesom	dc-evb	bsp	""	Basic BSP image for Charge SOM with DC EVB carrier board
chargesom	dc-evb	bsp	developer1	BSP image for Charge SOM with DC EVB and additional developer packages

For building an image, you would need to do the following:

1. Set the configurations for your build as mentioned in the table above. You can either:

• Execute the following commands to e.g., set the machine to tarragon and project to bsp:

export MACHINE=tarragon
export SUBMACHINE=""
export PROJECT=bsp
export BB_ENV_PASSTHROUGH_ADDITIONS="PROJECT MACHINE SUBMACHINE"

• Edit yocto/build/conf/local.conf directly. e.g., MACHINE=....

2. Execute source yocto/source/oe-init-build-env build which initializes the build environment and changes the directory to yocto/build.
3. Execute bitbake core-image-minimal to build the image.

The resulting image will be found in yocto/build/tmp/deploy/image/<machine>, having a filename similar to core-image-minimal-platform-1234567890-rootfs.ext4.gz

Flashing an Image

The internal storage of the products Charge Control C (Tarragon), M (EVAcharge SE) and Charge SOM is divided into several partitions and uses RAUC to handle updates. If you are interested in adding RAUC to your own image you can take a look at RAUC's documentation https://rauc.readthedocs.io/en/latest/integration.html#yocto . To flash an image it is important to identify the currently not-in-use partition because this will be our target partition.

The following tables describe the partitioning for Charge Control M and Charge Control C:

Charge Control M:

Partition	Size	Description
/dev/mmcblk0p1	3 MB	Bootloader Partition
/dev/mmcblk0p2	1 GB	Root file system A
/dev/mmcblk0p3	1 GB	Root file system B
/dev/mmcblk0p4		Extended Partition Container
/dev/mmcblk0p5	1 GB	Data Partition(/srv). This partition can be accessed by both file systems.
/dev/mmcblk0p6	128 MB	Logging file system A (/var/log)
/dev/mmcblk0p7	128 MB	Logging file system B (/var/log)

Charge Control C:

Partition	Size	Description
/dev/mmcblk0p1	1 GB	Root file system A
/dev/mmcblk0p2	1 GB	Root file system B
/dev/mmcblk0p3		Extended Partition Container
/dev/mmcblk0p5	1 GB	Data Partition(/srv). This partition can be accessed by both file systems.
/dev/mmcblk0p6	128 MB	Logging file system A (/var/log)
/dev/mmcblk0p7	128 MB	Logging file system B (/var/log)

A similar partitioning is used on the eMMC of the Charge SOM based products:

Charge SOM:

Partition	Size	Description
/dev/mmcblk0p1	2 GB	Root file system A
/dev/mmcblk0p2	2 GB	Root file system B
/dev/mmcblk0p3		Extended Partition Container
/dev/mmcblk0p5	~2.7 GB	Data Partition(/srv). This partition can be accessed by both file systems.
/dev/mmcblk0p6	128 MB	Logging file system A (/var/log)
/dev/mmcblk0p7	128 MB	Logging file system B (/var/log)

1. To identify the currently booted partition execute the following command and look for the partition which is marked with boot status good. For this example we will be on partition /dev/mmcblk0p1 on a Charge Control C.

rauc status

Output:

=== System Info ===
Compatible: I2SE Tarragon
Variant:
Booted from: rootfs.1 (B) 

=== Bootloader ===
Activated: rootfs.1 (B)

=== Slot States ===
x [rootfs.1] (/dev/mmcblk0p1, ext4, booted)
	 bootname: B
	 mounted: / 
	 boot status: good 
  [customerfs.1] (/dev/mmcblk0p6, ext4, active) mounted: /var/log
o [rootfs.0] (/dev/mmcblk0p2, ext4, inactive)
	 bootname: A
	 boot status: bad
  [customerfs.0] (/dev/mmcblk0p7, ext4, inactive)

2. Copy your image to /srv using any client capable of SFTP.
3. In the /srv directory execute the following command to flash your image to /dev/mmcblk0p2

zcat core-image-minimal-tarragon-1234567890-rootfs.ext4.gz > /dev/mmcblk0p2

4. Mount /dev/mmcblk0p2 and replace /sbin/init binary file with the following commands. (Omitting this step will format logging and data partitions)

mount /dev/mmcblk0p2 /mnt
mv /mnt/sbin/init.orig /mnt/sbin/init
umount /dev/mmcblk0p2

5. Mark the other partition as active with RAUC through the following command.

rauc status mark-active other

6. Reboot

Appendix

How to change kernel configurations

It may occur that you want to adapt the system's kernel configuration to be suitable for your special requirements, e.g., adding drivers or packages like Docker. Here are the steps you need to follow to generate a Linux image based on your desired kernel configuration:

1. Execute the command bitbake linux-imx -c menuconfig to open a tool that permits you to change the kernel configuration.
2. If you know the configuration name by the convention CONFIG_* only, you can search for it by typing "/" and putting its name after. You will be told which other configurations you need to set in order to be able to view this configuration and set it, as sometimes they may be hidden. Type "z" to find the hidden configurations. Press exit and choose "yes" to save the configurations temporarily.
3. You will need to perform the following commands in your build directory to save the configuration permanently and move them to your recipe folder.

bitbake -c savedefconfig linux-imx

cp tmp/work/tarragon-poky-linux-gnueabi/linux-imx/4.9.123-r0/build/defconfig  ../source/meta-chargebyte/recipes-kernel/linux/linux-imx/imx/

4. In the bbappend file found in meta-chargebyte/recipes-kernel/linux/linux-imx_%.bbappend, change the SRC_URI to be the following:

SRC_URI = "\
            git://github.com/chargebyte/linux.git;protocol=https;branch=${SRCBRANCH} \
            file://defconfig \
          "

5. Perform the following commands to remove the output files and shared state cache for the linux kernel, and then build a new image with the new kernel configuration.

bitbake -c cleansstate linux-imx

bitbake core-image-minimal

6. You may check the .config file located in tmp/work/tarragon-poky-linux-gnueabi/linux-imx/4.9.123-r0/build/ to make sure that your changes were added to the kernel configuration.

Footnotes

1. to be able to build a developer image, check the respective documentation in local.conf ↩ ↩²