Building a Custom Yocto Layer for Siemens IOT2000: Tutorial

Overview

The Siemens SIMATIC IOT2000 series (IOT2020, IOT2040) is an industrial gateway platform that runs a custom Linux image built with the Yocto Project and the OpenEmbedded build system. Siemens ships two reference layers — meta-iot2000-bsp (board support package) and meta-iot2000-example (sample image recipes) — through the official meta-iot2000 GitHub repository. When you need to add packages such as Apache2 with PHP and SQLite, ship a custom application, or change configuration defaults, the recommended path is to create your own Yocto layer rather than editing the upstream layers in place.

This article walks through the complete workflow for building a custom layer for the IOT2000, using kas as the build orchestrator, and explains the role of .bbappend files, the BBFILES variable, and LAYERDEPENDS declarations. The same procedure applies to any Yocto/OE-based image; the IOT2000-specific parts are clearly marked.

Prerequisites

Before you create a custom layer, set up the host environment that matches the IOT2000 BSP requirements.

• Host OS: A 64-bit Linux distribution. The Siemens BSP is validated against Ubuntu 18.04/20.04 LTS; other modern distributions (Debian, Fedora, openSUSE) also work with the standard Yocto dependencies.
• Required host packages: git, build-essential, chrpath, diffstat, gawk, gcc-multilib, libsdl1.2-dev, python3, python3-pip, texinfo, unzip, wget, file, libssl-dev, rpcbind. The full list is in the Yocto Project's Build Host Packages reference.
• kas: Install via pip3 install kas (kas 2.x or 3.x is compatible with meta-iot2000). Verify with kas --version.
• Disk space: 80–120 GB free in the build directory. A clean Yocto build with sstate-cache disabled typically consumes 60+ GB.
• RAM: Minimum 8 GB; 16 GB recommended for parallel builds (BB_NUMBER_THREADS = "8").

Understanding the IOT2000 Layer Architecture

Yocto layers are isolated directories that each contain a conf/layer.conf file declaring the layer's metadata, the recipes it provides, and its dependencies. For the IOT2000, three layers matter:

Siemens already pulls meta-openembedded into the default build via the kas file in meta-iot2000-example. You do not need to clone it manually when your custom kas file declares the same repositories. This avoids the fatal: not a git repository (or any of the parent directories): .git error that occurs when kas tries to update a directory it cannot identify.

Step 1 — Create the Custom Layer Directory Structure

Create a sibling directory to meta-iot2000-bsp and meta-iot2000-example. The directory name becomes the layer name; use only letters, digits, and hyphens.

1. Open a terminal in the parent directory that contains the two Siemens layers.
2. Create the layer skeleton:

   mkdir -p meta-my-iot2000/conf
   mkdir -p meta-my-iot2000/recipes-core/images
   mkdir -p meta-my-iot2000/recipes-httpd/apache2
   

3. Initialise an empty README.md and optional LICENSE (e.g. MIT) so the layer is self-describing.

The recipes-core/images path is not strictly required, but mirroring the upstream naming convention makes BBFILES patterns easy to read.

Step 2 — Write the layer.conf File

Every layer must have a conf/layer.conf declaring what recipes it provides and which other layers it depends on. For a layer that only customises the IOT2000 example image, a minimal file looks like:

# 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"

# Standard layer metadata
LAYERVERSION = "1"
LAYERDEPENDS_meta-my-iot2000 = "core iot2000-example openembedded-layer"
LAYERDEPENDS += "core iot2000-example openembedded-layer"

# Recognise bitbake variables LAYERDIR and LAYERVERSION
LAYERSERIES_COMPAT_meta-my-iot2000 = "dunfell gatesgarth hardknott honister kirkstone"

Key declarations:

• BBFILES: Globs the recipes and bbappends. If your bbappend is not picked up, the glob is the first place to check — bitbake silently ignores files outside the pattern.
• LAYERDEPENDS: Lists the layers your layer requires. Omitting iot2000-example causes bitbake to fail with "variable do_compile not found" or "recipe not found" when processing bbappends that target the IOT2000 image recipe. Forgetting openembedded-layer triggers errors when extending recipes that originate from meta-openembedded.
• LAYERSERIES_COMPAT: Yocto release codenames your layer has been tested with. Mismatches raise a warning but do not block the build.

Step 3 — Create the kas Build File

kas is a YAML-driven build orchestrator that clones repositories, checks out the right revisions, and runs bitbake. Drop a kas.yml at the root of your custom layer:

header:
  version: 11

machine: iot2040
distro: iot2000-example

target:
  - iot2000-example-image

repos:
  meta-iot2000:
    url: https://github.com/siemens/meta-iot2000.git
    refspec: master
  meta-openembedded:
    url: https://github.com/openembedded/meta-openembedded.git
    refspec: master
  meta-my-iot2000:
    url: .
    refspec: 

layers:
  - name: meta-iot2000-bsp
  - name: meta-iot2000-example
  - name: meta-openembedded/meta
  - name: meta-openembedded/meta-webserver
  - name: meta-openembedded/meta-python
  - name: meta-openembedded/meta-networking
  - name: meta-my-iot2000

Notes on the kas file:

• url: . for meta-my-iot2000 tells kas to use the current directory instead of cloning from a remote. This is what enables the "no .git" workflow when you develop locally.
• YAML colon placement: A colon must be followed by a space. The error "while scanning a simple key ... could not find expected ':'" is a YAML parse error and has nothing to do with bitbake.
• Order of layers matters when two layers provide the same recipe. The later entry wins; place meta-my-iot2000 last so your bbappends override upstream values.

Step 4 — Extend the IOT2000 Example Image with a .bbappend

A .bbappend file is appended to the original recipe when bitbake parses it. Use it to add packages to IMAGE_INSTALL, override variables, or append files to IMAGE_FEATURES.

1. Mirror the directory structure of the original recipe. If iot2000-example-image.bb lives at meta-iot2000-example/recipes-core/images/, place the bbappend at the same path inside your custom layer:

   meta-my-iot2000/recipes-core/images/iot2000-example-image.bbappend
   

2. Write the bbappend:

   IMAGE_INSTALL_append = " apache2 php php-cli php-sqlite3 sqlite3"
   
   # Optional: enable Apache modules
   PACKAGECONFIG_append_pn-apache2 = " ssl"
   
   # Optional: start Apache by default
   SYSTEMD_AUTO_ENABLE_pn-apache2 = "enable"
   

3. Save the file. The next kas build kas.yml will pick it up because BBFILES in your layer.conf matches *.bbappend.

Step 5 — Optional: Carry a Local Apache2 Recipe with PHP and SQLite

If you need to modify the Apache2 recipe itself — for example to force-enable mod_php or apply a patch — copy the upstream apache2_2.4.29.bb from meta-openembedded/meta-webserver/recipes-httpd/apache2 into meta-my-iot2000/recipes-httpd/apache2/ and then either edit the recipe in place or add an apache2_2.4.29.bbappend next to it. Carrying the unmodified upstream recipe is the correct approach when you need full control; carrying only a bbappend is preferred when your changes are limited to PACKAGECONFIG entries and patches.

A minimal bbappend for enabling PHP and SQLite support looks like:

PACKAGECONFIG_append = " php"

SRC_URI_append = " file://my-mod_php.conf"

do_install_append() {
    install -d ${D}${sysconfdir}/apache2/mods-enabled
    install -m 0644 ${WORKDIR}/my-mod_php.conf ${D}${sysconfdir}/apache2/mods-enabled/php.conf
}

The recipe from meta-openembedded is already known to the build because Siemens' kas file pulls meta-openembedded/meta-webserver into the layer set. You do not need to copy it; only the bbappend is required if your changes are additive.

Step 6 — Run the Build

From the root of your custom layer, execute:

kas build kas.yml

kas will:

1. Clone meta-iot2000 and meta-openembedded into a workspace.
2. Symlink or copy your meta-my-iot2000 directory into that workspace.
3. Run source oe-init-build-env.
4. Append each conf/layer.conf to bitbake.conf.
5. Execute bitbake iot2000-example-image.

For an incremental rebuild after editing a bbappend, the same command is sufficient. For a clean build, append --force-checkout or delete the build/tmp directory.

Verification

After a successful build, the image is written to build/tmp/deploy/images/iot2040/ as iot2000-example-image-iot2040.wic (or .ext4 / .hddimg depending on the BSP version). To verify the customisation took effect:

1. Inspect the package list:

   gunzip -c build/tmp/deploy/images/iot2040/iot2000-example-image-iot2040.wic.gz | \
     (mknod /tmp/img p; cat > /tmp/img) 2>/dev/null
   sudo losetup -P /dev/loop0 /tmp/img
   sudo mount /dev/loop0p2 /mnt
   ls /mnt/usr/lib/apache2/modules/ | grep php
   ls /mnt/usr/bin/ | grep sqlite
   sudo umount /mnt
   

2. Boot the IOT2040 with the new image, log in over serial or SSH, and confirm:

   systemctl status apache2
   php -v
   sqlite3 --version
   apache2ctl -M | grep php
   

3. Confirm the custom layer's bbappend was parsed:

   bitbake-getvar -r iot2000-example-image IMAGE_INSTALL | grep apache2
   

Troubleshooting Matrix

Best Practices for Maintainable IOT2000 Custom Layers

• Never edit upstream Siemens layers in place. All customisations belong in your own layer so that upgrading meta-iot2000 remains a one-step operation.
• Prefer bbappend over recipe copying. A bbappend survives upstream refactors; a copied recipe diverges silently.
• Pin upstream revisions. Replace refspec: master with a commit SHA or tag in the kas file for reproducible builds.
• Keep IMAGE_INSTALL appends sorted alphabetically. Bitbake is order-insensitive, but humans are not. Sorting prevents duplicate appends during merges.
• Use a shared sstate-cache. Configure SSTATE_MIRRORS in build/conf/local.conf to point at a CI archive and cut rebuild time from hours to minutes.
• Test the bbappend in isolation. Build only apache2 with bitbake apache2 -c populate_sysroot before triggering a full image build to catch recipe errors early.

Field-Proven Notes

Two operational details that consistently surface during commissioning:

1. Serial console configuration. The IOT2000 default iot2000-example-image enables the serial console at 115200 8N1 on the first UART. Custom layers that override [email protected] or IMAGE_FEATURES should re-enable it explicitly to keep debugging access after field deployment.
2. Read-only root filesystem. The Siemens example image ships a read-only rootfs with an overlay for /var. Adding packages that write to /etc (e.g. apache2 with default config) will fail on first boot. Use IMAGE_FEATURES_append = " read-only-rootfs" together with a custom systemd tmpfiles configuration to redirect writable paths to /var.

References Within This Article

• Siemens meta-iot2000 GitHub repository
• meta-openembedded Apache2 recipe
• Yocto Project: Customising Your Image with a Custom Layer
• BitBake User Manual
• kas documentation