Build a Zephyr app in redpesk - User Workflow

Prerequisites

Prepare your Zephyr app

If you want to build a Zephyr custom user app, its structure must meet Zephyr’s requirements.
On the other hand, if you want to build a Zephyr sample available in Zephyr file tree, you can skip this step.

The structure of a Zephyr app is described in the official Zephyr documentation:

Also, your Zephyr custom user app must be designed for one of the Zephyr distro we provide in redpesk.
If you want your app to be built on several of the distro products we provide, please prepare a distinct branch for each Zephyr distro.

As an example, we provide our own Zephyr custom user app “Zephyr-shell” available here: https://github.com/iotbzh/zephyr-shell

Zephyr app building guide

Create your project

To build Zephyr apps, you will first need to create a standard project.
This project can also contain other unrelated Apps.

  • Name: Any name you want, the name we are using in this guide is “zephyr-apps”
  • Distributions: At least one of the available Zephyr distributions.
  • Architectures: x86_64 (even if your target is ARM)

    Note: aarch64 host builds should be available later

  • Inheritance: You do not need any specific inheritance to build Zephyr apps

create-project

Create your Zephyr app

You will now create your Zephyr app in the project you just created.

In the following guide, two types of Zephyr app are supported, please follow the suited guide for your case:

  • Zephyr sample app: An app that is present in the Zephyr kernel file tree (samples and tests)
  • Zephyr custom user app: Your very own app hosted on a public git repository and prepared as described here

We published some examples of specfiles for you to use as starting points:

Zephyr sample app

As a Zephyr sample app example, we will prepare the build of the hello-world sample, located in the sample folder of Zephyr kernel file tree.

  • Name: zephyr-hello-world
  • Package Name: zephyr-hello-world
  • Distributions: Select one Zephyr distribution only

    Note: Multi distribution builds should be available later

  • Default package branch: main
  • Source URL: leave empty
  • Source revision: leave empty
  • Specfile: Internal Spec File

Under “application services” tab, please disable “Version update” option.

hello-world-branch-settings

You can then replace the content of generated specfile by this specfile template and edit some fields if needed.

Zephyr custom user app

As a Zephyr custom user app example, let’s look at how we create our zephyr-shell app for Zephyr latest distribution.
This example can also be built for Zephyr LTS releases distribution by using dedicated “lts2” & “lts3” tags.

  • Name: zephyr-shell
  • Package Name: zephyr-shell
  • Distributions: Select one Zephyr distribution only

    Note: Multi distribution builds should be available later

  • Default package branch: main
  • Source URL: https://github.com/iotbzh/zephyr-shell
  • Source revision: latest
  • Specfile: Internal Spec File

Under “application services” tab, please disable “Version update” option.

shell-branch-settings

You can then replace the content of generated specfile by this specfile template and edit some fields if needed.

Zephyrs apps templates

To help you get started, we provide some specfile templates for both Zephyr sample app and Zephyr custom user app.
Zephyr apps specfile templates are available here, you can complete them based on our specfile samples available here and/or with this guide.

Here’s how to fill in _TO_COMPLETE_ fields:

  • target name: Your board Zephyr name (used by west to build your firmware for your target)
  • target toolchain: Please fill target architecture using list of available toolchains linked here.
  • firmware name: Firmware name used in output file name
  • Name: Should be your redpesk App name
  • Version: branch or tag name used at app creation (if in x.x.x form, 0.0.0 otherwise)
  • Summary: Short summary for your Zephyr app, can be left empty
  • License: Your Zephyr app sources license, can be left empty
  • URL: URL to your app sources, can be left empty
  • Description: Longer description of your Zephyr app, can be left empty

Zephyr sample app specific configuration:
For Zephyr in-tree app, we also need to specify the path to the sources of the app under the Zephyr kernel file tree.
Please refer to the kernel file tree and edit the _TO_COMPLETE_ field under %prep.

Some advanced configuration:

  • If your Zephyr app has a custom build name, you need to edit lines under the %install section by providing reliable firmware paths.
  • Default output directory for firmware is /lib/firmware, it can be edited in the specfile in %files section.

Build your app

1 - At each specfile edition, an SRPM build will automatically be triggered.

2 - Once an SRPM is ready for your current specfile version, you can trigger a build as you usually do in the redpesk Factory.

3 - Once the build is done, you can find your output RPM containing your firmware files in the RPM's build tab. You can download RPM using either GUI or RP-CLI.

  • GUI

RPM-download

  • RP-CLI command to download the rpm: rp-cli applications download <application-alias> zephyr-xxxx.rpm

4 - This RPM can also be shipped in an Image, in this case, firmware files will be available in /lib/firmware folder by default.

Build and run on QEMU64

Some specific QEMU64 directives are already applied in our specfile samples and templates with qemu_x86_64 as targetname:

  • cd build && ninja qemu_locore_image_target qemu_main_image_target
  • %{__install} -m 755 build/zephyr/zephyr*qemu*.elf %{buildroot}/lib/firmware/

Build and run guide for QEMU64:

  • Build your app and download output RPM as described here.
  • Install qemu-system-x86_64 & rpm2cpio on your system
  • Execute the following commands
# Create and enter working dir
mkdir -p qemu64-zephyr
cd qemu64-zephyr

# Download the RPM here using GUI or RP-CLI
rp-cli applications download <application-alias> zephyr-xxxx.rpm

# Extract the RPM content here
rpm2cpio zephyr-xxxx.rpm | cpio -idmv

# Run firmware on QEMU64
qemu-system-x86_64 -m 32 -cpu qemu64,+x2apic,mmx,mmxext,sse,sse2 -machine q35 -device isa-debug-exit,iobase=0xf4,iosize=0x04 -no-reboot -nographic -machine acpi=off -net none -pidfile qemu.pid -chardev stdio,id=con,mux=on -serial chardev:con -mon chardev=con,mode=readline -device loader,file=./lib/firmware/zephyr-qemu-main.elf -smp cpus=2 -kernel ./lib/firmware/zephyr-qemu-locore.elf
  • Here is the obtained log when booting hello-world sample on a QEMU64 system: 
    SeaBIOS (version 1.16.3-2.fc40)
Booting from ROM..
*** Booting Zephyr OS build  ***
Hello World! qemu_x86_64

Note: QEMU64 commands have been tested on the following qemu-system-x86_64 version:

  • 8.2.2 on Fedora 40 : OK
  • 6.2.0 on ubuntu 22.04 : OK
  • 4.2.1 on ubuntu 20.04 : OK - (remove -machine acpi=off from the above command)