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]>
greg-fer · Jan 6, 2025 · 2442519 · 2442519
1 parent 8b79d37
commit 2442519
Show file tree

Hide file tree

Showing 9 changed files with 160 additions and 4 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,7 @@
     ("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
     ("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/...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 third-party boards that use Nordic Semiconductor Systems on Chip (SoCs) for custom project needs.
+
+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/notes_from_kapa.md b/doc/nrf/app_dev/device_guides/custom/notes_from_kapa.md
@@ -0,0 +1,47 @@
+To program a custom board using Nordic Semiconductor chips, you'll need to follow these general steps:
+
+1. Create a custom board definition in the nRF Connect SDK. This involves creating the necessary board files and configurations.
+
+2. Set up the hardware connections for programming. You'll need to connect the custom board to a debug probe that supports SWD (Serial Wire Debug) interface.
+
+3. Use the nRF Connect Programmer app or other compatible programming tools to flash your application to the custom board.
+
+Here's a more detailed breakdown:
+
+1. Creating a custom board definition:
+   - Create a new directory for your custom board files
+   - Define the board in the necessary files (devicetree, Kconfig, etc.)
+   - Point the build system to your custom board root directory
+
+   You can find detailed instructions on creating custom board files in the [nRF Connect SDK Intermediate course](https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-3-adding-custom-board-support/).
+
+2. Hardware connections:
+   Connect your custom board to a debug probe (like a Development Kit or a dedicated debug adapter) using the SWD interface. The typical connections needed are:
+   - SWDCLK
+   - SWDIO
+   - GND
+   - VDD (optional, for powering the board)
+   - RESET (optional)
+
+  Programming and debugging the nRF5x on our Developments kits is straight forward. Doing the same when you are using other boards might not be so easy. In this blog post we will explain which components are needed in order to program and debug a nRF5x chip.
+
+  The nRF chip is connected to a Debug unit through an interface called "Serial Wire Debug", or "SWD" for short. The debug unit acts as a bridge between the chip and your PC. It communicates with the programming and debugging software on your PC through a “Debug interface”. Your PC must have a driver for the debug unit and debug interface you are using. The driver allows your PC to recognize the debug unit, and allows communication between them over USB.
+
+  When developing applications on a nRF5x Development Kit, you can program it by simply connecting it to your PC with a USB cable. This is possible because the Development Kit has an on-board debug unit supporting the JLINK debug interface.
+
+  Since the on-board debug unit is able to program and debug the on-board chip, it is also able to program any other nRF5x chip. The Development Kit has headers where you can access the Serial Wire Debug pins. The video below describes how connect these headers to a custom board. You can also see section 5.1 of the nRF51 User Guide for more information about the debug out headers.
+
+  If you do not have a nRF5x Development Kit, you can always use a dedicated debug adapter. There exist several manufacturers and debug interfaces. With the nRF5x series, it is common to use JLINK debug adapters from Segger. You can also use debug units using other debug interfaces like the CMSIS-DAP interface, as long as you have the proper drivers and software on your PC. If you are having any problems, stop by our Developer Zone forum or support portal, where my colleagues and I will do our best to help you out.
+
+3. Programming:
+   Use the nRF Connect Programmer app to flash your application. The general steps are:
+   - Open nRF Connect for Desktop and launch the Programmer app
+   - Connect your board and select it from the device list
+   - Add your application's HEX file
+   - Click "Write" to program the board
+
+   Detailed instructions can be found in the [Programming devices documentation](https://docs.nordicsemi.com/bundle/nrf-connect-programmer/page/programming_dk.html#programming-devices).
+
+Remember to ensure that your custom board is properly powered and that all connections are secure before attempting to program it.
+
+If you encounter any issues during programming, try restarting the Programmer app (Ctrl+R or Command+R on macOS) and attempt the programming process again.
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,75 @@
+.. _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
+
+Required connections
+********************
+
+You will have to connect the following pins between your custom board and the debug probe:
+
+* Essential connections:
+
+  * SWDCLK (Clock)
+  * SWDIO (Data)
+  * GND (Ground)
+
+* Optional connections:
+
+  * VDD (for powering the board from debug probe)
+  * RESET
+
+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 don't have a Development Kit, use a dedicated debug adapter:
+
+      1. Connect a compatible debug probe (like SEGGER J-Link) to your custom board.
+      2. Install the appropriate debug interface drivers.
+      3. 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.