diff --git a/.github/workflows/build-using-docker.yml b/.github/workflows/build-using-docker.yml
new file mode 100644
index 0000000..1817f95
--- /dev/null
+++ b/.github/workflows/build-using-docker.yml
@@ -0,0 +1,40 @@
+name: Build and test app in NCS docker container
+
+on:
+ pull_request:
+
+jobs:
+ build-and-test-in-docker:
+ runs-on: ubuntu-22.04
+ container: ghcr.io/nrfconnect/sdk-nrf-toolchain:v2.6.99
+ defaults:
+ run:
+ # Bash shell is needed to set toolchain related environment variables in docker container
+ # It is a workaround for GitHub Actions limitation https://github.com/actions/runner/issues/1964
+ shell: bash
+ steps:
+ - name: Checkout repository with example application
+ uses: actions/checkout@v4
+ with:
+ path: example-application
+
+ - name: Prepare west project
+ run: |
+ west init -l example-application
+ west update -o=--depth=1 -n
+
+ - name: Build firmware
+ working-directory: example-application
+ run: |
+ west twister -T app -v --inline-logs --integration
+
+ - name: Store hex files
+ uses: actions/upload-artifact@v4
+ with:
+ name: built-applications
+ path: example-application/twister-out/**/zephyr/zephyr.hex
+
+ - name: Twister Tests
+ working-directory: example-application
+ run: |
+ west twister -T tests -v --inline-logs --integration
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index 8df701c..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,49 +0,0 @@
-name: Build
-
-on:
- push:
- pull_request:
- schedule:
- - cron: "0 0 * * *"
-
-jobs:
- build:
- strategy:
- fail-fast: false
- matrix:
- os: [ubuntu-22.04, macos-12, macos-14, windows-2022]
- runs-on: ${{ matrix.os }}
- steps:
- - name: Checkout
- uses: actions/checkout@v3
- with:
- path: example-application
-
- - name: Set up Python
- uses: actions/setup-python@v4
- with:
- python-version: 3.11
-
- - name: Setup Zephyr project
- uses: zephyrproject-rtos/action-zephyr-setup@v1
- with:
- app-path: example-application
- toolchains: arm-zephyr-eabi
-
- - name: Build firmware
- working-directory: example-application
- shell: bash
- run: |
- if [ "${{ runner.os }}" = "Windows" ]; then
- EXTRA_TWISTER_FLAGS="--short-build-path -O/tmp/twister-out"
- fi
- west twister -T app -v --inline-logs --integration $EXTRA_TWISTER_FLAGS
-
- - name: Twister Tests
- working-directory: example-application
- shell: bash
- run: |
- if [ "${{ runner.os }}" = "Windows" ]; then
- EXTRA_TWISTER_FLAGS="--short-build-path -O/tmp/twister-out"
- fi
- west twister -T tests -v --inline-logs --integration $EXTRA_TWISTER_FLAGS
diff --git a/CODEOWNERS b/CODEOWNERS
new file mode 100644
index 0000000..96ae659
--- /dev/null
+++ b/CODEOWNERS
@@ -0,0 +1 @@
+* @gmarull @carlescufi
diff --git a/README.md b/README.md
index 5cae4c5..b87bdc6 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,15 @@
-# Zephyr Example Application
+# nRF Connect SDK example application
-<a href="https://zephyrproject-rtos.github.io/example-application">
+<a href="https://nrfconnect.github.io/ncs-example-application">
<img alt="Documentation" src="https://img.shields.io/badge/documentation-3D578C?logo=sphinx&logoColor=white">
</a>
-<a href="https://zephyrproject-rtos.github.io/example-application/doxygen">
+<a href="https://nrfconnect.github.io/ncs-example-application/doxygen">
<img alt="API Documentation" src="https://img.shields.io/badge/API-documentation-3D578C?logo=c&logoColor=white">
</a>
-This repository contains a Zephyr example application. The main purpose of this
-repository is to serve as a reference on how to structure Zephyr-based
-applications. Some of the features demonstrated in this example are:
+This repository contains an nRF Connect SDK example application. The main
+purpose of this repository is to serve as a reference on how to structure nRF Connect
+SDK based applications. Some of the features demonstrated in this example are:
- Basic [Zephyr application][app_dev] skeleton
- [Zephyr workspace applications][workspace_app]
@@ -23,12 +23,12 @@ applications. Some of the features demonstrated in this example are:
- Custom [west extension][west_ext]
- Doxygen and Sphinx documentation boilerplate
-This repository is versioned together with the [Zephyr main tree][zephyr]. This
-means that every time that Zephyr is tagged, this repository is tagged as well
+This repository is versioned together with the [nRF Connect SDK main tree][sdk-nrf]. This
+means that every time that nRF Connect SDK is tagged, this repository is tagged as well
with the same version number, and the [manifest](west.yml) entry for `zephyr`
-will point to the corresponding Zephyr tag. For example, the `example-application`
-v2.6.0 will point to Zephyr v2.6.0. Note that the `main` branch always
-points to the development branch of Zephyr, also `main`.
+will point to the corresponding nRF Connect SDK tag. For example, the `ncs-example-application`
+v2.5.0 will point to nRF Connect SDK v2.5.0. Note that the `main` branch always
+points to the development branch of nRF Connect SDK, also `main`.
[app_dev]: https://docs.zephyrproject.org/latest/develop/application/index.html
[workspace_app]: https://docs.zephyrproject.org/latest/develop/application/index.html#zephyr-workspace-app
@@ -37,25 +37,25 @@ points to the development branch of Zephyr, also `main`.
[board_porting]: https://docs.zephyrproject.org/latest/guides/porting/board_porting.html
[bindings]: https://docs.zephyrproject.org/latest/guides/dts/bindings.html
[drivers]: https://docs.zephyrproject.org/latest/reference/drivers/index.html
-[zephyr]: https://github.com/zephyrproject-rtos/zephyr
+[sdk-nrf]: https://github.com/nrfconnect/sdk-nrf
[west_ext]: https://docs.zephyrproject.org/latest/develop/west/extensions.html
-## Getting Started
+## Getting started
-Before getting started, make sure you have a proper Zephyr development
-environment. Follow the official
-[Zephyr Getting Started Guide](https://docs.zephyrproject.org/latest/getting_started/index.html).
+Before getting started, make sure you have a proper nRF Connect SDK development environment.
+Follow the official
+[Installation guide](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/installation/install_ncs.html).
### Initialization
The first step is to initialize the workspace folder (``my-workspace``) where
-the ``example-application`` and all Zephyr modules will be cloned. Run the following
+the ``example-application`` and all nRF Connect SDK modules will be cloned. Run the following
command:
```shell
-# initialize my-workspace for the example-application (main branch)
-west init -m https://github.com/zephyrproject-rtos/example-application --mr main my-workspace
-# update Zephyr modules
+# initialize my-workspace for the ncs-example-application (main branch)
+west init -m https://github.com/nrfconnect/ncs-example-application --mr main my-workspace
+# update nRF Connect SDK modules
cd my-workspace
west update
```
@@ -71,9 +71,8 @@ west build -b $BOARD app
where `$BOARD` is the target board.
-You can use the `custom_plank` board found in this
-repository. Note that Zephyr sample boards may be used if an
-appropriate overlay is provided (see `app/boards`).
+You can use the `custom_plank` board found in this repository. Note that you can use
+Zephyr and nRF Connect SDK sample boards if an appropriate overlay is provided (see `app/boards`).
A sample debug configuration is also provided. To apply it, run the following
command:
diff --git a/app/boards/nucleo_f302r8.overlay b/app/boards/nucleo_f302r8.overlay
deleted file mode 100644
index 279e356..0000000
--- a/app/boards/nucleo_f302r8.overlay
+++ /dev/null
@@ -1,27 +0,0 @@
-/*
- * Copyright (c) 2021 Nordic Semiconductor ASA
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/* This devicetree overlay file will be automatically picked by the Zephyr
- * build system when building the sample for the nucleo_f302r8 board. It shows
- * how the example-application can be built on sample boards already provided
- * by Zephyr.
- */
-
-/ {
- example_sensor: example-sensor {
- compatible = "zephyr,example-sensor";
- input-gpios = <&gpioc 13 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
- };
-
- blink_led: blink-led {
- compatible = "blink-gpio-led";
- led-gpios = <&gpiob 13 GPIO_ACTIVE_HIGH>;
- blink-period-ms = <1000>;
- };
-};
-
-&gpioc {
- status = "okay";
-};
diff --git a/app/sample.yaml b/app/sample.yaml
index 582bb8f..09708b3 100644
--- a/app/sample.yaml
+++ b/app/sample.yaml
@@ -3,12 +3,12 @@
# so that you can easily test all of them locally or in CI.
sample:
description: Example application
- name: example-application
+ name: example-application
common:
+ sysbuild: true
build_only: true
integration_platforms:
- custom_plank
- - nucleo_f302r8
tests:
app.default: {}
app.debug:
diff --git a/doc/Doxyfile b/doc/Doxyfile
index 2c744db..cade097 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -42,7 +42,7 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places.
# The default value is: My Project.
-PROJECT_NAME = "Example Application"
+PROJECT_NAME = "NCS Example Application"
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
@@ -54,7 +54,7 @@ PROJECT_NUMBER = 1.0.0
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.
-PROJECT_BRIEF = A Zephyr-based example application
+PROJECT_BRIEF = An NCS-based example application
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
# in the documentation. The maximum height of the logo should not exceed 55
diff --git a/doc/_doxygen/main.md b/doc/_doxygen/main.md
index 10402ea..33943f7 100644
--- a/doc/_doxygen/main.md
+++ b/doc/_doxygen/main.md
@@ -1,5 +1,5 @@
# Introduction
-This is the Doxygen documentation for [example-application].
+This is the Doxygen documentation for [ncs-example-application].
-[example-application]: https://github.com/zephyrproject-rtos/example-application
+[ncs-example-application]: https://github.com/nrfconnect/ncs-example-application
diff --git a/doc/about.rst b/doc/about.rst
new file mode 100644
index 0000000..7c359bb
--- /dev/null
+++ b/doc/about.rst
@@ -0,0 +1,78 @@
+.. _example_about:
+
+About the Example Application
+#############################
+
+.. contents::
+ :local:
+ :depth: 2
+
+The About page is where more detailed information about the application should be placed.
+For this example, it contains information on the documentation structure.
+
+Table of contents
+*****************
+
+When a page other than the landing page is long and contains headers, you should also add a table of contents to that page.
+To generate the table of contents, add the following after the page title:
+
+.. code-block:: RST
+
+ .. contents::
+ :local:
+ :depth: 2
+
+.. _example_about_naming:
+
+Naming page files and page links
+********************************
+
+When naming the file for a page, use simple and descriptive names.
+Keep in mind that the file name will also be visible in the URL.
+
+You should attach a reference target to every every page title as well.
+The reference target is used when linking from one page to another.
+In most cases, it's good to match the reference target to the page name, as this makes it easier to know which page is linked when the target is used.
+For example, the the reference target for this page is ``example_about``, and it is defined with the following line just before the page title:
+
+.. code-block:: RST
+
+ .. _example_about:
+
+If you want to link to a subheading on a page, you should also add a reference target for that heading.
+The best practice for naming subheading reference targets is to use the page reference target and add some or all of the heading.
+For example, the reference target for this section is ``example_about_naming``, and it is defined in the same way as the page reference target.
+
+When you want to link to a reference target, you can use either of the following:
+
+.. code-block:: RST
+
+ :ref:`example_about`
+ :ref:`replaced link text <example_about>`
+
+The first one uses the name of the heading or title that is linked (:ref:`example_about`), while the second one replaces that with a custom link text (:ref:`replaced link text <example_about>`).
+
+External links
+==============
+
+For links outside of the documentation set, use the :file:`links.txt` file.
+This file makes it easier to update and re-use links.
+Define the links according to the existing examples, then use either of the following to place the link in the text:
+
+.. code-block:: RST
+
+ `nRF Connect SDK`_
+ `replaced link text <nRF Connect SDK_>`_
+
+The first one uses the name of the link (`nRF Connect SDK`_), while the second one replaces that with a custom link text (`replaced link text <nRF Connect SDK_>`_).
+
+Recommended pages
+*****************
+
+In addition to the About page, the following pages are recommended for all applications.
+
+Requirements and setup
+ The :ref:`example_setup` details what the user needs to have so they can work with the application.
+
+Release notes
+ The release notes page documents changes for each release.
diff --git a/doc/conf.py b/doc/conf.py
index 0cb5ccc..738f304 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -6,15 +6,15 @@
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-project = 'Example Application'
-copyright = '2024, The Zephyr Community'
-author = 'The Zephyr Community'
+project = 'NCS Example Application'
+copyright = '2024, Nordic Semiconductor'
+author = 'Nordic Semiconductor'
release = '1.0.0'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-extensions = ['sphinx.ext.intersphinx', 'breathe']
+extensions = ['breathe']
templates_path = ['_templates']
exclude_patterns = ['_build_sphinx', 'Thumbs.db', '.DS_Store']
@@ -22,12 +22,7 @@
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-html_theme = 'alabaster'
-
-# -- Options for Intersphinx -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
-
-intersphinx_mapping = {'zephyr': ('https://docs.zephyrproject.org/latest/', None)}
+html_theme = 'sphinx_ncs_theme'
## -- Options for Breathe ----------------------------------------------------
# https://breathe.readthedocs.io/en/latest/index.html
@@ -35,6 +30,11 @@
# WARNING: please, check breathe maintainership status before using this
# extension in production!
-breathe_projects = {'example-application': '_build_doxygen/xml'}
-breathe_default_project = 'example-application'
+breathe_projects = {'ncs-example-application': '_build_doxygen/xml'}
+breathe_default_project = 'ncs-example-application'
breathe_default_members = ('members', )
+
+# Include following files at the end of each .rst file.
+rst_epilog = """
+.. include:: /links.txt
+"""
diff --git a/doc/drivers/blink.rst b/doc/drivers/blink.rst
index 8f67edf..f94e0d8 100644
--- a/doc/drivers/blink.rst
+++ b/doc/drivers/blink.rst
@@ -1,14 +1,16 @@
+.. _example_driver_blink:
+
Blink
-=====
+#####
.. doxygengroup:: drivers_blink
Driver operations
------------------
+*****************
.. doxygengroup:: drivers_blink_ops
Public API
-----------
+**********
.. doxygengroup:: drivers_blink_api
diff --git a/doc/drivers/index.rst b/doc/drivers/index.rst
index a287e41..d104185 100644
--- a/doc/drivers/index.rst
+++ b/doc/drivers/index.rst
@@ -1,9 +1,13 @@
+.. _example_drivers:
+
Drivers
-=======
+#######
+
+This is an example for documenting drivers.
.. doxygengroup:: drivers
.. toctree::
- :maxdepth: 1
+ :maxdepth: 1
- blink
+ blink
diff --git a/doc/index.rst b/doc/index.rst
index 54f0f0b..4af9ef0 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,18 +1,19 @@
-Welcome to Example Application's documentation!
-===============================================
+.. _exaple_index:
-This is a simple Sphinx documentation setup for ``example-application``.
+Welcome to NCS Example Application's documentation!
+###################################################
+
+This is a simple Sphinx documentation setup for ``ncs-example-application``.
+You can use this as a template for your own application's documentation.
+
+This landing page should be a brief description what the application does, but does not need to go into full detail.
.. toctree::
:maxdepth: 2
:caption: Contents
+ about
+ setup
drivers/index
lib/index
- zephyr
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
+ release-notes
diff --git a/doc/lib/custom.rst b/doc/lib/custom.rst
index b2261ef..93293e4 100644
--- a/doc/lib/custom.rst
+++ b/doc/lib/custom.rst
@@ -1,11 +1,13 @@
+.. _example_lib_custom:
+
Custom
-======
+######
.. doxygengroup:: lib_custom
:desc-only:
Public API
-----------
+**********
.. doxygengroup:: lib_custom
- :content-only:
\ No newline at end of file
+ :content-only:
diff --git a/doc/lib/index.rst b/doc/lib/index.rst
index 1e46b5a..65f93a2 100644
--- a/doc/lib/index.rst
+++ b/doc/lib/index.rst
@@ -1,9 +1,13 @@
+.. _example_lib:
+
Libraries
-=========
+#########
+
+This is an example for documenting libraries.
.. doxygengroup:: lib
.. toctree::
- :maxdepth: 1
+ :maxdepth: 1
- custom
+ custom
diff --git a/doc/links.txt b/doc/links.txt
new file mode 100644
index 0000000..0b378e8
--- /dev/null
+++ b/doc/links.txt
@@ -0,0 +1,7 @@
+.. ### nRF Connect SDK documentation
+
+.. _`nRF Connect SDK`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/index.html
+.. _`Installing the nRF Connect SDK`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/installation/install_ncs.html
+
+.. _`Known issues for the nRF Connect SDK`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/known_issues.html
+.. _`Release notes for the nRF Connect SDK`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/release_notes.html
diff --git a/doc/release-notes.rst b/doc/release-notes.rst
new file mode 100644
index 0000000..5e8c512
--- /dev/null
+++ b/doc/release-notes.rst
@@ -0,0 +1,34 @@
+.. _example_release_notes:
+
+Release notes
+#############
+
+.. contents::
+ :local:
+ :depth: 2
+
+All the notable changes to this application are listed here.
+
+To follow the nRF Connect SDK style for release notes, group entries for Added, Changed, and Removed under a single bullet.
+
+.. _example_release_xx:
+
+Example Application - vX.X
+**************************
+
+* Changed:
+
+ * Feature two to handle both something and another function.
+ * Feature one to do a completely different thing.
+
+.. _example_release_xy:
+
+Example Application - vX.Y
+**************************
+
+* Added:
+
+ * Feature one, which is used to do something.
+ * Feature two, which is used for another function.
+
+* Removed feature three.
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 7f36028..89cee5f 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,2 +1,3 @@
Sphinx
breathe
+sphinx-ncs-theme==0.7.4
diff --git a/doc/setup.rst b/doc/setup.rst
new file mode 100644
index 0000000..091e718
--- /dev/null
+++ b/doc/setup.rst
@@ -0,0 +1,36 @@
+.. _example_setup:
+
+Requirements and setup
+######################
+
+This page outlines the requirements that you need to meet before you start working with [application/technology].
+
+If extensive information is required, create a Setting up [application] page instead, with sub pages for requirements and setting up different parts.
+See the `Setting up the Sidewalk environment`_ page of the nRF Connect SDK Amazon Sidewalk documentation for an example.
+
+Hardware requirements
+*********************
+
+To work with [application/technology], you need one/two of the following:
+
+* link to device product page
+* link to device product page
+
+Add any additional information on the devices after the list.
+
+If the user needs a smartphone or tablet to run an app, mention it both here and in the software requirements.
+
+List any optional devices last.
+
+Software requirements
+*********************
+
+To work with [application/technology], you need to install [link to application].
+
+If there are options, make a bullet list for those options.
+
+List any optional software last.
+
+If there are additional instructions on how the user needs to install or configure the software, create a subheading with the software's name and add the information there.
+
+.. _`Setting up the Sidewalk environment`: https://docs.nordicsemi.com/bundle/sidewalk_latest/page/setting_up_sidewalk_environment/setting_up_hardware.html
diff --git a/doc/zephyr.rst b/doc/zephyr.rst
deleted file mode 100644
index 778ea28..0000000
--- a/doc/zephyr.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-Zephyr
-======
-
-You can reference Zephyr documentation items, like
-:external+zephyr:ref:`getting_started` or :external+zephyr:c:func:`k_sleep`.
\ No newline at end of file
diff --git a/west.yml b/west.yml
index 6bb551c..18b85f9 100644
--- a/west.yml
+++ b/west.yml
@@ -6,17 +6,12 @@ manifest:
west-commands: scripts/west-commands.yml
remotes:
- - name: zephyrproject-rtos
- url-base: https://github.com/zephyrproject-rtos
+ - name: ncs
+ url-base: https://github.com/nrfconnect
projects:
- - name: zephyr
- remote: zephyrproject-rtos
+ - name: nrf
+ remote: ncs
+ repo-path: sdk-nrf
revision: main
- import:
- # By using name-allowlist we can clone only the modules that are
- # strictly needed by the application.
- name-allowlist:
- - cmsis # required by the ARM port
- - hal_nordic # required by the custom_plank board (Nordic based)
- - hal_stm32 # required by the nucleo_f302r8 board (STM32 based)
+ import: true