doc: Restructure sample documentation

Restructure sample documentation, removing common
stuff from sample to separat section.

Signed-off-by: Bjørn Tore Taraldsen <[email protected]>

Author: bjorn-tore-taraldsen

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 nRF Connect SDK.
+It  describes how you can create a copy of your sample, configure it, build and program the samples to test it running on a Nordic DK’s.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Subpages
+   :glob:
+
+   /sample/intro/create_sample
+   /sample/intro/configure_and_build_sample
+   /sample/intro/program_sample

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

@@ -0,0 +1,93 @@
+Configuring and building the sample
+===================================
+
+Follow these steps to create your first build configuration for this sample:
+
+1. Verify the configuration of this 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`_).
+
+   This information will be used in the steps that follow.
+
+   .. note::
+      The following screenshots show the **Hello SoftDevice** sample as reference.
+
+#. In the `Applications View`_, click :guilabel:`Add build configuration`.
+
+   .. figure:: /images/add_build_configuration.png
+      :alt: Add Build Configuration
+
+      Add Build Configuration
+
+#. This opens the **Add Build Configuration** page.
+
+   .. figure:: /images/add_build_configuration_page.png
+      :alt: Add Build Configuration page - fragment
+
+      Add Build Configuration page - fragment
+
+#. For your very first build configuration, double-check that the values in the |NCS| and toolchain menus match the expected versions.
+
+#. Select the board target onto which you want to program the firmware.
+
+   For your very first build configuration, select a compatible board target from the drop-down menu.
+
+   .. figure:: /images/board_target.png
+      :alt: Board target drop-down menu
+
+      Board target drop-down menu
+
+#. If the sample supports Kconfig fragments, you can configure a fragment by selecting :file:`prj.conf` from the :guilabel:`Base configuration files (Kconfig fragments)` drop-down menu.
+
+   Then, from the :guilabel:`Extra Kconfig fragments` drop-down menu, select the target fragment.
+
+#. Leave all the other options as default.
+
+   For more details on how to configure builds, see `How to build an application`_ in |VSC| extension documentation.
+
+#. Click :guilabel:`Generate and Build`.
+
+   The |VSC| extension generates the configuration file and triggers the build process, which can take some time. You can monitor its progress in the notification that appears.
+
+.. tabs::
+
+   .. group-tab:: Simple board variants
+
+      When the process is complete, the `Actions View`_ appears.
+      In this View, you can trigger the build process again, flash the built application, start a debug session (if debug options were set when building), or generate a memory report.
+      The build files appear in the build's `Details View`_, which is named after your application.
+
+      .. figure:: /images/show_build_configuration_files.png
+         :alt: Build configuration files
+
+         Build configuration files
+
+      When selecting Simple Board variants it will automatically include the SoftDevice hex.
+      When the build process is completed, the `Applications View`_ will list SoftDevice in addition to the main application.
+
+      .. note::
+         This will also be the case for the Peripheral samples where we do not need a SoftDevice.
+         Reason for this is the selected board target and that we have decided to not have any board targets without SoftDevice included.
+
+
+   .. group-tab:: MCUboot board variants
+
+      When the process is complete, the `Actions View`_ appears.
+      In this View, you can trigger the build process again, flash the built application, start a debug session (if debug options were set when building), or generate a memory report.
+      The build files appear in the build's `Details View`_, which is named after your application.
+
+      .. figure:: /images/show_build_configuration_files_mcuboot.png
+         :alt: Build configuration files
+
+         Build configuration files with MCUboot board variant
+
+      When selecting an MCUboot board variant, the configuration of the memory includes both MCUboot and single-bank DFU.
+      This will automatically include and compile the extra images needed for the partitions.
+      When the build process is completed, the Application view will list all images.
+
+      For details on how the memory partitions are organized when including MCUboot and DFU, see :ref:`dfu_memory_partitioning`.
+
+      For how to program your board and run the images, see :ref:`ug_dfu`.

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

@@ -0,0 +1,33 @@
+Creating a copy of the sample
+=============================
+
+Follow these steps to create a new application based on this sample:
+
+1. Open the |nRFVSC| by clicking its icon.
+#. From the :guilabel:`Welcome View`, click :guilabel:`Create a new application`.
+
+   A quick pick menu appears.
+
+#. Select :guilabel:`Copy a sample` - this will create a `freestanding application`_ from a sample in |BMlong|.
+
+   If you have more than one SDK version installed, a quick pick menu appears showing a list of SDK versions to copy the sample from.
+
+#. If asked to select the SDK version, select the one that you want to copy the sample from.
+
+   A quick pick menu appears showing a list of available samples to choose from.
+   This list is autogenerated based on the chosen SDK with the :guilabel:`nrf-bm` samples placed on the top of the list.
+   All samples below the :guilabel:`nrf-bm` specific list are not compatible and should be ignored.
+
+   .. figure:: /images/create_new_application_from_sample_quick_pick_menu.png
+      :alt: Create New Application from Sample - Quick Pick Menu
+
+      Create New Application from Sample - Quick Pick Menu
+
+#. Click on the name of this sample.
+
+   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.
+
+   The application creation process starts after you enter the name.
+   When the application is created, a prompt appears.
+   Click :guilabel:`Open` or :guilabel:`Open in New Window` to open the new application.

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

@@ -0,0 +1,41 @@
+Programming
+===========
+
+Follow these steps to program this sample:
+
+1. Plug in your device to the serial terminal using a USB cable.
+   Your device appears on the `Connected Devices View`_ list in |VSC|.
+#. To flash the application you have built, select your build folder in the `Applications View`_.
+   Then, click :guilabel:`Flash` in the `Actions View`_ after connecting the device to the terminal.
+
+
+Flash ALL
+---------
+
+By selecting the build folder in the Application View, nRF Connect extension in VS Code will automatically program ALL images listed in that build configuration.
+For a Simple Board variant, the build folder will list both the application and the SoftDevice, and a Flash command will flash both.
+Equally for a MCUboot variant, the Flash command will flash all the images needed.
+
+
+Flash individually
+------------------
+
+If you, in the Application view, select one of the images listed within a build folder, nRF Connect extension in VS Code will flash only the selected image.
+For a Simple Board variant, the build folder will list both the application and the SoftDevice. If you select either application or SoftDevice, the Flash command will Flash only the selected one.
+
+.. note::
+
+    When programming in VSC with nRF Connect plugin it’s important to understand the difference between the “Flash” and “Erase and Flash to board”. See [Action View] for details on this
+
+.. note::
+
+  When programming a board for the first time using MCUboot board variants with KMU (default), make sure the KMU is programmed with the necessary keys.
+
+  * Using the command line: Execute ``west flash --erase`` or ``west flash --recover``.
+  * Using Visual Studio Code: In the Actions View, hover over the :guilabel:`Flash` option.
+    Click :guilabel:`Erase and Flash to Board`, which appears to the right under :guilabel:`More actions`.
+
+   .. figure:: /images/erase_and_flash_to_board.png
+      :alt: Erase and flash to board.
+
+For more details, see `How to flash an application`_ in |VSC| extension documentation.

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/peripheral

samples/bluetooth/ble_cgms/README.rst

@@ -69,26 +69,16 @@ 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
-*******************************
+Playing with the sample
+***********************
 
-.. include:: /includes/softdevice_flash.txt
+his sample can be found under :file:`samples/bluetooth/ble_cgms/` in the |BMshort| folder structure.
 
-.. _ble_cgms_sample_testing:
+For details on how to create, configure and program a sample see :ref:`getting_started_with_the_samples`.
 
-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
 
 Testing
-=======
+*******
 
 1. Compile and program the application.
 #. Connect the device to the computer.

samples/bluetooth/ble_hids_keyboard/README.rst

@@ -101,26 +101,16 @@ 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
-********************
+Playing with the sample
+***********************
 
 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
+For details on how to create, configure and program a sample see :ref:`getting_started_with_the_samples`.
 
-.. include:: /includes/program_sample.txt
 
 Testing
-=======
+*******
 
 1. Compile and program the application.
 #. In the Serial Terminal, using the `Serial Terminal app`_ or |VSC|, observe that the ``BLE HIDS Keyboard sample started.`` message is printed.

samples/bluetooth/ble_hids_mouse/README.rst

@@ -102,27 +102,16 @@ 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
-********************
+Playing with the sample
+***********************
 
 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
+For details on how to create, configure and program a sample see :ref:`getting_started_with_the_samples`.
 
-.. include:: /includes/program_sample.txt
 
 Testing
-=======
+*******
 
 You can test this sample using a computer or a smartphone.
 

samples/bluetooth/ble_hrs/README.rst

@@ -95,26 +95,17 @@ 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
-********************
+Playing with the sample
+***********************
 
 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
+For details on how to create, configure and program a sample see :ref:`getting_started_with_the_samples`.
 
-.. include:: /includes/program_sample.txt
 
 Testing
-=======
+*******
 
 You can test this sample using `nRF Connect for Desktop`_ with the `Bluetooth Low Energy app`_ and the `Serial Terminal app`_.
 Make sure that these are installed before starting the testing procedure.

samples/bluetooth/ble_lbs/README.rst

@@ -71,27 +71,16 @@ The LED Button Service (LBS) is a custom service that receives information about
 
 You can use the sample to transmit the button state from your development kit to another device.
 
-Programming the S115 SoftDevice
-*******************************
-
-.. include:: /includes/softdevice_flash.txt
-
-.. _ble_lbs_sample_testing:
-
-
-Building and running
-********************
+Playing with the sample
+***********************
 
 This sample can be found under :file:`samples/bluetooth/ble_lbs/` in the |BMshort| folder structure.
 
-.. include:: /includes/create_sample.txt
-
-.. include:: /includes/configure_and_build_sample.txt
+For details on how to create, configure and program a sample see :ref:`getting_started_with_the_samples`.
 
-.. include:: /includes/program_sample.txt
 
 Testing
-=======
+*******
 
 You can test this sample using `nRF Connect for Desktop`_ with the `Bluetooth Low Energy app`_ and the `Serial Terminal app`_.
 Make sure that these are installed before starting the testing procedure.