Guide to Zephyr Workspace Topologies: Choose the Best for Your Project

Introduction

Are you diving into the world of Zephyr RTOS (Real-Time Operating System) but puzzled about how to structure your workspace effectively? You’re not alone. One of the first steps in Zephyr development is setting up a well-organized workspace, and the topology you choose can make a world of difference. In this guide, we’ll demystify Zephyr workspace topologies, helping you choose the best fit for your needs and even contributing to the Zephyr project itself. For general setup, installation of Zephyr and run your first example, please refer to this guide: Running Zephyr blinky sample in Raspberry Pi Pico board

Why Workspace Topology Matters

In Zephyr, a workspace is more than just a directory; it’s the backbone of your entire project. It contains the Zephyr RTOS, any external libraries, dependencies, and, of course, your application. The way you organize these elements can impact your development efficiency, so choosing an appropriate workspace topology is crucial.

Decoding Zephyr Workspace Topologies

If you’re looking to create you single project with Zephyr RTOS please consider moving directly to T2: Star topology, application is the manifest repository¶

T1: Star Topology with Zephyr as the Manifest Repository

In the T1 topology, the Zephyr repository is the heart of your workspace. It includes a west.yml manifest file that specifies all other projects and modules. This setup is especially useful if you’re planning to contribute to the Zephyr project.

Ideal for: Developers looking to contribute to the Zephyr project or those who wish to stay closely aligned with Zephyr’s updates.

Not recommended for: Developers who want to create applications with Zephyr RTOS but have no intent to contribute to Zephyr. If you’re focusing solely on application development, consider T2 or T3 topologies.

Directory Structure

my_zephyr_workspace/
|-- zephyr/             # Zephyr RTOS repository
|   └── west.yml        # Manifest file specifying external projects
|-- modules/
|   └── external_lib/   # External library

How to set it up:

1. Create a new folder for your workspace:

mkdir ws_t1_example
cd ws_t1_example

2. Initialize the workspace with Zephyr’s west.yml as the manifest:

west init -m  git@github.com:zephyrproject-rtos/zephyr.git 

3. Run west update to download what is specified in west.yml:

west update
  • Note: Re-run west update whenever you change manifest files like west.yml.

T2: Star Topology with Application as the Manifest Repository

Ideal For: Those focusing on a single Zephyr application. This will be the most common for everyone looking into creating an application using the Zephyr project.

Directory Structure

my_zephyr_workspace/
|-- application/        # Your application
|   └── west.yml        # Manifest file
|-- modules/
|   └── external_lib/   # External library
|-- zephyr               # Zephyr RTOS repository

How to Set It Up

In this topology, your application takes center stage. Your west.yml will be in your application directory.

Here’s a sample west.yml and a possible personal repository for your project:

manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      remote: zephyrproject-rtos
      revision: v2.5.0
      import: true
  self:
    path: your_application_name            # must match your app name

Example repo:

.
├── your_application_name      # your app folder, name must match the west.yml                        
│   ├── CMakeLists.txt         # CMakeLists.txt of your app
│   ├── prj.conf               # the prj.conf of your application
│   └── src                    # src/ folder of your app
│       └── main.c             # your app main.c
├── .git                       # this is the root of your repo
├── README.md                  # readme on the root of the project
└── west.yml                   # the west.yml shown above

In this sample west.yml we set the official Zephyr RTOS GitHub repository as one of the projects that we require alongside self which is our repository (the repository where we have our application).
For this simple example, we only require Zephyr RTOS besides our repo, but for each project, we must set the exact revision we want to track, we do this with the parameter revision.
Finally, not less important is import: true this will tell west to go to the project (in this case main Zephyr RTOS project) and import all the projects that it states in its own west.yml this will allow it to also download the projects that Zephyr RTOS has within its own west.yml and for most of cases, this is mandatory.

To set all up:

1. Create a folder for your workspace:

mkdir ws_t2_example
cd ws_t2_example

2. Initialize the workspace using your repo west.yml at a specified revision:

west init -m <your_repo_url> --mr <revision: tag, branch_name, or commit_id>

3. Update the workspace:

west update

Now you have a workspace defined by the manifest file (west.yml) in your application private repository that you can modify and track in your repository as needed by your application requirements. This is the ideal setup for your own independent application.

T3: Forest Topology with Freestanding Manifest Repository

Ideal For: Developers working on multiple independent Zephyr applications with no central repository. Since they’re independent in this topology we can have a private repository that only provides an west.yml with all the independent applications and revisions listed at the same level.

Directory Structure

my_zephyr_workspace/
|-- app1/               # First application
|-- app2/               # Second application
|-- manifest-repo/      # Manifest repository
|   └── west.yml        # Manifest file
|-- modules/
|   └── external_lib/   # External library
|-- zephyr/             # Zephyr RTOS repository

How to Set It Up

A dedicated manifest repository (manifest-repo here) holds the west.yml file, listing all the projects and applications.

Here’s a sample west.yml:

manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      remote: zephyrproject-rtos
      revision: v2.5.0
    - name: app1
      revision: SOME_SHA_OR_BRANCH_OR_TAG
    - name: app2
      revision: SOME_SHA_OR_BRANCH_OR_TAG
  self:
    path: manifest-repo

To set this up, assuming you have multiple repositories with Zephyr applications:

1. Create a folder for your workspace:

mkdir ws_t3_example
cd ws_t3_example

2. Initialize the workspace using your repo’s west.yml at a specified revision:

west init -m <your_repo_url> --mr <revision: tag, branch_name, or commit_id>

3. Update the workspace:

west update
  • Note: Re-run west update whenever you change manifest files like west.yml.

Conclusion

Choosing the right Zephyr workspace topology can make your development process smoother and more efficient. While the T1 topology is often the go-to for those looking to contribute to Zephyr, the T2 and T3 topologies offer greater flexibility for application-focused development.

Sources

This guide is based on the official Zephyr documentation on supported topologies.

Hope this helps! Feel free to share your experiences, tips, and questions in the comments section below.

Leave a Reply

Your email address will not be published. Required fields are marked *