Zephyr Project Template Documentation

Introduction

The purpose of this repository is to create a template for using Zephyr in designs with ST microcontrollers. I will use the Nucleo_L053R8 board because I have one available, and the intention is to explore the use of the low-power resources of this family of microcontrollers from ST with Zephyr.

Additionally, I want to add unit tests to the template using Ztest and execute the tests in a docker container using CI/CD with a GitLab runner on each commit.

Finally, I aim to control the code format using clang-format or astyle and generate the repository documentation using Doxygen.

Prerequisites

Before you begin, ensure you have the following prerequisites:

• Hardware:

• Nucleo_L053R8 board (Note: This template can be used with any compatible hardware, but it is currently tested with the Nucleo_L053R8 board)

• Software:

• Zephyr SDK
• Docker
• Git
• CMake
• Python 3.x
• West (Zephyr's meta-tool)
• Astyle (for code formatting)

• Doxygen (for generating documentation)

• Accounts:

• GitLab account (for CI/CD setup)

• Knowledge:

• Basic understanding of Zephyr RTOS
• Familiarity with Docker and GitLab CI/CD
• Basic knowledge of C/C++ programming

Repository Structure

The repository is organized as follows:

├── boards/                         # Board-specific configuration and source files.
|
├── docker/                         # Docker configuration files.
│   └── Dockerfile                  # Dockerfile for setting up the CI jobs environment.
|
├── docs/                           # Documentation directory.
│   └── ...                         # Doxygen generated docs.
|
├── include/                        # Header files directory.
│   └── ...                         # Header files for the project.
|
├── src/                            # Source code directory.
│   ├── main.c                      # Main application code.
│   └── ...                         # Additional source files.
|
├── modules/                        # Modules source code directory (maybe a git submodule).
│   ├── Template/                   # Module template.
|   |   ├── zephyr/                 # Zephyr-specific module files and configurations.
|   |   |   └── module.yaml         # Zephyr module template info metadata and configuration information.
|   |   ├── src/                    # Source folder for module implementation.
|   |   |    ├── template.c         # Module template C file containing the implementation of the module's functionality.
|   |   |    └── template.h         # Module template header file defining the module's interface and public functions.
|   |   ├── CMakeLists.txt          # CMake configuration file for building the module.
|   |   └── Kconfig                 # Configuration file for defining module-specific options.
│   └── ...                         # Other modules directories.
|
├── tests/                          # Directory containing test-related files for the project.
│   ├── Template/                   # Template module tests.
|   |   ├── src/                    # Source folder for test implementation files.
|   |   |   └── test_template.c     # C file containing the module test implementation.
|   |   ├── CMakeLists.txt          # CMake configuration file for building the test suite.
|   |   ├── prj.conf                # Configuration file for defining test-specific options.
|   |   └── testcase.yaml           # YAML file describing the test cases and their configurations.
│   └── ...                         # Other modules tests.
|
├── scripts/                        # Utility scripts.
│   └── ...                         # Scripts for formating code and git hooks.
|
├── .astylerc                       # Astyle configuration file for code formatting.
├── .gitignore                      # Specifies files and directories to be ignored by Git.
├── .gitlab-ci.yml                  # GitLab CI/CD configuration file.
├── CMakeLists.txt                  # CMake build configuration file.
├── Doxyfile                        # Doxygen configuration.
├── LICENSE                         # License file for the project.
├── prj.conf                        # Project configuration file for Zephyr.
└── README.md                       # Project documentation. (This file)

Cloning the Repository

To properly clone this repository, follow these steps:

1. Open a terminal on your system.
2. Use the git clone command to clone the repository: shell git clone https://gitlab.com/amoralesruiz/stm32l0_zephyr_template.git You are now ready to start working with the repository.

Setting Up the Development Environment

To set up the Zephyr development environment, follow these steps:

1. Install Required Tools:
2. Install Docker, Git, CMake, and Python 3.x using your system's package manager.Zephyr Getting Started Guide. shell sudo apt install --no-install-recommends git cmake ninja-build gperf \ ccache dfu-util device-tree-compiler wget doxygen\ python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1
3. Install virtual environment for python and create one env for zephyr python tools Zephyr python environment shell sudo apt install python3-venv python3 -m venv ~/zephyrproject/.venv source ~/zephyrproject/.venv/bin/activate

4. Install West, Zephyr's meta-tool, by running: shell pip install west

5. Initialize the Zephyr Workspace:

6. Create a directory for your Zephyr workspace: shell mkdir zephyrproject cd zephyrproject
7. Clone the Zephyr repository: shell west init ~/zephyrproject cd ~/zephyrproject west update

8. Export Zephyr environment variables: shell west zephyr-export

9. Install Python Dependencies:

10. Navigate to the Zephyr directory and install required Python dependencies: shell west packages pip --install

11. Add ZEPHYR path to bash*

12. Edit your bash file shell nano ~/.bashrc
13. Add this lines to the end of the file shell export ZEPHYR_BASE=~/zephyrproject/zephyr export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0/ export ZEPHYR_TOOLCHAIN_VARIANT=zephyr

14. Load changes shell source ~/.bashrc

15. Verify the Installation:

16. Test your setup by listing all west packages: shell west list

For more details, visit the Zephyr Project Documentation.

Building the Project

• Build native_sim aplication shell west build -p always -b native_sim

Running Unit Tests with ztest

• Run ztest with twister shell west twister -T ./tests -p native_sim

Continuous Integration and Deployment (CI/CD)

The CI/CD setup uses a local runner that executes various jobs within a local Docker container. This approach ensures a consistent and isolated environment for running tasks, leveraging the Docker image built specifically for the Zephyr environment.

Generate the Docker image containing a Zephyr environment

1. Navigate to the template directory and enter the docker directory containing the generation Dockerfile: This step takes a while. shell cd docker docker build -t zephyr-runner .
2. Check the image is available. shell docker images
3. Run the Docker image shell docker run -it --rm --name zephyr-runner zephyr-runner /bin/bash
4. Test west in the container shell west list
5. Exit the container. shell exit

Setting Up a Local GitLab Runner

This template uses a GitLab Runner to execute CI/CD jobs. For more details about GitLab Runners, refer to the GitLab Runners Documentation.

To install and configure a local GitLab Runner, follow these steps:

1. Download the GitLab Runner Binary:

2. Open a terminal and download the latest GitLab Runner binary for your operating system: shell curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

3. Set Permissions:

4. Make the binary executable: shell chmod +x /usr/local/bin/gitlab-runner

5. Install GitLab Runner as a Service:

6. Install and start GitLab Runner as a system service: shell gitlab-runner install gitlab-runner start

7. Register the GitLab Runner:

8. Register the runner with your GitLab instance by running: shell gitlab-runner register

9. During registration, provide the following details:

   • GitLab URL: The URL of your GitLab instance (e.g., https://gitlab.com).
   • Registration Token: Found in your GitLab project under Settings > CI/CD > Runners.
   • Runner Description: A name for the runner (e.g., local-runner).
   • Tags: Tags to identify the runner (e.g., build,test).
   • Executor: Select shell as the executor type.

10. Verify the Runner:

11. Navigate to your GitLab project under Settings > CI/CD > Runners to confirm the runner is active and registered.

For additional details, refer to the GitLab Runner Installation Guide.

1. Test the Runner:

2. Add a test .gitlab-ci.yml file to your repository with a simple pipeline: ```yaml stages:

   • build
   • test

   build: stage: build script: - echo "Compiling the project..." - sleep 5 - echo "Compilation successful"

   test: stage: test script: - echo "Running tests with Twister..." - sleep 5 - echo "Tests completed" ``` - Commit the file and push it to your repository. The runner should pick up the job and execute it.

Adding New Modules

To create and integrate new modules into the project structure, follow these steps:

1. Create a New Module Directory:
2. Navigate to the modules/ directory:

3. Create a new directory for your module:

4. Set Up the Module Structure:

5. Use the Template module as a reference to structure your new module. The directory should include the following: ├── zephyr/ # Zephyr-specific module files and configurations. │ └── module.yaml # Metadata and configuration information for the module. ├── src/ # Source folder for module implementation. │ ├── <module>.c # C file containing the implementation of the module's functionality. │ └── <module>.h # Header file defining the module's interface and public functions. ├── CMakeLists.txt # CMake configuration file for building the module. └── Kconfig # Configuration file for defining module-specific options.

6. Edit module.yaml:

7. Update the module.yaml file in the zephyr/ directory with the appropriate metadata for your module. For example: yaml name: <ModuleName> build: cmake: ./ kconfig: Kconfig

8. Implement Module Functionality:

9. Write the implementation of your module in the <module>.c file.

10. Define the module's public interface in the <module>.h file.

11. Configure CMake:

12. Update the CMakeLists.txt file to include the source files and dependencies for your module. For example: ```cmake # add the module source files directory zephyr_include_directories(${CMAKE_CURRENT_SOURCE_DIR}/src)

    add the module source files

    zephyr_library_sources(${CMAKE_CURRENT_SOURCE_DIR}/src/.c) ```

13. Define Module Options:

14. Use the Kconfig file to define configuration options specific to your module. For example: kconfig config <MODULE_NAME> bool "Enable <ModuleName>" default y help Enable the <ModuleName> module.

15. Integrate the Module:

16. Add the module to the project by including it in the CMakeLists.txt file of the main application or other modules that depend on it. cmake set(ZEPHYR_EXTRA_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/modules/<ModuleName>")

17. Test the Module:

18. Create a corresponding test directory under tests/ (e.g., tests/<ModuleName>).

19. Follow the structure of the Template module tests to implement unit tests for your module.

20. Build and Verify:

21. Build the project to ensure the module is correctly integrated: shell west build -p always -b <board_name>
22. Run the tests to verify the module's functionality: shell west twister -T ./tests -p <board_name>

Generate the Code Docs

To generate the code documentation using Doxygen, follow these steps:

1. Install Doxygen: Ensure Doxygen is installed on your system. You can install it using your package manager:

sudo apt install doxygen

1. Locate the Doxyfile: The Doxyfile configuration file is located in the root of the repository.

2. Generate the Documentation: Run the following command in the repository root to generate the documentation:

doxygen Doxyfile

1. View the Documentation: The generated documentation will be available in the docs/ directory. Open the index.html file in a web browser to view the documentation.

2. Export the documentation to a PDF file

To export the documentation to a PDF file, follow these steps:

Ensure that LaTeX and the required tools are installed on your system. You can install them using your package manager:

sudo apt install texlive texlive-latex-extra texlive-fonts-recommended latexmk

Navigate to the LaTeX Directory and run the make command to compile the LaTeX files and generate the PDF:

cd docs/latex
make pdf

After the process completes, the generated PDF file will be available in the same directory. Look for a file named refman.pdf.

For more details on configuring and using Doxygen, refer to the Doxygen Manual. For more details on LaTeX and troubleshooting, refer to the LaTeX Project Documentation.

Debugging and Troubleshooting

TODO: Provide tips and common solutions for debugging and resolving issues during development.

Contributing Guidelines

TODO: Define the process for contributing to the project, including code style, pull requests, and issue tracking.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Additional Resources

TODO: List references, documentation links, and any further reading materials for users and contributors.