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 - + Documentation - + API Documentation -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 ` + +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 `). + +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 `_ + +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 `_). + +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