Creating an application

The process for creating an application in the nRF Connect SDK follows Zephyr’s Application Development principles and the nRF Connect SDK’s Development model and contributions. The following sections provide basic information based on these two sources.

Application structure 

Here are the files that most of the Zephyr and nRF Connect SDK applications include in its <app> directory:

<app>
├── CMakeLists.txt
├── app.overlay
├── prj.conf
├── VERSION
└── src
    └── main.c

You can read more about each of these files in Zephyr’s Application Development overview.

Application types 

Based on where the <app> directory is located, you will usually work with one of the following types of applications in the nRF Connect SDK: repository, workspace, or freestanding. These types are adopted from Zephyr application types.

Repository application 

This kind of application is located inside the nRF Connect SDK source code (SDK repositories, including downstream forks of upstream projects). In the following example, the Bluetooth Peripheral UART sample is an nRF Connect SDK repository application and its location in the source code structure serves as the <app> directory:

<home>/
├─── .west/
├─── bootloader/
├─── modules/
├─── nrf/
│    ├─── applications/
│    ├─── ...
│    └─── samples/
│       ├─── ...
│       ├─── bluetooth/
│       │  ├── ...
│       │  └── peripheral_uart/   <--- <app> directory
│       └─── ...
├─── nrfxlib/
├─── test/
├─── tools/
└─── zephyr/

This type of application uses the default nRF Connect SDK settings and configuration, which might differ from the corresponding upstream configuration. For example, a notable difference is that when building this type of applications, sysbuild is enabled by default.

This application type is suitable for the following development cases:

You want to test the solution provided by the nRF Connect SDK out-of-the-box.

For more information about applications placed inside the nRF Connect SDK source code, see the workflow 3 on the development model page.

Workspace application 

This kind of application is located inside a west workspace, but outside of the repositories of the SDK. The application placed in a workspace uses its own copy of the nRF Connect SDK. It specifies the nRF Connect SDK version through the west.yml west manifest file, which is located in the application <app> directory.

With this kind of application, the workspace has the following structure:

<home>/
└─── <west-workspace>/
   ├─── .west/
   ├─── nrf/
   ├─── zephyr/
   ├─── ...
   └─── <app>/
      ├── src/
      ├── ...
      └── west.yml

This application type is suitable for the following development cases:

You want to take advantage of west to manage your own set of repositories.
You want to make changes to one or more of the repositories of the nRF Connect SDK when working on the application.
You want to develop a project that involves more than one board target, for example using a mesh networking protocol like Matter or Bluetooth Mesh.
You want to run a big project that lets you develop most features without having to patch the nRF Connect SDK tree, for example with out-of-tree boards, drivers, or SoCs.
You want to use out-of-tree applications from the nRF Connect SDK Add-ons index.
You want to set up Continuous Integration (CI) for your application and explicitly define all dependencies (such as the nRF Connect SDK version) in the application’s west manifest file.

For more information about applications placed in workspace in the nRF Connect SDK, see the workflow 4 on the development model page.

Freestanding application 

This kind of application is handled separately from the nRF Connect SDK. It is located out-of-tree, that is outside of a west workspace, and is not using the west manifest file to specify the SDK version. The build system will find the location of the SDK through the ZEPHYR_BASE environment variable, which is set either through a script or manually in an IDE.

With this kind of application, the workspace has the following structure:

<home>/
├─── <west-workspace>/
│  ├─── .west/
│  ├─── nrf/
│  ├─── zephyr/
│  └─── ...
└─── <app>/
   ├─── src/
   └─── ...

This application type is suitable for the following development cases:

You prefer to use one copy of the nRF Connect SDK when working on one or more applications because of limited bandwidth.
You want to do quick prototyping and the results might be later deleted or migrated to an application in a workspace.

For more information about freestanding applications in the nRF Connect SDK, see the workflow 2 on the development model page.

Creating an nRF Connect SDK application 

The process for creating an nRF Connect SDK application depends on the development environment. Using nRF Connect for VS Code is the recommended method.

Note

No steps are provided for the creation of repository applications. Creating repository applications is not recommended, as placing any application in the nRF Connect SDK source file structure can corrupt the SDK installation.

Creating application in nRF Connect for VS Code 

Note

If you prefer, you can start VS Code walkthrough and create applications and build configurations from there.

Use the following steps depending on the application placement:

To create a workspace application in nRF Connect for VS Code:

Open Visual Studio Code.
Open nRF Connect for VS Code.
In the Welcome View, click the Create a new application action. A quick pick menu appears.
Choose one of the following options:
- Create a blank application - This will create an application with a code structure that you need to populate from scratch.
- Copy a sample - This will create an application from an nRF Connect SDK sample or an nRF Connect SDK application. If you have more than one version of the nRF Connect SDK installed, you have to choose the version from which you copy the sample or the application from.
Enter the location and the name for the application. The location will be the <west-workspace>/ directory mentioned in the workspace application structure. The application creation process starts after you enter the name. When the application is created, a VS Code prompt appears asking you what to do with the application.
Click Open. This will open the new application and add it to the Applications View in the extension. At this point, you have created a freestanding application.
Add the west.yml to create a west workspace around the application:
1. In the Welcome View, click the Manage SDKs action. A quick pick menu appears.
2. Click Manage West Workspace….
3. In the Manage West Workspace… action menu, click Create West Workspace.
4. Enter a location for the west.yml file that matches the location provided when you were creating the application.
5. Select the SDK version for the west workspace. The west workspace is initialized.
6. Click Manage SDKs > Manage West Workspace > West Update to update the workspace modules.

You can now start configuring and building the application.

See the extension documentation for more information about working with workspace applications in the extension.

For more information about the differences between the applications types from the extension’s perspective, see the Applications page in the extension documentation.

Creating application for use with command line 

Nordic Semiconductor recommends using the example application repository to create a workspace application, but you can also create freestanding applications.

Use the following steps depending on the application type:

This recommended process for command line takes advantage of Nordic Semiconductor’s example application template repository, similar to the example application used for creating an application in Zephyr.

Nordic Semiconductor maintains a templated example repository as a reference for users that choose this workflow, ncs-example-application. This repository showcases the following features of both the nRF Connect SDK and Zephyr:

Basic Zephyr application skeleton
Zephyr workspace applications
West T2 topology
Custom boards
Custom devicetree bindings
Out-of-tree drivers
Out-of-tree libraries
Example CI configuration (using GitHub Actions)
Custom west extension

To create a workspace application:

Open the ncs-example-application repository in your browser.
Click the Use this template button on the GitHub web user interface. This creates your own copy of the template repository. In the copy of the repository, the app directory contains the template application that you can start modifying.
Start the toolchain environment in a terminal window.
Initialize the repository with the repository name and path you have chosen for your manifest repository (your-name/your-application and your-app-workspace, respectively). your-app-workspace corresponds to ncs/ in the workspace application structure. Use the following command pattern:
```
west init -m https://github.com/your-name/your-application your-app-workspace
```
Go to the your-app-workspace directory using the following command pattern:
```
cd your-app-workspace
```
Run the following west command to download the contents of the nRF Connect SDK:
```
west update
```
west will clone the nRF Connect SDK contents next to the example application directory.

For more information, see the detailed description of the workspace application workflow.

This procedure follows Zephyr’s steps for Creating an Application by Hand and the workflow 2 on the development model page. You can copy any of the Applications or Samples in the nRF Connect SDK as your source code files.

To create a freestanding application:

Create an application directory.

For example, in a Unix shell or Windows cmd.exe prompt:
```
mkdir app
```
Warning

Building Zephyr or creating an application in a directory with spaces anywhere on the path is not supported. So the Windows path C:\Users\YourName\app will work, but C:\Users\Your Name\app will not.
Create your source code files.

It’s recommended to place all application source code in a subdirectory named src. This makes it easier to distinguish between project files and sources.

Continuing the previous example, enter:
```
cd app
mkdir src
```
Place your application source code in the src sub-directory. For this example, we’ll assume you created a file named src/main.c.
Create a file named CMakeLists.txt in the app directory with the following contents:
```
cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr)
project(my_zephyr_app)

target_sources(app PRIVATE src/main.c)
```
Notes:
- The cmake_minimum_required() call is required by CMake. It is also invoked by the Zephyr package on the next line. CMake will error out if its version is older than either the version in your CMakeLists.txt or the version number in the Zephyr package.
- find_package(Zephyr) pulls in the Zephyr build system, which creates a CMake target named app (see Zephyr CMake Package). Adding sources to this target is how you include them in the build. The Zephyr package will define Zephyr-Kernel as a CMake project and enable support for the C, CXX, ASM languages.
- project(my_zephyr_app) defines your application’s CMake project. This must be called after find_package(Zephyr) to avoid interference with Zephyr’s project(Zephyr-Kernel).
- target_sources(app PRIVATE src/main.c) is to add your source file to the app target. This must come after find_package(Zephyr) which defines the target. You can add as many files as you want with target_sources().
Create at least one Kconfig fragment for your application (usually named prj.conf) and set Kconfig option values needed by your application there. See Kconfig Configuration. If no Kconfig options need to be set, create an empty file.
Configure any devicetree overlays needed by your application, usually in a file named app.overlay. See Set devicetree overlays.
Set up any other files you may need, such as twister configuration files, continuous integration files, documentation, etc.
Export a Zephyr CMake package by running the following command from the main directory of your nRF Connect SDK repository copied during Installation:
```
 west zephyr-export
```
This allows CMake to automatically load the boilerplate code required for building nRF Connect SDK applications.

You can now start configuring and building the application using the command line.

Creating application from add-ons 

You can create a workspace application also by browsing and copying reference applications from the nRF Connect SDK Add-ons index. The index is a collection of publicly available nRF Connect SDK supplementary components that extend the SDK’s functionality. In addition to applications, it includes drivers, libraries, and protocol implementations.

To create an application from the add-on index, complete the following steps:

Complete the following steps in nRF Connect for VS Code:

In the Welcome View, click Create a new application.
Select Browse nRF Connect SDK Add-on Index.
Browse through the available add-ons and select one that matches your needs.
Follow the creation wizard to set up your workspace application.

The add-on is copied to your workspace and automatically configured with a west workspace, allowing you to start development right away.

For more information, including how to contribute your own add-on to the index, read README.md and CONTRIBUTING.md in the ncs-app-index repository.