Knowledge Base

Requirements

Make sure that you have prepared the following points:

• The edge device is set up with a TeamViewer Embedded Agent.
• The edge device is connected to the internet.
• Your PC is set up with the TeamViewer Client.
• Your login credentials for the edge device (user name, and password).
• Installed dependencies (based on the operating system of Raspberry). Please install the following packages on the system: build-essential
  • lz4
  • git
  • texinfo
  • python3-distutils
  • libncurses5-dev
  • gawk
  • diffstat
  • chrpath

📌Note: On Ubuntu, you can install these packages with the following command:

:~$ sudo apt-get install build-essential chrpath diffstat gawk libncurses5-dev python3-distutils texinfo git lz4

Setup

1. On your PC open the TeamViewer Client and log in.

2. On the left side open the Computers & Contacts tab.

3. Double-click the device.

• The Control Window opens and the connection will be established.

4. In the Control Window on the top, open the Remote Terminal tab.

5. Type in your user password and press Enter.

6. To get the Yocto build environment, first git clone the latest Yocto and checkout a specific branch. It is generally not recommended to use main/master.

:~$ git clone -b kirkstone git://git.yoctoproject.org/poky.git kirkstone

This will download the latest kirstone branch from Yocto in the folder kirkstone.

7. Go to the kirkstone folder and clone the following repos to install the packages necessary to build an OS for Raspberry Pi with a desktop and with all the dependencies for the TeamViewer Agent:

• meta-openembedded - This is needed for having a desktop, network and other basic OS components on the device.
• meta-raspberrypi - This is needed for Raspberry Pi specific software and configuration, like the proprietary boot loader.
• meta-qt - This is needed for having QT on the device. This one is optional.
• meta-security

This can be done using the following commands:

~$ cd kirkstone
~/kirkstone$ git clone -b kirkstone git://git.openembedded.org/meta-openembedded
~/kirkstone$ git clone -b kirkstone https://github.com/meta-qt5/meta-qt5
~/kirkstone$ git clone -b kirkstone git://git.yoctoproject.org/meta-raspberrypi
~/kirkstone$ git clone -b kirkstone git://git.yoctoproject.org/meta-security.git

8. Make sure that all the branches match the one for the Yocto Project. If this is not the case, please make sure that the meta layers are compatible with the Yocto Project branch by checking the variable LAYERSERIES_COMPAT_${PN} found in the conf/layer.conf file. The ${PN} is the package name.

# 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 += "filesystems-layer"
BBFILE_PATTERN_filesystems-layer = "^${LAYERDIR}/"
BBFILE_PRIORITY_filesystems-layer = "6"
 
# This should only be incremented on significant changes that will
# cause compatibility issues with other layers
LAYERVERSION_filesystems-layer = "1"
 
LAYERDEPENDS_filesystems-layer = "core openembedded-layer"
 
LAYERSERIES_COMPAT_filesystems-layer = "kirkstone"

If the LAYERSERIES_COMPAT_${PN} is missing, this means there are no hard compatibility dependencies.

How to build it all and test it

To create the workspace for building the OS:

1. Source the oe-init-build-env script.

~/kirkstone$ source oe-init-build-env build
You had no conf/local.conf file. This configuration file has therefore been
created for you from /home/adrian/kirkstone/meta-poky/conf/local.conf.sample
You may wish to edit it to, for example, select a different MACHINE (target
hardware). See conf/local.conf for more information as common configuration
options are commented.
 
You had no conf/bblayers.conf file. This configuration file has therefore been
created for you from /home/adrian/kirkstone/meta-poky/conf/bblayers.conf.sample
To add additional metadata layers into your configuration please add entries
to conf/bblayers.conf.
 
The Yocto Project has extensive documentation about OE including a reference
manual which can be found at:
    https://docs.yoctoproject.org
 
For more information about OpenEmbedded see the website:
    https://www.openembedded.org/
 
 
### Shell environment set up for builds. ###
 
You can now run 'bitbake <target>'
 
Common targets are:
    core-image-minimal
    core-image-full-cmdline
    core-image-sato
    core-image-weston
    meta-toolchain
    meta-ide-support
 
You can also run generated qemu images with a command like 'runqemu qemux86'
 
Other commonly useful commands are:
 - 'devtool' and 'recipetool' handle common recipe tasks
 - 'bitbake-layers' handles common layer tasks
 - 'oe-pkgdata-util' handles common target package tasks

This command will setup the build environment and create the folder build.

2. Add all of the meta layers to the build system.

~/kirkstone$ cd build
~/kirkstone/build$ bitbake-layers add-layer ../meta-openembedded/meta-oe \
        ../meta-openembedded/meta-filesystems/ \
        ../meta-openembedded/meta-gnome/ \
        ../meta-openembedded/meta-initramfs/ \
        ../meta-openembedded/meta-multimedia/ \
        ../meta-openembedded/meta-networking/ \
        ../meta-openembedded/meta-perl/ \
        ../meta-openembedded/meta-python/ \
        ../meta-openembedded/meta-webserver/ \
        ../meta-openembedded/meta-xfce/ \
        ../meta-teamviewer-iot-agent \
        ../meta-raspberrypi \
        ../meta-qt5 \
        ../meta-security

3. Configure the build system to build the correct type of OS with the OS features and software packages the user needs.

#MACHINE ?= "beaglebone-yocto"
#MACHINE ?= "genericx86"
#MACHINE ?= "genericx86-64"
#MACHINE ?= "edgerouter"
#
# This sets the default machine to be qemux86-64 if no other machine is selected:
MACHINE ??= "raspberrypi3"

# For building a Raspberry pi
DISTRO_FEATURES:append = " security"
 
IMAGE_INSTALL:append = " openssh-sftp-server sudo python3 python3-pip rpi-gpio raspi-gpio"
 
IMAGE_FEATURES:append = " ssh-server-openssh"
 
IMAGE_FSTYPES = "wic.bz2 rpi-sdimg"
 
LICENSE_FLAGS_ACCEPTED = "commercial"
 
# For TeamViewer Embedded Agent
DISTRO_FEATURES:append = " X11"
 
IMAGE_INSTALL:append = " teamviewer-iot-agent"
 
IMAGE_ROOTFS_EXTRA_SPACE = "256000"
 
VOLATILE_LOG_DIR = "no"

The variable IMAGE_FSTYPES tells the Yocto build system what type of file system image to generate and can take many different values. These can be specified with a space between them. Some of the supported file system types are:

• rpi-sdimg
• wic.bz
• tar, tar.gz, tar.bz2, tar.xz, tar.lz3
• ext2, ext2.gz, ext2.bz, ext2.lzma
• ext3, ext3.gz
• jffs2, jffs2.sum
• iso
• hddimg
• squashfs, squashfs-xz
• ubi, ubifs

For a more comprehensive list of supported file system types, please check the Yocto documentation.

4. To start the build process, please call the bitbake command with the image name.

:~/kirkstone/build$ bitbake core-image-minimal-xfce

The resulting image will be located under kirkstone/build/tmp/deploy/images/raspberrypi3 and follows this naming convention image_type-arch.fstype

-rw-r--r-- 2 adrian adrian     7807 Nov 17 16:03 core-image-minimal-xfce.env
-rw-r--r-- 2 adrian adrian 746586112 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64-20221117150143.rootfs.ext3
-rw-r--r-- 2 adrian adrian   153011 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64-20221117150143.rootfs.manifest
-rw-r--r-- 2 adrian adrian 801112064 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64-20221117150143.rootfs.rpi-sdimg
-rw-r--r-- 2 adrian adrian 144049131 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64-20221117150143.rootfs.wic.bz2
-rw-r--r-- 2 adrian adrian   421745 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64-20221117150143.testdata.json
lrwxrwxrwx 2 adrian adrian       66 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64.ext3 -> core-image-minimal-xfce-raspberrypi3-64-20221117150143.rootfs.ext3
lrwxrwxrwx 2 adrian adrian       70 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64.manifest -> core-image-minimal-xfce-raspberrypi3-64-20221117150143.rootfs.manifest
lrwxrwxrwx 2 adrian adrian       71 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64.rpi-sdimg -> core-image-minimal-xfce-raspberrypi3-64-20221117150143.rootfs.rpi-sdimg
lrwxrwxrwx 2 adrian adrian       68 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64.testdata.json -> core-image-minimal-xfce-raspberrypi3-64-20221117150143.testdata.json
lrwxrwxrwx 2 adrian adrian       69 Nov 17 16:03 core-image-minimal-xfce-raspberrypi3-64.wic.bz2 -> core-image-minimal-xfce-raspberrypi3-64-20221117150143.rootfs.wic.bz2

5. To flash the image to an SD Card, the user can use either the dd command or the bmaptool command based.

:~$ sudo dd if=kirkstone/build/tmp/deploy/images/raspberrypi3/core-image-minimal-xfce-raspberrypi3-64.rpi-sdimg of=/dev/sdc bs=4M status=progress
or
:~$ sudo bmaptool copy kirkstone/build/tmp/deploy/images/raspberrypi3-64/core-image-minimal-xfce-raspberrypi3.wic.bz2 /dev/sdc -nobmap

Please make sure to replace the sdc with the device name of the mounted SD Card.

6. To test the image just insert the SD card in a Raspberry Pi 3 and power it on. The core-image-minimal-xfce will have a desktop so attaching a monitor to it will help. The image has port 22 open and the login is root without password.

If you want to generate the SDK necessary to cross-compile any software for this specific device instead of the image, please also include the argument -c populate_sdk.

:~/kirkstone/build$ bitbake core-image-minimal-xfce -c populate_sdk

The SDK will be generate under kirkstone/build/tmp/deploy/sdk and has the following naming convention: poky-glibc-host_system-image_type-arch-toolchain-release_version.sh. For the Raspberry Pi 3 32 bits OS this SDK will be named poky-glibc-x86_64-core-image-minimal-xfce-cortexa53-raspberrypi3-toolchain-4.0.5.sh

Further reading material for Yocto

• Yocto documentation
• Embedded Linux Systems With the Yocto Project by Rudolf J. Streif