diff --git a/.github/workflows/build-using-docker.yml b/.github/workflows/build-using-docker.yml new file mode 100644 index 0000000..8333989 --- /dev/null +++ b/.github/workflows/build-using-docker.yml @@ -0,0 +1,65 @@ +name: Build and test app in NCS docker container + +on: + pull_request: + push: + branches: + - main + - 'v*-branch' + +jobs: + set-image-tag: + runs-on: ubuntu-24.04 + outputs: + IMAGE_TAG: ${{ steps.set-output.outputs.IMAGE_TAG }} + steps: + - name: Checkout repository with example application + uses: actions/checkout@v4 + with: + path: example-application + + - name: Prepare west project + run: | + python3 -m pip install west + west init -l example-application + west update -o=--depth=1 -n nrf + + - name: Find toolchain bundle id + id: set-output + run: echo "IMAGE_TAG=$(./nrf/scripts/print_toolchain_checksum.sh)" >> $GITHUB_OUTPUT + + build-and-test-in-docker: + needs: set-image-tag + runs-on: ubuntu-24.04 + container: ghcr.io/nrfconnect/sdk-nrf-toolchain:${{ needs.set-image-tag.outputs.IMAGE_TAG }} + 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-using-toolchain-bundle.yml b/.github/workflows/build-using-toolchain-bundle.yml new file mode 100644 index 0000000..30bef52 --- /dev/null +++ b/.github/workflows/build-using-toolchain-bundle.yml @@ -0,0 +1,41 @@ +name: Build and test app in toolchain bundle environment + +on: + pull_request: + push: + branches: + - main + - 'v*-branch' + +jobs: + build-and-test-in-toolchain-bundle: + runs-on: ubuntu-24.04 + steps: + - name: Checkout repository with example application + uses: actions/checkout@v4 + with: + path: example-application + + - name: Prepare west project + run: | + python3 -m pip install west + west init -l example-application + west update -o=--depth=1 -n + + - name: Setup ncs toolchain + id: setup-toolchain + uses: nrfconnect/action-ncs-toolchain-setup@main + with: + nrf-path: nrf + + - name: Build firmware + run: | + ./nrfutil sdk-manager toolchain launch \ + --toolchain-bundle-id ${{steps.setup-toolchain.outputs.toolchain-bundle-id}} \ + --chdir example-application -- 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 diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index af53072..0000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,55 +0,0 @@ -name: Build - -on: - push: - pull_request: - schedule: - - cron: "0 0 * * *" - -permissions: - contents: read - -jobs: - build: - name: Build app and tests - strategy: - fail-fast: false - matrix: - os: [ubuntu-22.04, macos-14, macos-15-intel, windows-2022] - runs-on: ${{ matrix.os }} - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - path: example-application - persist-credentials: false - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: 3.12 - - - name: Setup Zephyr project - uses: zephyrproject-rtos/action-zephyr-setup@v1 - with: - app-path: example-application - toolchains: arm-zephyr-eabi - ccache-cache-key: ${{ matrix.os }} - - - 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/.github/workflows/src-mirror.yml b/.github/workflows/src-mirror.yml new file mode 100644 index 0000000..f6613db --- /dev/null +++ b/.github/workflows/src-mirror.yml @@ -0,0 +1,41 @@ +name: src-mirror + +on: + workflow_dispatch: + inputs: + git-ref: + description: 'Branch, tag or SHA to checkout' + required: true + default: 'main' + push: + tags: + - '*' + pull_request: + types: + - opened + - synchronize + paths: + - .github/workflows/src-mirror.yml + +concurrency: + group: src-mirror-${{ github.ref }} + cancel-in-progress: true + + # Tar entire project west workspace, prune, and upload to artifact service. +jobs: + standard: + runs-on: + - runs-on=${{ github.run_id }} + - runner=16cpu-linux-x64 + steps: + - name: Upload src.tar.gz + uses: nrfconnect/action-src-mirror@main + with: + path: 'ncs-example-application' + west-update-args: '' + artifactory-path: >- + ${{ (github.ref_type != 'tag') && + format('ncs-src-mirror/internal/{0}/{1}/src.tar.gz', github.event.repository.name, github.ref_name) || + format('ncs-src-mirror/external/{0}/{1}/src.tar.gz', github.event.repository.name, github.ref_name) }} + artifactory-user: ${{ secrets.COM_NORDICSEMI_FILES_USERNAME }} + artifactory-pass: ${{ secrets.COM_NORDICSEMI_FILES_PASSWORD }} 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 ceb2c51..bdd1519 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ -# 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] @@ -30,12 +30,12 @@ applications. Some of the features demonstrated in this example are: - Custom [Zephyr runner][runner_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 @@ -44,27 +44,46 @@ 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 [runner_ext]: https://docs.zephyrproject.org/latest/develop/modules.html#external-runners -## 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 -command: +This section represents alternative approaches for initializing the workspace. + +#### Initialize workspace from scratch + +The first step is to initialize the workspace folder (``ncs``) where +the ``ncs-example-application`` and all nRF Connect SDK modules will be cloned. +Run the following commands: + +```shell +# Initialize ncs for the ncs-example-application (main branch) +west init -m https://github.com/nrfconnect/ncs-example-application --mr main ncs +# Update nRF Connect SDK modules +cd ncs +west update +``` + +#### Add application into existing nRF Connect SDK workspace + +Assume you have an existing nRF Connect SDK workspace in the ``ncs`` folder. Run the following commands: ```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 -cd my-workspace +# Navigate to the workspace folder +cd ncs +# Clone application repository +git clone https://github.com/nrfconnect/ncs-example-application +# Set manifest path to the application directory +west config manifest.path ncs-example-application +# Update nRF Connect SDK modules west update ``` @@ -79,9 +98,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/nrf54l15dk_nrf54l15_cpuapp.overlay b/app/boards/nrf54l15dk_nrf54l15_cpuapp.overlay new file mode 100644 index 0000000..fc66f78 --- /dev/null +++ b/app/boards/nrf54l15dk_nrf54l15_cpuapp.overlay @@ -0,0 +1,23 @@ +/* + * Copyright (c) 2025 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 nRF54l15 DK (cpuapp) board. + * It shows how the ncs-example-application can be built on sample boards + * already provided by Zephyr or NCS. + */ + +/ { + example_sensor: example-sensor { + compatible = "zephyr,example-sensor"; + input-gpios = <&gpio1 13 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>; + }; + + blink_led: blink-led { + compatible = "blink-gpio-led"; + led-gpios = <&gpio2 9 GPIO_ACTIVE_HIGH>; + blink-period-ms = <1000>; + }; +}; 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..97f75c9 100644 --- a/app/sample.yaml +++ b/app/sample.yaml @@ -3,12 +3,13 @@ # 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 + - nrf54l15dk/nrf54l15/cpuapp tests: app.default: {} app.debug: diff --git a/doc/Doxyfile b/doc/Doxyfile index 86ae4bf..8351904 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/conf.py b/doc/conf.py index e4d8bfb..ecba5af 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -6,7 +6,7 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'Example Application' +project = 'NCS Example Application' copyright = '2024, The Zephyr Community' author = 'The Zephyr Community' release = '1.0.0' @@ -14,7 +14,7 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.intersphinx'] +extensions = [] templates_path = ['_templates'] exclude_patterns = ['_build_sphinx', 'Thumbs.db', '.DS_Store'] @@ -23,8 +23,3 @@ # 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)} diff --git a/doc/index.rst b/doc/index.rst index 3890d83..e3b07f5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,13 +1,7 @@ -Welcome to Example Application's documentation! -=============================================== +Welcome to NCS Example Application's documentation! +=================================================== -This is a simple Sphinx documentation setup for ``example-application``. - -.. toctree:: - :maxdepth: 2 - :caption: Contents - - zephyr +This is a simple Sphinx documentation setup for ``ncs-example-application``. Indices and tables ================== diff --git a/doc/zephyr.rst b/doc/zephyr.rst deleted file mode 100644 index 7e4d199..0000000 --- a/doc/zephyr.rst +++ /dev/null @@ -1,5 +0,0 @@ -Zephyr -====== - -You can reference Zephyr documentation items, like -:external+zephyr:ref:`getting_started`. diff --git a/west.yml b/west.yml index c3e4067..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_6 # required by the ARM port for Cortex-M - - hal_nordic # required by the custom_plank board (Nordic based) - - hal_stm32 # required by the nucleo_f302r8 board (STM32 based) + import: true