doc: west: runner allows nrfutil

Added information about the change of west runner for Nordic devices.
Edited the programming page, migration guide for 3.0.0, and other
affected pages. NCSDK-32305, part 1.

Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>

Author: greg-fer

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_gs.rst

@@ -266,6 +266,7 @@ If you have multiple Nordic Semiconductor devices, ensure that only the nRF54H20
 
    west flash
 
+Make sure you have the :ref:`nrfutil device <ug_nrf54h20_install_toolchain>` command installed for ``west flash`` to work with the nRF54H20 DK.
 This command builds and programs the sample automatically on both the application core and the Peripheral Processor (PPR) of the nRF54H20 SoC.
 
 .. include:: /includes/nRF54H20_erase_UICR.txt

doc/nrf/app_dev/programming.rst

@@ -21,6 +21,60 @@ To program the :ref:`output build files <app_build_output_files>` to your device
 The flash command programs all cores by default, both in the |nRFVSC| and on the command line.
 If you want to program only one selected core, use ``west flash`` on the command line and :ref:`specify the domain <zephyr:west-multi-domain-flashing>`.
 
+.. _programming_selecting_runner:
+
+Selecting west runner
+*********************
+
+Starting with the |NCS| v3.0.0, all Nordic Semiconductor :ref:`boards <app_boards>` are using the `nRF Util`_ as the default runner for the ``west flash`` command.
+This change ensures that the programming process is consistent across all boards.
+See the :ref:`build system section in the v3.0.0 migration guide <migration_3.0_recommended>` for more information.
+
+.. note::
+
+   The ``west debug`` command is not affected by this change of the default runner.
+
+Runners are Zephyr-specific Python classes that wrap Zephyr's :ref:`flash and debug host tools <zephyr:flash-debug-host-tools>` and integrate them with west and the Zephyr build system to support ``west flash`` and related commands.
+Runners supported on a board are determined by the :file:`board.cmake` file in the board folder, for example `this one <nRF52840 DK board.cmake_>`_.
+In particular, the following include lines enable them, with the first ``<runner>`` listed becoming the default runner:
+
+.. code-block:: cmake
+
+   include(${ZEPHYR_BASE}/boards/common/<runner>.board.cmake)
+
+For more information about runners, see the Zephyr documentation: :ref:`zephyr:flash-and-debug-support` and :ref:`zephyr:west-flashing`.
+
+If you want to change the runner used by ``west flash``, you can use one of the following options:
+
+* Specify the runner permanently in your application's :file:`CMakeLists.txt` file:
+
+  .. code-block::
+
+     set(BOARD_FLASH_RUNNER nrfjprog)
+
+* Specify the runner for a single command:
+
+  .. code-block::
+
+     west flash -r nrfjprog
+
+In either case, make sure you have the required tools installed on your system: `nRF Util`_ for ``-r nrfutil`` or the archived `nRF Command Line Tools`_ for ``-r nrfjprog``.
+
+To see which runners are available for your board, run the following command:
+
+.. code-block::
+
+   west flash --context
+
+The output will include lines like the following:
+
+.. code-block::
+
+   available runners in runners.yaml:
+     nrfutil, nrfjprog, jlink, pyocd, openocd
+   default runner in runners.yaml:
+     nrfutil
+
 .. _programming_hw:
 
 Hardware-specific programming steps
@@ -35,6 +89,10 @@ Programming to Thingy:91 also requires a :ref:`similar step <building_pgming>`,
 Programming the nRF52840 Dongle
   To program the nRF52840 Dongle instead of a development kit, follow the programming instructions in :ref:`zephyr:nrf52840dongle_nrf52840` or use the `Programmer app <Programming the nRF52840 Dongle_>`_.
 
+Programming the nRF54H20 DK
+   To program the nRF54H20 DK, follow the programming instructions in the :ref:`nRF54H20 device guide <ug_nrf54h20_gs_sample>`.
+   Programming the nRF54H20 DK with the |NCS| version earlier than v3.0.0 requires installing the `nrfutil device command <Installing and upgrading nRF Util commands_>`_ for the ``west flash`` command to work with this device.
+
 .. _programming_params:
 
 Optional programming parameters

doc/nrf/links.txt

@@ -68,8 +68,11 @@
 .. _`manifest group filter`: https://github.com/nrfconnect/sdk-nrf/blob/20f40501f69bc9bfd2b321704917da1769411936/west.yml#L42
 .. _`Zephyr commit 8dc3f8`: https://github.com/nrfconnect/sdk-zephyr/commit/8dc3f856229ce083c956aa301c31a23e65bd8cd8
 .. _`hwmv2 conversion script`: https://github.com/nrfconnect/sdk-zephyr/blob/main/scripts/utils/board_v1_to_v2.py
-.. _`ncs-example-application commit f9f2da`: https://github.com/nrfconnect/ncs-example-application/commit/f9f2da24041a7b1923e49893cca912482c138aae
 .. _`sdk-zephyr west build patch`: https://github.com/nrfconnect/sdk-zephyr/blob/1a5d3b4a4ff98a33222856526afdf9c089b96d2b/scripts/west_commands/build.py#L585-L598
+.. _`nRF52840 DK board.cmake`: https://github.com/nrfconnect/sdk-zephyr/blob/main/boards/nordic/nrf52840dk/board.cmake
+
+.. _`ncs-example-application commit f9f2da`: https://github.com/nrfconnect/ncs-example-application/commit/f9f2da24041a7b1923e49893cca912482c138aae
+
 .. _`sdk-nrf PR #15892`: https://github.com/nrfconnect/sdk-nrf/pull/15892
 .. _`sdk-nrf PR #14474`: https://github.com/nrfconnect/sdk-nrf/pull/14474
 .. _`sdk-nrf PR #16242`: https://github.com/nrfconnect/sdk-nrf/pull/16242

doc/nrf/releases_and_maturity/migration/migration_guide_3.0.rst

@@ -53,6 +53,36 @@ Recommended changes
 
 The following changes are recommended for your application to work optimally after the migration.
 
+Build system
+============
+
+.. toggle::
+
+   * The default runner for the ``west flash`` command has been changed to use `nRF Util`_ instead of ``nrfjprog`` that is part of the archived `nRF Command Line Tools`_.
+     This affects all :ref:`boards <app_boards>` that used ``nrfjprog`` as the west runner backend for programming the following SoCs and SiPs:
+
+     * nRF91 Series (including nRF91x1)
+     * nRF7002
+     * nRF5340 (including nRF5340 Audio DK)
+     * Nordic Thingy:53
+     * nRF52 Series
+     * nRF21540
+
+     This change is made to ensure that the programming process is consistent across all boards and to provide a more robust programming experience.
+     The ``west flash`` command now uses the ``nrfutil device`` subcommand by default to flash the application to the board.
+
+     It is recommended to install nRF Util to avoid potential issues during programming.
+     Complete the following steps:
+
+     1. Follow the steps for `Installing nRF Util`_ in its official documentation.
+     2. Install the `nrfutil device <Device command overview_>`_ using the following command:
+
+        .. code-block::
+
+           nrfutil install device
+
+     If you prefer to continue using ``nrfjprog`` for programming devices, :ref:`specify the west runner <programming_selecting_runner>` with ``west flash``.
+
 Samples and applications
 ========================
 

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -49,6 +49,8 @@ Build and configuration system
 * Removed support for the deprecated multi-image builds (parent-child images) functionality.
   All |NCS| projects must now use :ref:`sysbuild`.
   See :ref:`child_parent_to_sysbuild_migration` for an overview of differences with parent-child image and how to migrate.
+* Updated the default runner for the ``west flash`` command to `nRF Util`_ instead of ``nrfjprog`` that is part of the archived `nRF Command Line Tools`_.
+  For more information, see the :ref:`build system section in the v3.0.0 migration guide <migration_3.0_recommended>` and the :ref:`programming_selecting_runner` section on the programming page.
 
 Bootloaders and DFU
 ===================