doc: custom board programming guide

Added a new section to the Application Development that covers development with custom boards. The section includes a new page about how to connect custom board hardware for programming. NCSDK-28526. Signed-off-by: Grzegorz Ferenc <[email protected]>
nrfconnect · Jan 7, 2025 · 42f77d4 · 42f77d4
1 parent 4cb4cd1
commit 42f77d4
Show file tree

Hide file tree

Showing 9 changed files with 118 additions and 7 deletions.
diff --git a/doc/_utils/redirects.py b/doc/_utils/redirects.py
@@ -58,7 +58,6 @@
     ("config_and_build/board_support/index", "app_dev/board_support/index"),
     ("config_and_build/board_support/board_names", "app_dev/board_support/board_names"), # Board names
     ("config_and_build/board_support/processing_environments", "app_dev/board_support/processing_environments"), # Processing environments
-    ("config_and_build/board_support/defining_custom_board", "app_dev/board_support/defining_custom_board"), # Defining custom board
     ("gs_modifying", "app_dev/config_and_build/index"), # Configuring and building (landing)
     ("getting_started/modifying", "app_dev/config_and_build/index"),
     ("config_and_build/modifying", "app_dev/config_and_build/index"),
@@ -262,6 +261,8 @@
     ("device_guides/fem/fem_incomplete_connections", "app_dev/device_guides/fem/fem_incomplete_connections"), # Use case of incomplete physical connections to the FEM module
     ("device_guides/fem/fem_power_models", "app_dev/device_guides/fem/fem_power_models"), # Using FEM power models
     ("device_guides/fem/21540ek_dev_guide", "app_dev/device_guides/fem/21540ek_dev_guide"), # Developing with the nRF21540 EK
+    ("config_and_build/board_support/defining_custom_board", "app_dev/device_guides/custom/defining_custom_board"), # Defining custom board
+    ("app_dev/board_support/defining_custom_board", "app_dev/device_guides/custom/defining_custom_board"),
     ("ug_radio_coex", "app_dev/device_guides/wifi_coex"), # Coexistence of short-range radio and other radios
     ("app_dev/wifi_coex/index", "app_dev/device_guides/wifi_coex"),
     ("device_guides/wifi_coex", "app_dev/device_guides/wifi_coex"),

diff --git a/doc/_zoomin/ncs.tags.yml b/doc/_zoomin/ncs.tags.yml
@@ -233,6 +233,7 @@ mapping_topics:
   - nrf/app_dev/device_guides/fem/*.html: ["fem", "nrf21540", "evaluation-kits", "development-kits"]
   - nrf/app_dev/device_guides/wifi_coex.html: ["kconfig", "ble", "nrf70-series", "nrf7002",
                                                "nrf7001", "nrf7000", "wifi"]
+  - nrf/app_dev/device_guides/custom/*.html: ["development-kits"]
   - nrf/test_and_optimize.html: ["nrf91-series", "nrf70-series", "nrf54-series", "nrf53-series",
                                  "nrf52-series", "nrf7002", "nrf7001", "nrf7000", "nrf9160",
                                  "thingy91", "thingy91x", "nrf9161", "nrf9151", "nrf9131",

diff --git a/doc/nrf/app_dev.rst b/doc/nrf/app_dev.rst
@@ -35,4 +35,5 @@ For detailed integration instructions of specific technologies and components, c
    app_dev/device_guides/thingy53/index
    app_dev/device_guides/pmic/index
    app_dev/device_guides/fem/index
+   app_dev/device_guides/custom/index
    app_dev/device_guides/wifi_coex
diff --git a/doc/nrf/app_dev/board_support/index.rst b/doc/nrf/app_dev/board_support/index.rst
@@ -10,12 +10,9 @@ You can select the board targets for these boards when :ref:`building`.
 
 Some boards can support Cortex-M Security Extensions (CMSE), with their board targets separated for different :ref:`app_boards_spe_nspe`.
 
-In addition, you can :ref:`define custom boards <defining_custom_board>`.
-
 .. toctree::
    :maxdepth: 1
    :caption: Subpages:
 
    board_names
    processing_environments
-   defining_custom_board
diff --git a/...v/board_support/defining_custom_board.rst → ...e_guides/custom/defining_custom_board.rst b/...v/board_support/defining_custom_board.rst → ...e_guides/custom/defining_custom_board.rst
@@ -7,7 +7,13 @@ Defining custom board
    :local:
    :depth: 2
 
-Defining your own board is a very common step in application development, because applications are typically designed to run on boards that are not directly supported by the |NCS|, and are often custom designs not available publicly.
+Defining your own board is a very common step in application development, because applications are typically designed to run on boards that are not directly supported by the |NCS| and these boards are often custom designs not available publicly.
+
+This page lists resources about defining custom board files in the |NCS|.
+To read about how to program a custom board, see :ref:`programming_custom_board`.
+
+.. note::
+   If you want to go through a dedicated training related to some of the topics covered here, enroll in the `nRF Connect SDK Intermediate course`_ in the `Nordic Developer Academy`_. The `Lesson 3 – Adding custom board support`_ shows how to add custom board support using the |nRFVSC|.
 
 Guidelines for custom boards
 ****************************
@@ -20,7 +26,7 @@ To define your own board, you can use the following Zephyr guides as reference,
 Adding a custom board in the |nRFVSC|
 *************************************
 
-The |nRFVSC| lets you add your own boards to your |NCS| project.
+|nRFVSC| lets you add your own boards to your |NCS| project.
 Read the `How to work with boards and devices`_ page in the extension documentation for detailed steps.
 
 Application porting guides

diff --git a/doc/nrf/app_dev/device_guides/custom/index.rst b/doc/nrf/app_dev/device_guides/custom/index.rst
@@ -0,0 +1,20 @@
+.. _ug_custom_board:
+
+Developing with custom boards
+#############################
+
+.. |nrf_series| replace:: custom boards
+
+.. include:: /includes/guides_complementary_to_app_dev.txt
+
+Custom boards are hardware designs that are not directly provided or supported by Nordic Semiconductor.
+These are typically boards that use Nordic Semiconductor Systems on Chip (SoCs) for custom projects.
+
+The following sections provide information on how to work with custom boards in the |NCS|.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Subpages:
+
+   defining_custom_board
+   programming_custom_board
diff --git a/doc/nrf/app_dev/device_guides/custom/programming_custom_board.rst b/doc/nrf/app_dev/device_guides/custom/programming_custom_board.rst
@@ -0,0 +1,79 @@
+.. _programming_custom_board:
+
+Connecting custom boards for programming
+########################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+After you :ref:`created custom board files <defining_custom_board>`, you need to connect your custom board to a debug probe for programming.
+
+Hardware requirements
+*********************
+
+To connect a custom board for programming, you need the following hardware:
+
+* A debug probe supporting Serial Wire Debug (SWD), such as:
+
+  * A Development Kit (DK) from Nordic Semiconductor (all include an onboard debug probe)
+  * Dedicated debug adapter (like SEGGER J-Link)
+
+* Connecting wires
+* USB cable for the DK or the debug adapter
+
+Required connections
+********************
+
+You have to connect the following pins between your custom board and the debug probe:
+
+* Essential connections:
+
+  * SWDCLK (Clock)
+  * SWDIO (Data)
+  * GND (Ground)
+  * VTref (Target Reference Voltage)
+
+* Optional connections:
+
+  * VDD - For powering the board from debug probe.
+    If the custom board is not powered from VDD, it must be powered externally.
+  * RESET - For resetting the board.
+    If the custom board does not have a reset pin, you can use the reset pin on the debug probe.
+
+Connecting the debug probe
+**************************
+
+The following steps describe how to connect your custom board to a debug probe.
+
+.. tabs::
+
+   .. group-tab:: Using a DK as debug probe
+
+      Development Kits from Nordic Semiconductor include an onboard debug probe that supports the J-Link interface.
+
+      To connect your custom board to this onboard debug probe, complete the following steps:
+
+      1. Locate the SWD debug output header pins on your DK.
+         Check the DK user guide on `Nordic Semiconductor TechDocs`_ for the exact location of these pins.
+         For example, for the nRF52840 DK, read the `Debug output <nRF52840 DK Debug output_>`_ page.
+      #. Connect the required pins to your custom board.
+      #. Connect the DK to your PC using the USB cable.
+      #. Install required J-Link drivers if not already present.
+
+   .. group-tab:: Using a dedicated debug adapter
+
+      If you do not have a Development Kit, use a dedicated debug adapter:
+
+      1. Connect a compatible debug probe (like SEGGER J-Link) to your custom board.
+         See the debug probe documentation for the exact pinout.
+      #. Install the appropriate debug interface drivers.
+      #. Connect the debug probe to your PC using the USB cable.
+
+.. note::
+      The |NCS| supports various debug interfaces like J-Link and CMSIS-DAP, provided you have the proper drivers installed.
+
+Programming custom boards
+*************************
+
+After you connected the custom board, you can program your application to the board using either the :ref:`standard programming instructions <programming>` or the `Programmer app`_ from `nRF Connect for Desktop`_.
diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt
@@ -738,6 +738,7 @@
 .. _`System OFF mode`: https://docs.nordicsemi.com/bundle/ps_nrf52840/page/power.html#ariaid-title10
 .. _`nRF52840 DK User Guide`: https://docs.nordicsemi.com/bundle/ug_nrf52840_dk/page/UG/dk/intro.html
 .. _`nRF52840 Dongle User Guide`: https://docs.nordicsemi.com/bundle/ug_nrf52840_dongle/page/UG/nrf52840_Dongle/intro.html
+.. _`nRF52840 DK Debug output`: https://docs.nordicsemi.com/bundle/ug_nrf52840_dk/page/UG/dk/hw_debug_out.html
 .. _`nRF52840 DK Compatibility Matrix`: https://docs.nordicsemi.com/bundle/comp_matrix_nrf52840/page/COMP/nrf52840/nrf52840_comp_matrix.html
 
 .. _`nRF52833 Product Specification`: https://docs.nordicsemi.com/bundle?labelkey=nrf52833&labelkey=product-specification
@@ -921,6 +922,7 @@
 
 .. _`nRF Connect SDK Intermediate course`: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/
 .. _`Lesson 2 - Debugging and troubleshooting`: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-2-debugging/
+.. _`Lesson 3 – Adding custom board support`: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-3-adding-custom-board-support/
 .. _`Lesson 5 – Serial Peripheral Interface (SPI)`: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-5-serial-peripheral-interface-spi/
 .. _`Lesson 7 - Device driver model`: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-7-device-driver-model/
 

diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
@@ -608,4 +608,8 @@ cJSON
 Documentation
 =============
 
-|no_changes_yet_note|
+* Added new section :ref:`ug_custom_board`.
+  This section includes the following pages:
+
+  * :ref:`defining_custom_board` - Previously located under :ref:`app_boards`.
+  * :ref:`programming_custom_board` - New page.