Restructure sample documentation

doc/nrf-bm/app_dev/dfu/bootloader_keys.rst

@@ -62,12 +62,16 @@ To boot an image that uses the KMU feature, you must program the MCUboot signing
 If you do not perform this step, the device will not boot.
 You can enable this setup through the :kconfig:option:`SB_CONFIG_BM_BOOTLOADER_MCUBOOT_SIGNATURE_USING_KMU` Kconfig option.
 
+.. _ug_bootloader_kmu_autokeys:
+
 Automatic key programming
 =========================
 
 The configuration option :kconfig:option:`SB_CONFIG_BM_BOOTLOADER_MCUBOOT_GENERATE_DEFAULT_KMU_KEYFILE`, enabled by default, automates the programming of the public key file to the board.
-This automation occurs when you use the ``west flash`` command with the ``--erase`` or ``--recover`` arguments.
+In |nRFVSC|, this automatically happens when using the :guilabel:`Erase and Flash to Board` option.
+If using ``west flash`` on the command line, this automatically happens when using the ``--erase`` or ``--recover`` arguments.
 It is essential to run this command first after building the project to prepare the board for development.
+
 For more information about KMU on the nRF54L Series, see `Introduction to KMU key provisioning`_ and `Performing KMU provisioning`_.
 
 Runtime revocation

doc/nrf-bm/app_dev/dfu/memory_partitioning.rst

@@ -46,6 +46,31 @@ The memory in the device is divided into several partitions, each serving a spec
      - Used for application data storage that persists across resets and firmware updates.
      - Placement and size are configurable based on application requirements.
 
+.. _ug_memorypartiton_irot:
+
+Configuring MCUboot to be IRoT
+******************************
+
+Configuring MCUboot to act as Immutable Root of Trust (IRoT) is done using the immutable boot region configuration register ``UICR.BOOTCONF``.
+By default, this functionality is disabled, but it can be enabled with the :kconfig:option:`SB_CONFIG_BM_BOOT_BOOTCONF_LOCK_WRITES` sysbuild Kconfig option.
+This is done by by creating a :file:`sysbuild.conf` file in the project's root folder and including ``SB_CONFIG_BM_BOOT_BOOTCONF_LOCK_WRITES=y``.
+
+Enabling this option sets the ``EXECUTE``, ``READ``, ``SECURE``, and ``LOCK`` bits in the ``UICR.BOOTCONF`` register and sets the ``UICR.BOOTCONF.SIZE`` to the size of the ``boot_partition`` from the board files.
+This enables write protection on the bootloader region and locks down the configuration registers for the immutable boot region.
+
+Programming
+===========
+
+With IRoT enabled, you must run an Erase All before programming certain parts of the memory.
+In |nRFVSC|, this is done by using the :guilabel:`Erase and Flash to Board` option, or, alternatively, by using  the ``west flash`` command with the ``--erase`` or ``--recover`` arguments.
+
+When IRoT is established, the device is blocked from performing write operations on the ``boot_partition`` without performing an erase all operation.
+All other regions are open and can be programmed just like before the IRoT was established.
+
+.. note::
+   Use nRF Util device version 2.15.0 or higher as older versions have a known issue related to ERASEALL and UICR.BOOTCONF on nRF54L.
+   Alternatively, use the ``Recover`` function to erase the device and remove the IRoT protection.
+
 Requirement for MCUboot
 ***********************
 
@@ -69,7 +94,7 @@ An example of such images are application and firmware loader.
 The SoftDevice is not affected by this requirement.
 
 SoftDevice placement
---------------------
+********************
 
 .. figure:: ../../images/dfu_softdevice.svg
    :alt: Placement of the SoftDevice relative to the top of NVM

doc/nrf-bm/links.txt

@@ -34,6 +34,7 @@
 .. _`nRF Connect for Visual Studio Code`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/installation/recommended_versions.html#requirements-nrfvsc
 .. _`Visual Studio Code download page`: https://code.visualstudio.com/download
 .. _`freestanding application`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/guides/applications.html
+.. _`UI overview`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/reference/ui_overview.html
 .. _`Applications View`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/reference/ui_sidebar_applications.html
 .. _`Actions View`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/reference/ui_sidebar_actions.html
 .. _`Details View`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/reference/ui_sidebar_details.html

doc/nrf-bm/sample/intro.rst

@@ -0,0 +1,16 @@
+.. _getting_started_with_the_samples:
+
+Getting Started with the samples
+################################
+
+This section is a general description of how you can explore and try out the samples provided with the |BMlong|.
+It describes how you can create a copy of a sample, configure it, build it, program it, and run it on a supported Nordic development kit.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Subpages
+   :glob:
+
+   /sample/intro/create_sample
+   /sample/intro/configure_and_build_sample
+   /sample/intro/program_sample

doc/nrf-bm/includes/configure_and_build_sample.txt → doc/nrf-bm/sample/intro/configure_and_build_sample.rst

@@ -1,14 +1,16 @@
-Configuring and building the sample
-===================================
+.. _sample_intro_config_build:
 
-Follow these steps to create your first build configuration for this sample:
+Configuring and building a sample
+#################################
 
-1. Verify the configuration of this sample.
+Follow these steps to create your first build configuration for a sample:
+
+1. Verify the configuration of the selected sample.
 
    You will need the following information:
 
    * The |NCS| version and toolchain version that the current |BMshort| release is based on: |ncs_release|
-   * The board target onto which you want to program the firmware (see `Requirements`_).
+   * The board target onto which you want to program the firmware (see the Requirements section of each sample description).
 
    This information will be used in the steps that follow.
 
@@ -65,6 +67,14 @@ Follow these steps to create your first build configuration for this sample:
 
          Build configuration files
 
+      When selecting simple board variants, the SoftDevice hex file is automatically included.
+      When the build process is completed, the `Applications View`_ lists the SoftDevice in addition to the main application.
+
+      .. note::
+         This is also the case for the peripheral samples where the SoftDevice is not needed.
+         This is because the SDK does not include board targets without the SoftDevice, in order to reduce complexity.
+
+
    .. group-tab:: MCUboot board variants
 
       When the process is complete, the `Actions View`_ appears.

doc/nrf-bm/includes/create_sample.txt → doc/nrf-bm/sample/intro/create_sample.rst

@@ -1,7 +1,11 @@
-Creating a copy of the sample
-=============================
+.. _sample_intro_copy:
 
-Follow these steps to create a new application based on this sample:
+Creating a copy of a sample
+###########################
+
+This procedure is the recommended approach when working with the samples and allows you to add changes without modifying the SDK itself.
+
+Follow these steps to create a new application based on a sample:
 
 1. Open the |nRFVSC| by clicking its icon.
 #. From the :guilabel:`Welcome View`, click :guilabel:`Create a new application`.
@@ -23,7 +27,7 @@ Follow these steps to create a new application based on this sample:
 
       Create New Application from Sample - Quick Pick Menu
 
-#. Click on the name of this sample.
+#. Click on the name of the sample you want to work with.
 
    A prompt appears asking to enter the location for the application.
    You can also use the folder button at the top of the quick pick to open a folder picker.

doc/nrf-bm/sample/intro/program_sample.rst

@@ -0,0 +1,42 @@
+.. _sample_intro_program:
+
+Programming a sample
+####################
+
+This section describes how you program the DK with all the different firmware modules and the extra data that is needed.
+This description assumes you are using |nRFVSC|.
+For details, see `UI overview`_.
+
+* `Applications View`_ - Select what to program.
+
+  1. Select which application should be the active one.
+  #. In case the project has multiple build contexts, select the one that should be used.
+  #. Within the build context, you can select between programming the whole project (all images) by selecting the build folder, or just one of the images within the build context by selecting one of the domains within the build folder.
+
+* `Actions View`_ - Specify how to program.
+
+  * :guilabel:`Flash` - This will flash the active context selected in the Application View and only replace the memory section specified by the active context.
+
+  * :guilabel:`Erase and Flash to Board` - This will first do a chip Erase All erasing all NVM including UICR and KMU content, before it flashes the active context.
+
+* Select which target (DK) to program.
+
+  In case there is only one DK connected, only that one will be flashed.
+  In case you have more than one DK connected, you will be promted and can select one or multiple DKs to be flashed.
+
+Special cases
+*************
+
+MCUboot
+=======
+
+When running samples with MCUboot and firmware loader included, the project will have signing key(s) included.
+It is required to provision the key(s) when programming the board for the first time.
+This can be done by programming with the :guilabel:`Erase and Flash to Board` option.
+See :ref:`ug_bootloader_kmu_autokeys` for more details.
+
+Immutable Bootloader (IRoT) configuration
+=========================================
+
+When running a sample with MCUboot set as Immutable Root of Trust (IRoT), you must take special care when programming.
+See :ref:`ug_memorypartiton_irot` for more details.

doc/nrf-bm/samples.rst

@@ -13,6 +13,7 @@ All other samples and applications that are included in the distribution must be
    :glob:
    :caption: Subpages:
 
+   sample/intro
    sample/ble
    sample/dfu
    sample/nfc

samples/bluetooth/ble_bms/README.rst

@@ -56,23 +56,14 @@ LED 0:
 LED 1:
    Lit when a device is connected.
 
-Programming the S115 SoftDevice
-*******************************
-
-.. include:: /includes/softdevice_flash.txt
-
 .. _ble_bms_sample_testing:
 
 Building and running
 ********************
 
 This sample can be found under :file:`samples/bluetooth/ble_bms/` in the |BMshort| folder structure.
 
-.. include:: /includes/create_sample.txt
-
-.. include:: /includes/configure_and_build_sample.txt
-
-.. include:: /includes/program_sample.txt
+For details on how to create, configure, and program a sample, see :ref:`getting_started_with_the_samples`.
 
 Testing
 =======

samples/bluetooth/ble_cgms/README.rst

@@ -69,23 +69,12 @@ Overview
 
 The Continuous Glucose Monitoring Service (CGMS) is a service that exposes glucose and other data from a personal Continuous Glucose Monitoring sensor.
 
-Programming the S115 SoftDevice
-*******************************
-
-.. include:: /includes/softdevice_flash.txt
-
-.. _ble_cgms_sample_testing:
-
 Building and running
 ********************
 
 This sample can be found under :file:`samples/bluetooth/ble_cgms/` in the |BMshort| folder structure.
 
-.. include:: /includes/create_sample.txt
-
-.. include:: /includes/configure_and_build_sample.txt
-
-.. include:: /includes/program_sample.txt
+For details on how to create, configure, and program a sample, see :ref:`getting_started_with_the_samples`.
 
 Testing
 =======

samples/bluetooth/ble_hids_keyboard/README.rst

@@ -101,23 +101,12 @@ LED 1:
 LED 3:
    Lit when Caps Lock is on.
 
-Programming the S115 SoftDevice
-*******************************
-
-.. include:: /includes/softdevice_flash.txt
-
-.. _ble_hids_keyboard_sample_testing:
-
 Building and running
 ********************
 
 This sample can be found under :file:`samples/bluetooth/ble_hids_keyboard/` in the |BMshort| folder structure.
 
-.. include:: /includes/create_sample.txt
-
-.. include:: /includes/configure_and_build_sample.txt
-
-.. include:: /includes/program_sample.txt
+For details on how to create, configure, and program a sample, see :ref:`getting_started_with_the_samples`.
 
 Testing
 =======

samples/bluetooth/ble_hids_mouse/README.rst

@@ -102,24 +102,12 @@ LED 0:
 LED 1:
    Lit when a device is connected.
 
-Programming the S115 SoftDevice
-*******************************
-
-.. include:: /includes/softdevice_flash.txt
-
-.. _ble_hids_mouse_sample_testing:
-
-
 Building and running
 ********************
 
 This sample can be found under :file:`samples/bluetooth/ble_hids_mouse/` in the |BMshort| folder structure.
 
-.. include:: /includes/create_sample.txt
-
-.. include:: /includes/configure_and_build_sample.txt
-
-.. include:: /includes/program_sample.txt
+For details on how to create, configure, and program a sample, see :ref:`getting_started_with_the_samples`.
 
 Testing
 =======

samples/bluetooth/ble_hrs/README.rst

@@ -95,23 +95,12 @@ User interface
 Button 1:
    Keep the button pressed while resetting the board to delete bonding information for all peers stored on the device.
 
-Programming the S115 SoftDevice
-*******************************
-
-.. include:: /includes/softdevice_flash.txt
-
-.. _ble_hrs_sample_testing:
-
 Building and running
 ********************
 
 This sample can be found under :file:`samples/bluetooth/ble_hrs/` in the |BMshort| folder structure.
 
-.. include:: /includes/create_sample.txt
-
-.. include:: /includes/configure_and_build_sample.txt
-
-.. include:: /includes/program_sample.txt
+For details on how to create, configure, and program a sample, see :ref:`getting_started_with_the_samples`.
 
 Testing
 =======

samples/bluetooth/ble_hrs_central/README.rst

@@ -71,23 +71,14 @@ This sample scans for devices that advertise with the :ref:`lib_ble_service_hrs`
 When a device is connected, the sample starts the service discovery procedure.
 If this succeeds, the sample subscribes to the Heart Rate Measurement characteristic to receive heart rate notifications.
 
-Programming the S115 SoftDevice
-*******************************
-
-.. include:: /includes/softdevice_flash.txt
-
 .. _ble_hrs_central_sample_testing:
 
 Building and running
 ********************
 
-This sample can be found under :file:`samples/bluetooth/ble_hrs/` in the |BMshort| folder structure.
-
-.. include:: /includes/create_sample.txt
-
-.. include:: /includes/configure_and_build_sample.txt
+This sample can be found under :file:`samples/bluetooth/ble_hrs_central/` in the |BMshort| folder structure.
 
-.. include:: /includes/program_sample.txt
+For details on how to create, configure, and program a sample, see :ref:`getting_started_with_the_samples`.
 
 Testing
 =======