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/
├─── mbedtls/
├─── 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, SoCs, and so on.

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. Instead, the nRF Connect SDK version is taken from the ZEPHYR_BASE environment variable. This means that all freestanding applications will use the same nRF Connect SDK version and the same copy of the SDK.

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 the nRF Connect for VS Code extension 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 the nRF Connect for VS Code extension

Use the following steps depending on the application placement:

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

  1. Open Visual Studio Code.

  2. Open the nRF Connect for VS Code extension.

  3. In the Welcome View, click the Create a new application action. A quick pick menu appears.

  4. 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.

  5. 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.

  6. Click Open. This opens the new application and adds it to the Applications View in the extension. At this point, you have created a freestanding application.

  7. 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 Create west workspace.

    3. Enter a location for the west.yml file that matches the location provided in step 4.

    4. Select the SDK version for the west workspace. The west workspace is initialized and the Manage SDKs action changes to Manage west workspace.

    5. Click Manage west workspace and select West Update button to update the workspace modules.

You can now start configuring and building the application.

See the extension documentation for more information about west workspace and workspace applications in the extension.

See the extension documentation for more information about the differences between the applications types from the extension’s perspective.

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:

To create a workspace application:

  1. Open the ncs-example-application repository in your browser.

  2. 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.

  3. Start the toolchain environment in a terminal window.

  4. 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
  5. Go to the your-app-workspace directory using the following command pattern:

    cd your-app-workspace
  6. 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.

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