# Working with Zephyr

Zephyr is a small real-time operating system for connected, resource-constrained and embedded devices supporting multiple architectures, published on the [Zephyr Project website](https://www.zephyrproject.org).

The purpose of this extension is to provide a full development flow experience, starting from installing tools, source repository, capability to create and manage projects, source configuration management, build and debug applications.

Starting with the release of version 3.7.0, Zephyr is adopting a new hardware model (Hardware Model v2) to resolve the limitation that a single board or SoC that has CPUs with different architectures could not be defined. The limitation was due to the existing file system hierarchy.
As a result we are now supporting both the new hardware model and the old model and user experience is intended to be similar for any of the models.

## Install dependencies

Some dependencies are needed to install in order to work with Zephyr environment. The instructions to get all needed tools are described in *Install* sections in the [Zephyr official documentation]( https://docs.zephyrproject.org/latest/develop/getting_started/index.html).

For convenience, MCUXpresso Installer offers a one step installation process for all these dependencies.

![Install Zephyr dependencies](./pictures/nxp-installer-zephyr.png)

## Import remote source repository

Similar with MCUXpresso SDK, *REMOTE GIT* tab option on the *Import repository* view will allow the user to specify the details about the remote repository.

![Install remote Zephyr](./pictures/nxp-import-zephyr.png)

By default, the revision of the latest Zephyr release is selected. If other revision is needed, check the expanded list.

![Install revision Zephyr](./pictures/nxp-zephyr-revisions.png)

By default, 'west.yml' manifest file is used to import, if other manifest file is needed check the "Use custom manifest file" checkbox and select an option.

![Install manifest file Zephyr](./pictures/nxp-zephyr-manifest.png)

## Create and build a project

Go to *Import Example* viewer as explained on [Create and build project](Create-Project).
Fulfill the fields considering Zephyr specific elements:
- **Choose a repository** - select a Zephyr repository. The listed repositories are the ones also available in IMPORTED REPOSITORIES area;
- **Choose a board** - select a desired board (the listed ones are the ones available in the loaded Zephyr repository), the board may be changed later if needed;
- **Choose a template** - select a desired project template you want to start with;
- **Application type** - select the desired application type, choose "Repository application" if you want to use the application directly in the repository folder (example's sources will not be copied), choose "Freestanding application" if you want to keep the application in a user provided location (example's sources will be copied) or "Workspace Application" if you want to keep the application in the workspace;
- **Name** - set a desired name for the project;
- **Location** - set a desired project path (this option is specific to freeestanding application type).
-  **Choose an SDK** - the listed ones are automatically identified by the extension. Pick a suitable one or use *Add Zephyr SDK* path option from the combobox;

![Zephyr import example](./pictures/nxp-zephyr-import-example.png)

Once the project is created, you can simply press *Build* button as described on [Create and build project](Create-Project) section.

## Sysbuild (System build)

Sysbuild is a higher-level build system that can be used to combine multiple other build systems together. For more details please follow [Zephyr Sysbuild (System build)](https://docs.zephyrproject.org/latest/build/sysbuild/index.html) documentation.

To enable or disable Sysbuild, go to the context menu of the project, select "Set Sysbuild" under the "Configure" group and select the desired option.

![Zephyr Set Sysbuild command](./pictures/nxp-zephyr-set-sysbuild.png)

![Zephyr Set Sysbuild options](./pictures/nxp-zephyr-set-sysbuild-options.png)

## DEVICE TREE View

Once a project is built, simply select *DEVICE TREE* from main's MCUXpresso extension view and press *Refresh*. This will create a full tree of nodes, with the ability to open the source once a node is selected.

![DEVICE TREE Viewer](./pictures/nxp-zephyr-dts.png)

In-depth usage of the DEVICE TREE view is described in the [DEVICE TREE view](Device-Tree) section.

## Kconfig graphical interface for Zephyr kernel configuration

Zephyr kernel configuration can be changed by editing zephyr/.config in the application build directory or via UI by using Kconfig graphical interface.

![Zephyr open kernel configuration](./pictures/nxp-zephyr-open-kernel_configuration.png)

To open Kconfig graphical interface go to the context menu of the project and select "Open Kconfig GUI Configuration" under the "Configure" group. If the project is newly created and the build directory doesn't exist it will be created before opening the Kconfig interface.

![Zephyr Kconfig interface](./pictures/nxp-zephyr-kconfig.png)

## Changing the associated Zephyr SDK for an existing project

When importing a project or an example from the repository you are required to choose a Zephyr SDK to be associated to the project. The associated Zephyr SDK can be modified later for an existing project. To change it, right-click on the project, navigate to "Configure", and select "Associate Zephyr SDK". For more details, please refer to the [Toolchain Management Documentation](https://github.com/nxp-mcuxpresso/vscode-for-mcux/wiki/Create-Project#toolchain-management).

![Zephyr Associate SDK](./pictures/nxp-zephyr-associate-sdk.png)

## Changing the associated repository for an existing project

You can also change the repository associated to an existing project. To do this go to the context menu of the project, select "Configure" and then "Associate Repository", you should now see all the available Zephyr repositories and select the desired value. 

![Zephyr Associate Repository](./pictures/nxp-zephyr-associate-repository.png)

## Debug the project

For debugging the project, the standard steps described in [debug](https://github.com/nxp-mcuxpresso/vscode-for-mcux/wiki/Debug) documentation section should be followed.

## Change board

To change the used board go to `Build Configuration` from the `PROJECTS` view and edit the build configuration that is currently used.
From the `Board` option identify and select the desired board. Press `Save` to apply the changes.

![Zephyr Change Optimization Level](./pictures/nxp-zephyr-change-board.png)


## Change build optimization level

To change the build optimization level go to `Build Configuration` from the `PROJECTS` view and edit the build configuration that is currently used.
From the `Optimization Level` option select the desired optimization. Press `Save` to apply the changes.

![Zephyr Change Optimization Level](./pictures/nxp-zephyr-change-optimization-lvl.png)

## Change build directory

The build directory can also be changed via the `Edit Build Configuration` view. Just type in the desired build directory under the `Build Directory` option and press `Save` to apply the changes.

![Zephyr Change Build Directory](./pictures/nxp-zephyr-change-build-dir.png)

## Change configuration file
Project configuration is managed through Kconfig configuration files (.conf files). These files allow you to customize component selection, feature enablement, and various build settings.

To change the configuration file go to `Build Configuration` from the `PROJECTS` view and edit the build configuration that is currently used.
From the `Config file` drop-down menu select one or multiple files and make your desired changes. Press `Save` to apply the changes.

These changes will be automatically reflected in the project's build configuration, and the CONF_FILE variable will be updated in the CMakePresets.json file to specify the active configuration.

![Zephyr Change Config File](./pictures/nxp-zephyr-conf-files.png)

The list of available configuration files is automatically detected by searching for .conf files in the project directory and CMakePresets.json file. If your desired configuration file is not listed, you can manually add the path using the "+ Add configuration file path" entry in the drop-down menu.

![Zephyr Change Add Config File](./pictures/nxp-zephyr-add-conf-file.png)

For detailed information about the configuration system and configuration priority, please refer to the [Zephyr Configuration System documentation](https://docs.zephyrproject.org/latest/build/kconfig/setting.html#the-initial-configuration) and the [Build System Variables guide](https://docs.zephyrproject.org/latest/develop/application/index.html#important-build-system-variables).
## Add CMake extra arguments

Additional CMake arguments not present in the Build Configuration options can be specified in the CMake Extra Args field. Press `Save` to apply the changes.

![Zephyr Change Add Extra CMake Args](./pictures/nxp-zephyr-cmake-extra-args.png)

## Using Out-of-Tree Boards

If the board you are developing is not supported by Zephyr, you can still use it without modifying the Zephyr source tree (out-of-tree board definition).

To work with your defined out-of-tree board(s), you have two options:

- **Set the BOARD_ROOT Environment Variable**:
Add the path to your custom board directory to the BOARD_ROOT environment variable. 

- **Associate the out-of-tree board Location via the Zephyr Repository View**:
In your development environment, open the context menu for your Zephyr repository entry in the Repository View, then select "Associate Out-of-Tree Board Location". 

![Zephyr associate out-of-tree boards](./pictures/nxp-zephyr-associate-out-of-tree.png)

Type or browse to the location of your custom boards directory.
Once the out-of-tree boards location is added, it will appear under your Zephyr repository in the Repository View. 

![Zephyr out-of-tree-boards-entry](./pictures/nxp-zephyr-out-of-tree-entry.png)

You can add multiple out-of-tree boards locations, and remove them as needed. To remove an out-of-tree board location: go to the repository view, select the out-of-tree board entry, open its context menu then click the "Remove Out-of-Tree board Location".

If addded as out-of-tree boards, your custom boards should now be visible:
- When importing a new example from your repository.
- When changing the board for an existing project.

![Zephyr Change Add Extra CMake Args](./pictures/nxp-zephyr-custom-boards.png)

## Project Integrated Terminal

Open MCUXpresso Terminal specific for the project using project menu -> Open in Integrated Terminal.

The opened MCUXpresso terminal will have the environment completely configured for the project and the associated repository type, including system specific variables, virtual python environment (if available), utility tools access (i.e. west, available debug probe software).
Example command to build the project appears in green. The command is constructed specific for the project and it can be used as is for a quick west build.

![Build in terminal](./pictures/nxp-terminal-zephyr-build-project.png)