Zephyr RTOS¶

Project Structure¶

Zephyr framework requires an unusual project structure because most of the framework configuration is performed by the native for Zephyr build system called CMake.

A typical PlatformIO project for Zephyr framework must have the following structure:

project_dir
├── include
├── src
│    └── main.c
├── zephyr
│    ├── prj.conf
│    └── CMakeLists.txt
└── platformio.ini

Besides files related to PlatformIO project, there is an additional folder zephyr that contains Zephyr-specific files CMakeLists.txt and prj.conf:

CMakeLists.txt file enables features supported by Zephyr’s build system, e.g. board-specific kernel configuration files. A typical CMakeLists.txt file has the following content:

# Boilerplate code, which pulls in the Zephyr build system.
cmake_minimum_required(VERSION 3.13.1)
include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
project(my_zephyr_app)

# Add your source file to the "app" target. This must come after the boilerplate
# code, which defines the target. Note relative path to source file
target_sources(app PRIVATE ../src/main.c)

The files specified in target_sources are used ONLY for generating build configurations, but it’s highly recommended to specify all application source files in order to keep the project compatible with the usual Zephyr workflow.

Due to the current limitations of CMake file-based API, there is no way to generate build configuration for source files written in various programming languages if they are not specified in target_sources command. If your project contains libraries written in languages that differ from the language used for the main application you need to create an empty file with desired extension (e.g. *.cpp for C++) in order to force CMake generate build configuration for this language.

prj.conf file sets application-specific values for one or more kernel configuration options. These application settings are merged with board-specific settings to produce a kernel configuration.

Devicetree overlays¶

Zephyr applications can use overlay files to enable a peripheral that is disabled by default, select a sensor on the board for an application specific purpose, etc. This makes it possible to reconfigure the kernel and device drivers without modifying source code. There are several ways to set .overlay files:

• Using DTC_OVERLAY_FILE variable in the CMakeLists.txt file, before including Zephyr’s boilerplate.cmake file. (Recommended)

• Using a boards/<BOARD>.overlay file in the zephyr folder, for the current board

• Using a <BOARD>.overlay file in the zephyr folder.

Embedding files at compile time¶

In case your CMakeLists.txt relies on using generate_inc_* functions that are used for generating and compressing individual files (for example certificates for secure connections) you need to configure your PlatformIO project accordingly using the following structure:

[env:myenv]
platform = ...
board = ...
framework = zephyr
board_build.embed_files =
    # files to be embedded
    src/apps-cert.der
    src/apps-key.der

Where apps-cert.der and apps-key.der are the files you want to embed to your project at the compile time.

Zephyr modules¶

Zephyr modules are externally maintained packages that allow using well-established and mature code created by third party developers.

These modules contain either a single module.yml file or CMakeLists.txt and Kconfig files that describe how to build and configure them. You can specify paths to additional directories with source code, Kconfig, etc. using ZEPHYR_EXTRA_MODULES at the top of your project’s CMakeLists.txt file, for example:

# Additional modules
set(ZEPHYR_EXTRA_MODULES "path/to-zephyr-custom-module"  [...])

# Boilerplate code, which pulls in the Zephyr build system.
cmake_minimum_required(VERSION 3.13.1)
include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
project(my_zephyr_app)

# Add your source file to the "app" target. This must come after
# the boilerplate code, which defines the target.
target_sources(app PRIVATE ../src/main.c)

Since the build may not work correctly if the full path to sources is greater than 250 characters (see CMAKE_OBJECT_PATH_MAX) it might be a good idea to keep modules close to the project configuration files (e.g. in zephyr folder) in form of a git submodule.

Limitations¶

At the moment several limitations are present:

• The minimum supported version of Python is 3.4

• No whitespace characters allowed in project paths.

• The Trusted Firmware M module is not supported

Tools & Debug Probes¶

Supported debugging tools are listed in “Debug” column. For more detailed information, please scroll table by horizontal. You can switch between debugging Tools & Debug Probes using debug_tool option in “platformio.ini” (Project Configuration File).

96Boards¶

Adafruit¶

Arduino¶

Atmel¶

BBC¶

Digilent¶

ElectronutLabs¶

Freescale¶

Generic¶

Holyiot¶

Laird Connectivity¶

Makerdiary¶

MikroElektronika¶

NXP¶

Nordic¶

Olimex¶

PHYTEC¶

Particle¶

RedBearLab¶

Ruuvi¶

SEGGER¶

ST¶

Seeed¶

SiFive¶

Silicon Labs¶

SparkFun¶

VNG¶

Waveshare¶

WeAct Studio¶

u-blox¶