diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst index 4ce37f983844..a4ede757cf87 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst @@ -27,8 +27,9 @@ Make sure you have all the required hardware and that your computer has one of t Hardware ======== -* nRF54H20 DK version PCA10175 v0.7.x or v0.8.0 (ES3). - Check the version number on your DK's sticker to verify its compatibility with |NCS| version 2.6.99-cs2. +* nRF54H20 DK version PCA10175 v0.7.x or v0.8.0 (ES3), ES4. + These are the only versions of the nRF54H20 DK compatible with |NCS| 2.7. + Check the version number on your DK's sticker to verify its compatibility with |NCS| version 2.7. * USB-C cable. @@ -37,9 +38,11 @@ Software On your computer, one of the following operating systems: -* Microsoft Windows -* Ubuntu Linux -* macOS +.. include:: ../../../../nrf/installation/recommended_versions.rst + :start-after: os_table_start + :end-before: os_table_end + +See :ref:`supported_OS` for more information about the tier definitions. |supported OS| @@ -82,175 +85,106 @@ To work with the nRF54H20 DK, follow the instructions in the next sections to in .. _ug_nrf54h20_install_toolchain: -Installing the toolchain -======================== - -You can install the toolchain for the customer sampling of the |NCS| by running an installation script. -Follow these steps: - -.. tabs:: - - .. tab:: Windows - - 1. Open Git Bash. - #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: - - .. parsed-literal:: - :class: highlight - - curl --proto '=https' --tlsv1.2 -sSf https://files.nordicsemi.com/artifactory/swtools/external/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.6.99-cs2 sh - - Depending on your connection, this might take some time. - #. Open a new terminal window with the |NCS| toolchain environment by running the following command: - - .. parsed-literal:: - :class: highlight - - c:/ncs-lcs/nrfutil.exe toolchain-manager launch --terminal --chdir "c:/ncs-lcs/work-dir" --ncs-version v2.6.99-cs2 - - This setup allows you to access west and other development tools. - Alternatively, you can set up the environment variables manually by running the following command:: - - c:/ncs-lcs/nrfutil.exe toolchain-manager env --as-script - - Copy-paste the output into the terminal and execute it to enable the use of west directly in that window. - - .. note:: - WWhen working with west in the customer sampling release, you must always use a terminal window with the |NCS| toolchain environment. - - If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`C:\\ncs-lcs` directory, and start over. - - .. tab:: Linux - - 1. Open a terminal window. - #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: - - .. parsed-literal:: - :class: highlight - - curl --proto '=https' --tlsv1.2 -sSf https://files.nordicsemi.com/artifactory/swtools/external/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.6.99-cs2 sh - - Depending on your connection, this might take some time. - #. Open a new terminal window with the |NCS| toolchain environment by running the following command: +Installing the |NCS| v2.7 and its toolchain +******************************************* - .. parsed-literal:: - :class: highlight +You can install the |NCS| v2.7 and its toolchain by using Toolchain Manager. - $HOME/ncs-lcs/nrfutil toolchain-manager launch --shell --chdir "$HOME/ncs-lcs/work-dir" --ncs-version v2.6.99-cs2 +Toolchain Manager is a tool available from `nRF Connect for Desktop`_, a cross-platform tool that provides different applications that simplify installing the |NCS|. +Both the tool and the application are available for Windows, Linux, and macOS. - .. note:: - When working with west in the customer sampling release, you must always use a shell window with the |NCS| toolchain environment. +To install the toolchain and the SDK using the Toolchain Manager app, complete the following steps: - If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`ncs-lcs` directory, and start over. +1. Install Toolchain Manager: - .. tab:: macOS + a. `Download nRF Connect for Desktop`_ for your operating system. + #. Install and run the tool on your machine. + #. In the **APPS** section, click :guilabel:`Install` next to Toolchain Manager. - 1. Open a terminal window. - #. Install `Homebrew`_: + The app is installed on your machine, and the :guilabel:`Install` button changes to :guilabel:`Open`. - .. code-block:: bash +#. Install the |NCS| source code: - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + a. Open Toolchain Manager in nRF Connect for Desktop. - #. Use the ``brew`` command to install the required dependencies: + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm.png + :alt: The Toolchain Manager window - .. code-block:: bash + The Toolchain Manager window - brew install cmake ninja gperf python3 ccache qemu dtc wget libmagic + #. Click :guilabel:`SETTINGS` in the navigation bar to specify where you want to install the |NCS|. + #. In :guilabel:`SDK ENVIRONMENTS`, click the :guilabel:`Install` button next to the |NCS| version 2.7. - Ensure that these dependencies are installed with their versions as specified in the :ref:`Required tools table `. - To check the installed versions, run the following command: + The |NCS| version 2.7 is installed on your machine. + The :guilabel:`Install` button changes to :guilabel:`Open VS Code`. - .. parsed-literal:: - :class: highlight +#. Set up the preferred building method: - brew list --versions + .. tabs:: - #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: + .. tab:: nRF Connect for Visual Studio Code - .. parsed-literal:: - :class: highlight + To build on the |nRFVSC|, complete the following steps: - curl --proto '=https' --tlsv1.2 -sSf https://files.nordicsemi.com/artifactory/swtools/external/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.6.99-cs2 sh + a. In Toolchain Manager, click the :guilabel:`Open VS Code` button. - Depending on your connection, this might take some time. + A notification appears with a list of missing extensions that you need to install, including those from the `nRF Connect for Visual Studio Code`_ extension pack. + #. Click **Install missing extensions**. + #. Once the extensions are installed, click **Open VS Code** button again. - .. note:: - On macOS, the install directory is :file:`/opt/nordic/ncs`. - This means that creating the directory requires root access. - You will be prompted to grant the script admin rights for the creation of the folder on the first install. - The folder will be created with the necessary access rights to the user, so subsequent installs do not require root access. + You can then follow the instructions in :ref:`creating_vsc`. - Do not run the toolchain-manager installation as root (for example, using `sudo`). - It restricts access to the root user only, meaning you will need the root access for any subsequent installations. - If you run the script as root, to fix permissions delete the installation folder and run the script again as a non-root user. + .. tab:: Command line - #. Open a new terminal window with the |NCS| toolchain environment by running the following command: + To build on the command line, complete the following steps: - .. parsed-literal:: - :class: highlight + 1. With admin permissions enabled, download and install the `nRF Command Line Tools`_. + #. Restart the Toolchain Manager application. + #. Click the dropdown menu for the installed nRF Connect SDK version. - /Users/*yourusername*/ncs-lcs/nrfutil toolchain-manager launch --shell --chdir "/Users/*yourusername*/ncs-lcs/work-dir" --ncs-version v2.6.99-cs2 + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm_dropdown.png + :alt: The Toolchain Manager dropdown menu for the installed nRF Connect SDK version, cropped - .. note:: - When working with west in the customer sampling release, you must always use a shell window with the |NCS| toolchain environment. + The Toolchain Manager dropdown menu options - #. Run the following commands in your terminal to install the correct lxml dependency: + #. Select :guilabel:`Open command prompt`. - .. parsed-literal:: - :class: highlight + You can then follow the instructions in :ref:`creating_cmd`. - pip uninstall -y lxml - pip install lxml - - If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`ncs-lcs` directory, and start over. - -We recommend adding the nRF Util path to your environmental variables. - -.. _ug_nrf54h20_install_ncs: - -Installing the |NCS| -==================== - -After you have installed the toolchain, complete the following steps to get the customer sampling version of the |NCS|: - -1. In the terminal window opened during the toolchain installation, initialize west with the revision of the |NCS| from the customer sampling: +Installing the Terminal application +*********************************** - .. parsed-literal:: - :class: highlight +On your computer, install `nRF Connect for Desktop`_. +You must also install a terminal emulator, such as `nRF Connect Serial Terminal`_ (from the nRF Connect for Desktop application) or the nRF Terminal (part of the `nRF Connect for Visual Studio Code`_ extension). - west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.6.99-cs2 +Installing nRF Util and its commands +************************************ -#. Enter the following command to clone the project repositories:: +Using the nRF54H20 DK with the |NCS| 2.7 requires the following: - west update +* nRF Util version 7.11.1 or above +* nRF Util ``device`` version 2.4.0 - Depending on your connection, this might take some time. +1. Download the nrfutil executable file from the `nRF Util development tool`_ product page. +#. Add nRF Util to the system path to run it from anywhere on the system. + Use one of the following options: -#. Export a :ref:`Zephyr CMake package `. - This allows CMake to automatically load the boilerplate code required for building |NCS| applications:: + * Add nRF Util's directory to the system path. + * Move the file to a directory in the system path. - west zephyr-export +#. On macOS and Linux, give ``nrfutil`` execute permissions by typing ``chmod +x nrfutil`` in a terminal or using a file browser. + This is typically a checkbox found under file properties. +#. Verify the version of the nRF Util installation on your machine by running the following command:: -Your directory structure now looks similar to this:: + nrfutil --version - ncs-lcs/work-dir - |___ .west - |___ bootloader - |___ modules - |___ nrf - |___ nrfxlib - |___ zephyr - |___ ... +#. If your version is below 7.11.1, run the following command to update nRF Util:: -Note that there are additional folders, and that the structure might change. -The full set of repositories and folders is defined in the manifest file. + nrfutil self-upgrade -Installing the Terminal application -*********************************** +#. Install the nRF Util ``device`` command to version 2.4.0 as follows:: -On your computer, install `nRF Connect for Desktop`_. -You must also install a terminal emulator, such as `nRF Connect Serial Terminal`_ (from the nRF Connect for Desktop application) or the nRF Terminal (part of the `nRF Connect for Visual Studio Code`_ extension). + nrfutil install device=2.4.0 --force .. _ug_nrf54h20_gs_bringup: @@ -281,10 +215,10 @@ To prepare the nRF54H20 DK for first use, you must manually program the values o Programming the SDFW and SCFW ============================= -After programming the BICR, the nRF54H20 SoC requires the provisioning of a bundle ( :file:`nrf54h20_soc_binaries_v0.3.3.zip`) containing the precompiled firmware for the Secure Domain and System Controller. +After programming the BICR, the nRF54H20 SoC requires the provisioning of a bundle ( :file:`nrf54h20_soc_binaries_v0.5.0.zip`) containing the precompiled firmware for the Secure Domain and System Controller. To program the Secure Domain Firmware (SDFW, also known as ``urot``) and the System Controller Firmware (SCFW) from the firmware bundle to the nRF54H20 DK, do the following: -1. Download the `nRF54H20 firmware bundle`_. +1. Download the `nRF54H20 firmware bundle v0.5.0`_. #. Move the :file:`ZIP` bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:: nrfutil device x-provision-nrf54h --firmware --serial-number @@ -294,6 +228,10 @@ To program the Secure Domain Firmware (SDFW, also known as ``urot``) and the Sys Updating the FICR ================= +.. caution:: + This step is required only if your nRF54H20 DK is version PCA10175 v0.7.x or v0.8.0 (ES3). + Jump to the next step if your DK is version ES4. + After programming the SDFW and SCFW from the firmware bundle, you must update the Factory Information Configuration Registers (FICR) to correctly configure some trims of the nRF54H20 SoC. To update the FICR, you must run a J-Link script: @@ -301,9 +239,15 @@ To update the FICR, you must run a J-Link script: curl -LO https://files.nordicsemi.com/artifactory/swtools/external/scripts/nrf54h20es_trim_adjust.jlink -#. Run the script:: +#. Run the script: + + * Linux and Mac OS:: + + JLinkExe -CommanderScript nrf54h20es_trim_adjust.jlink + + * Windows:: - JLinkExe -CommanderScript nrf54h20es_trim_adjust.jlink + jlink.exe -CommanderScript nrf54h20es_trim_adjust.jlink .. rst-class:: numbered-step diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst deleted file mode 100644 index 1c71b6fddc73..000000000000 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst +++ /dev/null @@ -1,299 +0,0 @@ -:orphan: - -.. _ug_nrf54h20_matter_thread: - -Working with nRF54H20 and Matter and Thread -########################################### - -.. contents:: - :local: - :depth: 2 - -The nRF54H20 DK supports the following Matter and Thread samples: - -* :ref:`Matter door lock sample ` -* :ref:`Matter template sample ` -* :ref:`Thread CLI sample ` - -The Matter support is currently limited to Matter over Thread, and support for both Matter and Thread is currently :ref:`experimental `. -Read the following sections for more information about support in the nRF54H20 DK and the platform design for the nRF54H20 SoC. - -For more information about Matter and Thread in the |NCS|, read the documentation in the :ref:`ug_matter` and :ref:`ug_thread` protocol sections. - -Platform designs for the nRF54H20 SoC -************************************* - -Matter in the |NCS| supports the *System-on-Chip, multiprotocol* platform design for the nRF54H20 SoC using Matter over Thread. -You can read more about other available platform designs for Matter on the :ref:`Matter platform design page`. - -Thread in the |NCS| supports the *System-on-Chip, single protocol* and *System-on-Chip, multiprotocol* platform designs for the nRF54H20 SoC. -You can read more about other available platform designs for Thread on the :ref:`OpenThread architectures page`. - -For more information about the multiprotocol feature, see :ref:`ug_multiprotocol_support`. - -System-on-Chip, single protocol -=============================== - -In this design, the OpenThread stack runs on several cores and domains of a single nRF54H20 SoC. - -This platform designs is suitable for the following development kit: - -##TODO add to /includes/sample_board_rows.txt - -In this design: - -* The Application Core runs the OpenThread stack. -* The Radio Core runs the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. -* The Secure Domain stores all the secure components, including keys and certificates. - It also manages the access to peripherals, memory, and other components. - - .. note:: - The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. - -* The Global Domain manages clocks, power, global RAM, and global NVM. - -For more information, see :ref:`ug_nrf54h20_architecture_cpu`. - -The following figure demonstrates the architecture. -The Global Domain is not included. - -.. figure:: images/thread_platform_design_nRF54h20.svg - :alt: Multiprotocol Thread and Bluetooth LE architecture (nRF54H20) - - Single protocol Thread architecture on the nRF54H20 SoC - -System-on-Chip, multiprotocol -============================= - -In this design, the OpenThread stack and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. - -This platform design is suitable for the following development kit: - -##TODO add to /includes/sample_board_rows.txt - -In this design: - -* The Application Core runs the OpenThread stack, and a part of the Bluetooth LE Controller. -* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. -* The Secure Domain stores all the secure components, including keys and certificates. - It also manages the access to peripherals, memory, and other components. - - .. note:: - The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. - -* The Global Domain manages clocks, power, global RAM, and global NVM. - -For more information, see :ref:`ug_nrf54h20_architecture_cpu`. - -The following figure demonstrates the architecture. -The Global Domain is not included. - -.. _nrf54h20_platform_multi_figure: - -.. figure:: images/thread_platform_design_nRF54h20_multi.svg - :alt: Multiprotocol Thread and Bluetooth LE architecture (nRF54H20) - - Multiprotocol Thread and Bluetooth LE architecture on the nRF54H20 SoC - -Matter over Thread -================== - -In this design, the Matter stack, the OpenThread stack, and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. - -This platform design is suitable for the following development kit: - -##TODO add to /includes/sample_board_rows.txt - -In this design: - -* The Application Core runs the Matter stack, the OpenThread stack, and a part of the Bluetooth LE Controller. -* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. -* The Secure Domain stores all the secure components, including keys and certificates. - It also manages the access to peripherals, memory, and other components. - - .. note:: - The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. - -* The Global Domain manages clocks, power, global RAM, and global NVM. - -For more information, see :ref:`ug_nrf54h20_architecture_cpu`. - -Refer to the :ref:`nrf54h20_platform_multi_figure` figure to see the architecture of the SoC. -The Global Domain is not included. - -Additional requirements on the nRF54H20 DK -****************************************** - -In addition to the standard requirements for the |NCS|, such as the :ref:`ug_matter_gs_tools_gn` for Matter, you need the following to run Matter-enabled or Thread-enabled applications on the nRF54H20 DK: - -* For DFU - J-Link and a USB cable. -* nrfjprog from the `nRF Command Line Tools`_. - -Configuring Matter and Thread on the nRF54H20 DK -************************************************ - -Currently, only the configuration for Matter over Thread is supported for Matter. -Follow the configuration steps on the :ref:`ug_matter_gs_testing` page to configure the Matter environment for the supported Matter samples. - -Currently, only the :ref:`ot_cli_sample` sample is supported for Thread. -See the sample documentation for how to configure it. - -The Matter and Thread samples can work on the corresponding networks with standard devices of the same protocol. - -Programming Matter and Thread samples on the nRF54H20 DK -======================================================== - -To program the compatible Matter or Thread samples on the nRF54H20 DK, follow the :ref:`ug_nrf54h20_gs_sample` steps. -Read also programming guides prepared for specific Matter samples: :ref:`Matter door lock sample `, and :ref:`Matter template sample `. - -.. note:: - :ref:`Testing using Bluetooth LE with Nordic UART Service ` on the :ref:`Matter door lock sample ` is disabled by default. - -Logging for Matter and Thread samples on the nRF54H20 DK -======================================================== - -To read logs for Matter samples on the nRF54H20 DK, complete the following steps: - -1. Connect to the nRF54H20 DK using a USB cable. -#. Select the first available port to read the logs from. - -For more information, see :ref:`ug_nrf54h20_logging`. - -.. _ug_nrf54h20_matter_thread_matter_wifi: - -Matter over Wi-Fi -================= - -Matter over Wi-Fi is currently supported on the :ref:`Matter door lock sample ` and :ref:`Matter template sample `. - -In this design, the Matter stack, the Wi-Fi stack, and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. - -To run Matter over Wi-Fi on the nRF54H20 DK you need the additional ``nrf7002_ek`` shield attached through the nRF54H20 DK to the nRF7002 EK interposer board. - -In this design: - -* The Application Core runs the Matter stack, the Wi-Fi stack, and a part of the Bluetooth LE Controller. -* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. -* The Secure Domain stores all the secure components, including keys and certificates. - It also manages the access to peripherals, memory, and other components. - - .. note:: - The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. - -* The Global Domain manages clocks, power, global RAM, and global NVM. - -To build the sample with Matter over Wi-Fi support run the following command: - -.. code-block:: console - - west build -b nrf54h20dk/nrf54h20/cpuapp -- -DSHIELD=nrf700x_nrf54h20dk -DCONFIG_CHIP_WIFI=y - - -.. _ug_nrf54h20_matter_thread_suit_dfu: - -SUIT Device Firmware Upgrade support on the nRF54H20 DK -======================================================= - -The :ref:`SUIT Device Firmware Upgrade ` feature has been implemented on the nRF54H20 DK and you can use it in the :ref:`Matter door lock sample `. -In this solution, both Application and Radio Cores can be upgraded sequentially to the newest version using :ref:`SUIT hierarchical manifests `. -The SUIT DFU feature uses :ref:`SUIT manifests ` that contain components and images of the firmware and are used by the Secure Domain to replace, verify and run the firmware. -In the Matter Lock sample, we use the Simple Management Protocol (SMP) over Bluetooth LE transport to deliver the new firmware to the device's DFU partition and then the SUIT processor installs the image according to the instructions that are described in the manifest. -By default, the root manifest contains both Application and Radio Core images, but for the Matter sample the images need to be split to the separate cores and perform upgrades sequentially. -Currently, there is no protection against incompatibility between the new Radio Core and old Application Core images, so you need to ensure that compatibility. -We have prepared manifest templates in the ``configurations/nrf54h20dk_nrf54h20_cpuapp`` directory in the Matter lock sample which are prepared to generate two separate SUIT envelopes - one for the Application Core and another for the Radio Core. They are as follows: - - * :file:`app_envelope.yaml.jinja2` - Contains the procedures for SUIT directives that allow for the Application Core image to be updated. - * :file:`app_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for the Application Core image. - * :file:`multiprotocol_rad_envelope.yaml.jinja2` - Contains the procedures for SUIT directives that allow for the Radio Core image to be updated. - * :file:`multiprotocol_rad_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for the Radio Core image. - * :file:`root_hierarchical_envelope.yaml.jinja2` - Contains the procedures for SUIT directives to run the current firmware. - * :file:`root_hierarchical_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for running the current firmware. - -You can edit the templates for other purposes. -To learn how to do edit the manifest templates, see the :ref:`ug_nrf54h20_suit_customize_dfu` guide. - -To build the firmware with the SUIT DFU support, run the following command with the *number* replaced with the new image number, that should be higher than the previous one: - -.. parsed-literal:: - :class: highlight - - west build -b nrf54h20dk/nrf54h20/cpuapp -- -DSB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=*number* - -You can perform a DFU using the nRF Connect Device Manager mobile application or the :ref:`Mcumgr command-line tool `. -After building the sample you can find two SUIT envelopes created in the build directory and depending on the core type you can search for: - - * the :file:`build/zephyr/app.suit` file to get the SUIT envelope for the Application Core. - * the :file:`build/multiprotocol_rpmsg/zephyr/multiprotocol_rpmsg_subimage.suit` file to get the SUIT envelope for the Radio Core. - -To learn how to perform a DFU using the nRFConnect Device Manager mobile application read instructions in the ``suit smp transfer `` guide. - -Performing DFU on nRF54H20 DK using Mcumgr command-line tool ------------------------------------------------------------- - - 1. Follow the instructions in the :ref:`Mcumgr command-line tool ` guide to install Mcumgr. - #. Press **Button 1** to enable Bluetooth LE SMP advertising on the nRF54H20 DK. - #. Run the following command to upgrade the Radio Core: - - .. parsed-literal:: - :class: highlight - - mcumgr --conntype ble --hci *hci number* --connstring peer_name=*peer name* image upload *path to multiprotocol_rpmsg_subimage.suit* -n 0 -w 1 - - Where: - - * *hci number* is the Bluetooth LE device ID on your host device (by default it is ``0``). - * *peer name* is the Bluetooth LE name which is advertised by the nRF54H20 DK (by default ``"Matter Lock"``). - * *path to multiprotocol_rpmsg_subimage.suit* is a path to the SUIT envelope that contains Radio Core image. - - For example: - - .. parsed-literal:: - :class: highlight - - mcumgr --conntype ble --hci 0 --connstring peer_name="MatterLock" image upload build/multiprotocol_rpmsg/zephyr/multiprotocol_rpmsg_subimage.suit -n 0 -w 1 - - #. Press **Button 1** to enable Bluetooth LE SMP advertising on the nRF54H20 DK again, because the previous operation disabled it after applying the image. - #. Run the same command as in Step 3 to upgrade the Application Core image, but this time provide a path to the ``app.suit`` file. - - For example: - - .. parsed-literal:: - :class: highlight - - mcumgr --conntype ble --hci 0 --connstring peer_name="MatterLock" image upload build/zephyr/app.suit -n 0 -w 1 - - -Implementing support for the nRF54H20 DK -======================================== - -If you want to implement support for the nRF54H20 DK in your Matter-enabled or Thread-enabled application, read the :ref:`ug_nrf54h20_configuration` guide. - -.. _ug_nrf54h20_matter_thread_limitations: - -Limitations for Matter and Thread on the nRF54H20 DK -**************************************************** - -Matter and Thread support has the following limitations on the nRF54H20 DK: - -* DFU over Matter or Serial Link is not yet implemented. -* The current implementation is not power-optimized. -* The cryptographic operations related to Matter and Thread are performed on the Application Core, rather than on the Secure Domain. -* The ``west flash --erase`` command is blocked. - See :ref:`ug_nrf54h20_gs_sample` for more information. -* The factory reset functionality does not work properly. - After clearing all NVM storage, the device cannot reboot automatically and falls into a hard fault. - - As a workaround, press the reset button on the nRF54H20 DK board after performing a factory reset. -* Matter over Thread commissioning might be unstable due to the lack of true random generator support on nRF54H20. - - After each reboot or factory reset, the device will always have the same Bluetooth LE and IEEE 80215.4 addresses. - This might impact working within the Thread network because after the second and following connections, Thread Border Router will reject these connections until deleted from the database and commissioning to Matter will take more and more time. - - As a workaround, after each factory reset and before performing the next commissioning to Matter, connect to the device's serial port and run the following command: - - .. parsed-literal:: - :class: highlight - - ot extaddr *address* - - Replace the *address* argument with an 8-byte randomly generated MAC address, for example ``87fb47d5730ac0a0``. diff --git a/doc/nrf/gsg_guides.rst b/doc/nrf/gsg_guides.rst index ea4b762d2ecd..f741b988378b 100644 --- a/doc/nrf/gsg_guides.rst +++ b/doc/nrf/gsg_guides.rst @@ -17,6 +17,8 @@ This is not a comprehensive section that includes all of the available getting s * To get started with the nRF91x1 DKs, complete the steps in the `Quick Start`_ app, available from `nRF Connect for Desktop`_. * To get started with the nRF54L15 PDK, the installation of the |NCS| is required. See :ref:`ug_nrf54l15_gs`. + * To get started with the nRF54H20 DK, the installation of the |NCS| is required. + See :ref:`ug_nrf54h20_gs`. * To get started with the nPM1300 EK, see the `Get started `_ section of the nPM1300 EK product page. * To get started with the nRF7002 EB, see the `Get started `_ section of the nRF7002 EB product page. diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index d0387c6edb01..6dc2ca2cbd9f 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -1588,7 +1588,9 @@ .. _`curl`: https://curl.se/ -.. _`nRF54H20 firmware bundle`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.3.3.zip +.. _`nRF54H20 firmware bundle`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.5.0.zip +.. _`nRF54H20 firmware bundle v0.3.3`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.3.3.zip +.. _`nRF54H20 firmware bundle v0.5.0`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.5.0.zip .. _`BICR binary file`: https://files.nordicsemi.com/artifactory/SDSC/external/bicr_ext_loadcap.hex diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_nRF54H20_cs_to_2_7.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_nRF54H20_cs_to_2_7.rst new file mode 100644 index 000000000000..3c8b9f131e86 --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/migration_guide_nRF54H20_cs_to_2_7.rst @@ -0,0 +1,21 @@ +.. _migration_nrf4h20_to_2.7: + +Migration notes for |NCS| v2.7 for nRF54H20 users +################################################# + +This document describes the new features and changes implemented in |NCS| to take into consideration when migrating your application for the nRF54H20 DK to |NCS| v2.7. + +To ensure the nRF54H20 DK runs its components correctly, verify its compatibility with the |NCS| v2.7 release checking the version number on your DK's sticker. +The only versions of the nRF54H20 DK compatible with the |NCS| v2.7 are the following ones: + +* Version PCA10175 v0.7.x (ES3) +* Version PCA10175 v0.8.0 (ES3) +* Version ES4 + +.. toctree:: + :maxdepth: 1 + :glob: + :reversed: + :caption: Subpages: + + nRF54H20_migration_2.7/* diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink788j_install.png b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink788j_install.png new file mode 100644 index 000000000000..c1c6aa0d5a41 Binary files /dev/null and b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink788j_install.png differ diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink794e_install.png b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink794e_install.png new file mode 100644 index 000000000000..63fb110568aa Binary files /dev/null and b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink794e_install.png differ diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst new file mode 100644 index 000000000000..8087b1d240ae --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst @@ -0,0 +1,137 @@ +.. _migration_cs3_to_to_2_7_app: + +Migrate your application for the nRF54H20 DK to |NCS| v2.7 (for v2.4.99-cs3 users) +################################################################################## + +.. contents:: + :local: + :depth: 2 + +This document describes the changes you should be aware of when migrating your application from |NCS| for the nRF54 customer sampling release v2.4.99-cs3 to |NCS| v2.6.99-cs2. + + +Overview +******** + +|NCS| v2.6.99-cs2 introduced a series of changes that might affect your existing applications. +The following is a summary of the most important ones: + +Updated |NCS| toolchain + The |NCS| toolchain has been updated. + See :ref:`transition_cs3_to_2_7_env` for more info on how to upgrade your current |NCS| installation based on version 2.4.99-cs3. + +SDFW and SCFW + The Secure Domain Firmware (SDFW) and System Controller Firmware (SCFW) are no longer built from the source during the application build process, but they are installed as binaries from the provided firmware bundle and programmed when flashing the application to the device. + For additional details, see :ref:`transition_cs3_to_2_7_env_bringup`. + +nRF Util has now replaced nRF Command Line Tools. + nRF Util is now the main command line backend utility. + +Updated boards + SOC1-based boards have been removed and FP1-based board have been added. + The board names for the Application, Radio, and PPR core have been updated. + +DTS changes + The layout of DTS files and the names of DTS nodes related to the updated board names have been also updated, also affecting overlay files from applications and samples. + If your application required a specific custom board, you must update the custom board files to match the changes done to the nRF54H20 SoC DTS files. + +Lifecycle State changes + To correctly operate the nRF54H20 DK, it must be set in LCS ``RoT``. + + Also, it is no longer possible to perform an unauthenticated backward LCS transitions. + This means that once set to ``RoT``, it is no longer possible to revert to LCS state ``EMPTY``. + +.. + ### Add DTS changes ### + add sysbuild and hwmodelv2 links + +.. note:: + Not all the features supported in |NCS| v2.4.99-cs3 have been ported to v2.6.99-cs2 (for example, the nRF54H20 support for the nRF Desktop and nRF Machine Learning applications). + Additional features will be provided in future releases. + +Required changes +**************** + +The following changes are mandatory to make your application work in the same way as in previous releases. + +This section describes the changes related to samples and applications. + +Samples and applications +======================== + + + +General +------- + +.. toggle:: + + * The nRF54H20 DK samples and applications are now using the following FP1-based board names: + + * Application core: ``nrf54h20dk_nrf54h20_cpuapp`` (Previously ``nrf54h20pdk_nrf54h20_cpuapp@soc1``) + * Radio core: ``nrf54h20dk_nrf54h20_cpurad`` (Previously ``nrf54h20pdk_nrf54h20_cpurad@soc1``) + * PPR core: ``nrf54h20dk_nrf54h20_cpuppr`` (Previously ``nrf54h20pdk_nrf54h20_cpuppr@soc1``) + + The previously used SOC1-based board files have been removed. + +Security +======== + +.. toggle:: + + * For samples using ``CONFIG_NRF_SECURITY``: + + * RSA keys are no longer enabled by default. + This reduces the code size by 30 kB if not using RSA keys. + This also breaks the configuration if using the RSA keys without explicitly enabling an RSA key size. + Enable the required key size to fix the configuration, for example by setting the Kconfig option :kconfig:option:`CONFIG_PSA_WANT_RSA_KEY_SIZE_2048` if 2048-bit RSA keys are required. + + * The PSA config is now validated by the :file:`ncs/nrf/ext/oberon/psa/core/library/check_crypto_config.h` file. + Users with invalid configurations must update their PSA configuration according to the error messages that the :file:`check_crypto_config.h` file provides. + + * For the :ref:`crypto_persistent_key` sample: + + * The Kconfig option ``CONFIG_PSA_NATIVE_ITS`` is replaced by the Kconfig option :kconfig:option:`CONFIG_TRUSTED_STORAGE`, which enables the new :ref:`trusted_storage_readme` library. + The :ref:`trusted_storage_readme` library provides the PSA Internal Trusted Storage (ITS) API for build targets without TF-M. + It is not backward compatible with the previous PSA ITS implementation. + Migrating from the PSA ITS implementation, enabled by the ``CONFIG_PSA_NATIVE_ITS`` option, to the new :ref:`trusted_storage_readme` library requires manual data migration. + + * For :ref:`lib_wifi_credentials` library and Wi-Fi samples: + + * ``CONFIG_WIFI_CREDENTIALS_BACKEND_PSA_UID_OFFSET`` has been removed because it was specific to the previous solution that used PSA Protected Storage instead of PSA Internal Trusted Storage (ITS). + Use :kconfig:option:`CONFIG_WIFI_CREDENTIALS_BACKEND_PSA_OFFSET` to specify the key offset for PSA ITS. + Be aware that Wi-Fi credentials stored in Protected Storage will not appear in ITS when switching. + To avoid re-provisioning Wi-Fi credentials, manually read out the old credentials from Protected Storage in the previously used UID and store to ITS. + +zcbor +===== + +.. toggle:: + + * If you have zcbor-generated code that relies on the zcbor libraries through Zephyr, you must regenerate the files using zcbor 0.8.1. + Note that the names of generated types and members has been overhauled, so the code using the generated code must likely be changed. + + For example: + + * Leading single underscores and all double underscores are largely gone. + * Names sometimes gain suffixes like ``_m`` or ``_l`` for disambiguation. + * All enum (choice) names have now gained a ``_c`` suffix, so the enum name no longer matches the corresponding member name exactly (because this previously broke the C++ namespace rules). + + * The functions :c:func:`zcbor_new_state`, :c:func:`zcbor_new_decode_state` and the macro :c:macro:`ZCBOR_STATE_D` have gained new parameters related to the decoding of unordered maps. + If you are not using this functionality, you can set the functions and the macro to ``NULL`` or ``0``. + * The functions :c:func:`zcbor_bstr_put_term` and :c:func:`zcbor_tstr_put_term` have gained a new parameter ``maxlen``, referring to the maximum length of the parameter ``str``. + This parameter is passed directly to :c:func:`strnlen` under the hood. + * The function :c:func:`zcbor_tag_encode` has been renamed to :c:func:`zcbor_tag_put`. + * Printing has been changed significantly, for example, :c:func:`zcbor_print` is now called :c:func:`zcbor_log`, and :c:func:`zcbor_trace` with no parameters is gone, and in its place are :c:func:`zcbor_trace_file` and :c:func:`zcbor_trace`, both of which take a ``state`` parameter. + +Recommended changes +******************* + +The following changes are recommended for your application to work optimally after the migration. + +General +======= + +.. toggle:: + + * Applications that use :file:`prj_.conf` Kconfig configurations should be transitioned to using :file:`boards/.conf` Kconfig fragments. diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst new file mode 100644 index 000000000000..52c8b489dedd --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst @@ -0,0 +1,54 @@ +.. _migration_2_6_99_cs2_to_2_7_app: + +Migrate your application to |NCS| v2.7 (for v2.6.99-cs2 users) +############################################################## + +.. contents:: + :local: + :depth: 2 + +This document describes the changes you should be aware of when migrating your application from |NCS| for the nRF54 customer sampling release v2.6.99-cs2 to |NCS| v2.7. + + + +Overview +******** + +|NCS| v2.7 introduced a series of changes that might affect your existing applications. +The following is a summary of the most important ones: + +.. + ### Add DTS changes ### Add other changes add sysbuild and hwmodelv2 + + +Required changes +**************** + +The following changes are mandatory to make your application work in the same way as in previous releases. + +This section describes the changes related to samples and applications. + +Samples and applications +======================== + + +General +------- + + + +Security +======== + + +zcbor +===== + + +Recommended changes +******************* + +The following changes are recommended for your application to work optimally after the migration. + +General +======= diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2_7_environment.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2_7_environment.rst new file mode 100644 index 000000000000..b8c1e1be8380 --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2_7_environment.rst @@ -0,0 +1,307 @@ +.. _migration_cs2_to_2_7_env: + +Update your development environment for |NCS| v2.7 (for v2.6.99-cs2 users) +########################################################################## + +.. contents:: + :local: + :depth: 2 + +This document describes how to update your development environment for the nRF54H20 DK from |NCS| v2.6.99-cs2 to |NCS| v2.7. + +The main development environment changes introduced by 2.7 for the nRF54H20 DK are the following: + +.. + ##TODO + +Minimum requirements +******************** + +Make sure you have all the required hardware, software, and that your computer has one of the supported operating systems. + +Hardware +======== + +* nRF54H20 DK version PCA10175 v0.7.x or v0.8.0 (ES3), ES4. + These are the only versions of the nRF54H20 DK compatible with |NCS| 2.7. + Check the version number on your DK's sticker to verify its compatibility with |NCS| version 2.7. +* USB-C cable. + +Software +======== + +On your computer, one of the following operating systems: + +.. include:: ../../../../nrf/installation/recommended_versions.rst + :start-after: os_table_start + :end-before: os_table_end + +See :ref:`supported_OS` for more information about the tier definitions. + +|supported OS| + +You also need the following: + +* `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively) +* `curl`_ +* On Windows, SEGGER USB Driver for J-Link +* SEGGER `J-Link version 7.94e`_ + +Updating the |NCS| and its toolchain +************************************ + +You can update to the |NCS| v2.7 and its toolchain by using Toolchain Manager. + +Toolchain Manager is a tool available from `nRF Connect for Desktop`_, a cross-platform tool that provides different applications that simplify installing the |NCS|. +Both the tool and the application are available for Windows, Linux, and macOS. + +To proceed with the update, complete the following steps: + +1. Install Toolchain Manager: + + a. `Download nRF Connect for Desktop`_ for your operating system. + #. Install and run the tool on your machine. + #. In the **APPS** section, click :guilabel:`Install` next to Toolchain Manager. + + The app is installed on your machine, and the :guilabel:`Install` button changes to :guilabel:`Open`. + +#. Open the Toolchain Manager application in nRF Connect for Desktop. +#. Click the button with the arrow pointing down next to the installed |NCS| version to expand the drop-down menu with options. + + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm_dropdown.png + :alt: The Toolchain Manager dropdown menu for the installed nRF Connect SDK version, cropped + + The Toolchain Manager dropdown menu options + +#. In the drop-down menu, click :guilabel:`Update toolchain`. +#. In the same drop-down menu, click :guilabel:`Update SDK`. + +Updating the Terminal application +********************************* + +To update `Serial Terminal from nRF Connect for Desktop`, follow these steps: + +1. On your computer, open `nRF Connect for Desktop`_ + If there is an update available, a pop up will notify you of its availability. +#. If available, install the update from the pop up screen. +#. Update `Serial Terminal from nRF Connect for Desktop`. + +If you are using the nRF Terminal application part of the `nRF Connect for Visual Studio Code`_ extension, open Visual Studio Code instead and ensure you are running the newest version of both the editor and the extension. + +Updating nRF Util and its commands +********************************** + +|NCS| 2.7 requires nRF Util version 7.11.1 or above. + +1. Verify the version of the nRF Util installation on your machine by running the following command:: + + nrfutil --version + +#. If your version is below 7.11.1, run the following command to update nRF Util:: + + nrfutil self-upgrade + +#. Add nRF Util to the system path to run it from anywhere on the system. + Use one of the following options: + + * Add nRF Util's directory to the system path. + * Move the file to a directory in the system path. + +#. On macOS and Linux, give ``nrfutil`` execute permissions by typing ``chmod +x nrfutil`` in a terminal or using a file browser. + This is typically a checkbox found under file properties. +#. Update the nRF Util ``device`` command to version 2.4.0 as follows:: + + nrfutil install device=2.4.0 --force + +.. _migration_cs2_to_2_7_env_bringup: + +Verify the LCS of the device +**************************** + +The current nRF54H20 DK is delivered with its lifecycle state (LCS) set to ``EMPTY``. +To correctly operate, its lifecycle state must be transitioned to Root of Trust (``RoT``) through the bring-up steps. + +.. note:: + The forward transition to LCS ``RoT`` is permanent. + After the transition, it is not possible to transition backward to LCS ``EMPTY``. + +However, you must follow different steps to program the most updated version of the SDFW and the SCFW on a device in ``RoT``. +So you must verify the current lifecycle state of the nRF54H20 as follows:: + + nrfutil device x-adac-discovery --serial-number + +The output will look similar to the following:: + + *serial_number* + adac_auth_version 1.0 + vendor_id Nordic VLSI ASA + soc_class 0x00005420 + soc_id [e6, 6f, 21, b6, dc, be, 11, ee, e5, 03, 6f, fe, 4d, 7b, 2e, 07] + hw_permissions_fixed [00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + hw_permissions_mask [01, 00, 00, 00, 87, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + psa_lifecycle LIFECYCLE_EMPTY (0x1000) + sda_id 0x01 + secrom_revision 0xad3b3cd0 + sysrom_revision 0xebc8f190 + token_formats [TokenAdac] + cert_formats [CertAdac] + cryptosystems [Ed25519Sha512] + Additional TLVs: + TargetIdentity: [ff, ff, ff, ff, ff, ff, ff, ff] + +If the lifecycle state (``psa_lifecycle``) shown is ``RoT`` (``LIFECYCLE_ROT (0x2000)``), the device is in +If the lifecycle state (``psa_lifecycle``) shown is not ``RoT`` (``LIFECYCLE_EMPTY (0x1000)`` means the LCS is set to ``EMPTY``) you can follow the bring-up steps below. + +nRF54H20 DK bring-up +******************** + +.. caution:: + Follow these steps only if your device is in lifecycle state ``EMPTY``. + For more information, see `Verify the LCS of the device`_. + +The following sections describe the steps required for the nRF54H20 bring-up. + +.. rst-class:: numbered-step + +Programming the BICR +==================== + +The Board Information Configuration Registers (BICR) are non-volatile memory (NVM) registers that contain information on how the nRF54H20 SoC must interact with other board elements, including the information about the power and clock delivery to the SoC. +To prepare the nRF54H20 DK for first use, you must manually program the values of the BICR using a precompiled BICR binary file (:file:`bicr_ext_loadcap.hex`). + +1. Download the `BICR binary file`_ . +#. List all the connected development kits to see their serial number (matching the one on the DK's sticker):: + + nrfutil device list + +#. Move the BICR HEX file to a folder of your choice, then program the BICR by running nRF Util from that folder using the following command:: + + nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware bicr_ext_loadcap.hex --core Secure --serial-number + +.. rst-class:: numbered-step + +Provisioning the SDFW and SCFW +============================== + +After programming the BICR, the nRF54H20 SoC requires the provisioning of a bundle ( :file:`nrf54h20_soc_binaries_v0.5.0.zip`) containing the precompiled firmware for the Secure Domain and System Controller. +To program the Secure Domain Firmware (SDFW, also known as ``urot``) and the System Controller Firmware (SCFW) from the firmware bundle to the nRF54H20 DK, do the following: + +1. Download the `nRF54H20 firmware bundle v0.5.0`_. +#. Move the :file:`ZIP` bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:: + + nrfutil device x-provision-nrf54h --firmware --serial-number + +.. rst-class:: numbered-step + +Updating the FICR +================= + +.. caution:: + This step is required only if your nRF54H20 DK is version PCA10175 v0.7.x or v0.8.0 (ES3). + Jump to the next step if your DK is version ES4. + +After programming the SDFW and SCFW from the firmware bundle, you must update the Factory Information Configuration Registers (FICR) to correctly configure some trims of the nRF54H20 SoC. +To update the FICR, you must run a J-Link script: + +1. Get the Jlink script that updates the FICR:: + + curl -LO https://files.nordicsemi.com/artifactory/swtools/external/scripts/nrf54h20es_trim_adjust.jlink + +#. Run the script: + + * Linux and Mac OS:: + + JLinkExe -CommanderScript nrf54h20es_trim_adjust.jlink + + * Windows:: + + jlink.exe -CommanderScript nrf54h20es_trim_adjust.jlink + +.. _migration_cs2_to_2_7_env_lcsrot: + +.. rst-class:: numbered-step + +Transitioning the nRF54H20 SoC to RoT +===================================== + +Set the device to Root of Trust using the following command:: + + nrfutil device x-adac-lcs-change --life-cycle rot --serial-number + +#. Verify again the current lifecycle state of the nRF54H20:: + + nrfutil device x-adac-discovery --serial-number + + The output will look similar to the following:: + + *serial_number* + adac_auth_version 1.0 + vendor_id Nordic VLSI ASA + soc_class 0x00005420 + soc_id [e6, 6f, 21, b6, dc, be, 11, ee, e5, 03, 6f, fe, 4d, 7b, 2e, 07] + hw_permissions_fixed [00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + hw_permissions_mask [01, 00, 00, 00, 87, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + psa_lifecycle LIFECYCLE_ROT (0x2000) + sda_id 0x01 + secrom_revision 0xad3b3cd0 + sysrom_revision 0xebc8f190 + token_formats [TokenAdac] + cert_formats [CertAdac] + cryptosystems [Ed25519Sha512] + Additional TLVs: + TargetIdentity: [ff, ff, ff, ff, ff, ff, ff, ff] + + The lifecycle state (``psa_lifecycle``) is now correctly set to *Root of Trust* (``LIFECYCLE_ROT (0x2000)``) + +#. After the LCS transition, reset the device:: + + nrfutil device reset --reset-kind RESET_PIN --serial-number + +nRF54H20 DK firmware bundle update +********************************** + +.. caution:: + Follow these steps only if your device is in lifecycle state ``RoT``. + For more information, see `Verify the LCS of the device`_. + +If your device is in ``RoT``, you can update to the newest release of the firmware bundle as follows: + +1. Download the `nRF54H20 firmware bundle v0.5.0`_. +#. Move the :file:`ZIP` bundle to a folder of your choice and unzip the bundle. +#. Purge all the domains:: + + nrfutil device x-boot-mode-set --boot-mode safe --traits jlink + nrfutil device erase --all --traits jlink --log-level trace --core Application + nrfutil device erase --all --traits jlink --log-level trace --core Network + nrfutil device x-boot-mode-set --boot-mode normal --traits jlink + +#. Program the SDFW update:: + + nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware uslot_download.hex --core Application --serial-number + +#. Instruct SDFW to instruct SDROM to apply the update:: + + nrfutil device x-ssf-sdfw-update --traits jlink --tbs-addr 0x0e100000 --dl-max 0x4b000 --dl-addr-fw 0x0e100160 --dl-addr-pk 0x0e100100 --dl-addr-signature 0x0e100120 --log-level debug + +#. Do a pin-reset for SDROM to apply the update:: + + nrfutil device reset --reset-kind RESET_PIN --serial-number + +#. Check the current SDFW version:: + + python nrf/scripts/sdfw/main.py version --type 1 + +# The output should be as follows:: + + <-- AdacResponse(status=, data=b'\x05\x00\x00\x06') + +Next steps +********** + +.. + ##TODO update all the following links + +Your environment is now set to use the |NCS| v2.7 with the nRF54H20 DK: + +* If you want to modify your existing custom applications previously developed for |NCS| v2.6.99-cs2 to be compatible with v2.7, consult ``new_migration_guide``. +* If you want to build and program a sample application on your nRF54H20 DK, consult the building and programming section in the ``nRF54H20 DK getting started guide for the nRF Connect SDK v2.7``. diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/transition_guide_2.4.99-cs3_to_2.7_environment.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/transition_guide_2.4.99-cs3_to_2.7_environment.rst new file mode 100644 index 000000000000..d64d2fdd797b --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/transition_guide_2.4.99-cs3_to_2.7_environment.rst @@ -0,0 +1,324 @@ +.. _transition_cs3_to_2_7_env: + +Transition your development environment to |NCS| v2.7 (for v2.4.99-cs3 users) +############################################################################# + +.. contents:: + :local: + :depth: 2 + +This document describes how to transition your development environment for the nRF54H20 DK from |NCS| v2.4.99-cs3 to |NCS| v2.7. + +The main development environment changes introduced by 2.7 for the nRF54H20 DK are the following: + +* The |NCS| toolchain has been updated. +* nRF Util has now replaced nRF Command Line Tools. + The bootstrap script will now install and update nRF Util. +* SDFW and SCFW are now provided as precompiled binaries. + The Secure Domain Firmware (SDFW) and System Controller Firmware (SCFW) are no longer built from the source during the application build process, but they must be provisioned as binaries from the provided firmware bundle before the DK can be used. + See the details in the `nRF54H20 DK bring-up`_ section below. +* The nRF54H20 SoC lifecycle state must now be set to Root of Trust (RoT). + See the details in the `Transitioning the nRF54H20 SoC to RoT`_ section. + +Minimum requirements +******************** + +Make sure you have all the required hardware, software, and that your computer has one of the supported operating systems. + +Hardware +======== + +* nRF54H20 DK version PCA10175 v0.7.x or v0.8.0 (ES3), ES4. + These are the only versions of the nRF54H20 DK compatible with |NCS| 2.7. + Check the version number on your DK's sticker to verify its compatibility with |NCS| version 2.7. +* USB-C cable. + +Software +======== + +On your computer, one of the following operating systems: + +.. include:: ../../../../nrf/installation/recommended_versions.rst + :start-after: os_table_start + :end-before: os_table_end + +See :ref:`supported_OS` for more information about the tier definitions. + +|supported OS| + +You also need the following: + +* `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively) +* `curl`_ +* On Windows, SEGGER USB Driver for J-Link +* SEGGER `J-Link version 7.94e`_ + +.. note:: + The SEGGER USB Driver for J-Link was included, on Windows, in the nRF Command Line Tools bundle required by the |NCS| v2.4.99-cs3. + When updating SEGGER J-Link to version 7.94e on Windows, select :guilabel:`Update existing installation` under :guilabel:`Choose destination` in the :guilabel:`choose optional components` window. + + See the following screenshot: + + .. figure:: images/jlink794e_install.png + :alt: Optional components in the J-Link installation + +Preliminary step +**************** + +Before transitioning to the new toolchain, rename your existing ``ncs-lcs`` and ``.west`` folders (for example as ``ncs-lcs_old`` and ``.west_old``) to backup their files. + +Transitioning to the |NCS| v2.7 +******************************* + +You can transition to the |NCS| v2.7 by using Toolchain Manager. + +Toolchain Manager is a tool available from `nRF Connect for Desktop`_, a cross-platform tool that provides different applications that simplify installing the |NCS|. +Both the tool and the application are available for Windows, Linux, and macOS. + +To install the toolchain and the SDK using the Toolchain Manager app, complete the following steps: + +1. Install Toolchain Manager: + + a. `Download nRF Connect for Desktop`_ for your operating system. + #. Install and run the tool on your machine. + #. In the **APPS** section, click :guilabel:`Install` next to Toolchain Manager. + + The app is installed on your machine, and the :guilabel:`Install` button changes to :guilabel:`Open`. + +#. Install the |NCS| source code: + + a. Open Toolchain Manager in nRF Connect for Desktop. + + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm.png + :alt: The Toolchain Manager window + + The Toolchain Manager window + + #. Click :guilabel:`SETTINGS` in the navigation bar to specify where you want to install the |NCS|. + #. In :guilabel:`SDK ENVIRONMENTS`, click the :guilabel:`Install` button next to the |NCS| version 2.7. + + The |NCS| version 2.7 is installed on your machine. + The :guilabel:`Install` button changes to :guilabel:`Open VS Code`. + +#. Set up the preferred building method: + + .. tabs:: + + .. tab:: nRF Connect for Visual Studio Code + + To build on the |nRFVSC|, complete the following steps: + + a. In Toolchain Manager, click the :guilabel:`Open VS Code` button. + + A notification appears with a list of missing extensions that you need to install, including those from the `nRF Connect for Visual Studio Code`_ extension pack. + #. Click **Install missing extensions**. + #. Once the extensions are installed, click **Open VS Code** button again. + + You can then follow the instructions in :ref:`creating_vsc`. + + .. tab:: Command line + + To build on the command line, complete the following steps: + + 1. With admin permissions enabled, download and install the `nRF Command Line Tools`_. + #. Restart the Toolchain Manager application. + #. Click the dropdown menu for the installed nRF Connect SDK version. + + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm_dropdown.png + :alt: The Toolchain Manager dropdown menu for the installed nRF Connect SDK version, cropped + + The Toolchain Manager dropdown menu options + + #. Select :guilabel:`Open command prompt`. + + You can then follow the instructions in :ref:`creating_cmd`. + +#. If you have any existing custom applications created for 2.4.99-cs3 that you would like to migrate, move its files from the previous ``ncs-lcs_old`` folder to the newly created |NCS| installation folder. + +Updating the Terminal application +********************************* + +To update `Serial Terminal from nRF Connect for Desktop`, follow these steps: + +1. On your computer, open `nRF Connect for Desktop`_ + If there is an update available, a pop up will notify you of its availability. +#. If available, install the update from the pop up screen. +#. Update `Serial Terminal from nRF Connect for Desktop`. + +If you are using the nRF Terminal application part of the `nRF Connect for Visual Studio Code`_ extension, open Visual Studio Code instead and ensure you are running the newest version of both the editor and the extension. + +Installing nRF Util and its commands +************************************ + +Using the nRF54H20 DK with the |NCS| 2.7 requires the following: + +* nRF Util version 7.11.1 or above +* nRF Util ``device`` version 2.4.0 + +1. Download the nrfutil executable file from the `nRF Util development tool`_ product page. +#. Add nRF Util to the system path to run it from anywhere on the system. + Use one of the following options: + + * Add nRF Util's directory to the system path. + * Move the file to a directory in the system path. + +#. On macOS and Linux, give ``nrfutil`` execute permissions by typing ``chmod +x nrfutil`` in a terminal or using a file browser. + This is typically a checkbox found under file properties. +#. Verify the version of the nRF Util installation on your machine by running the following command:: + + nrfutil --version + +#. If your version is below 7.11.1, run the following command to update nRF Util:: + + nrfutil self-upgrade + +#. Install the nRF Util ``device`` command to version 2.4.0 as follows:: + + nrfutil install device=2.4.0 --force + +.. _transition_cs3_to_2_7_env_bringup: + +nRF54H20 DK bring-up +******************** + +The following sections describe the steps required for the nRF54H20 bring-up. + +.. rst-class:: numbered-step + +Programming the BICR +==================== + +The Board Information Configuration Registers (BICR) are non-volatile memory (NVM) registers that contain information on how the nRF54H20 SoC must interact with other board elements, including the information about the power and clock delivery to the SoC. +To prepare the nRF54H20 DK for first use, you must manually program the values of the BICR using a precompiled BICR binary file (:file:`bicr_ext_loadcap.hex`). + +1. Download the `BICR binary file`_ . +#. List all the connected development kits to see their serial number (matching the one on the DK's sticker):: + + nrfutil device list + +#. Move the BICR HEX file to a folder of your choice, then program the BICR by running nRF Util from that folder using the following command:: + + nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware bicr_ext_loadcap.hex --core Secure --serial-number + +.. rst-class:: numbered-step + +Programming the SDFW and SCFW +============================= + +After programming the BICR, the nRF54H20 SoC requires the provisioning of a bundle ( :file:`nrf54h20_soc_binaries_v0.5.0.zip`) containing the precompiled firmware for the Secure Domain and System Controller. +To program the Secure Domain Firmware (SDFW, also known as ``urot``) and the System Controller Firmware (SCFW) from the firmware bundle to the nRF54H20 DK, do the following: + +1. Download the `nRF54H20 firmware bundle v0.5.0`_. +#. Move the :file:`ZIP` bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:: + + nrfutil device x-provision-nrf54h --firmware --serial-number + +.. rst-class:: numbered-step + +Updating the FICR +================= + +.. caution:: + This step is required only if your nRF54H20 DK is version PCA10175 v0.7.x or v0.8.0 (ES3). + Jump to the next step if your DK is version ES4. + +After programming the SDFW and SCFW from the firmware bundle, you must update the Factory Information Configuration Registers (FICR) to correctly configure some trims of the nRF54H20 SoC. +To update the FICR, you must run a J-Link script: + +1. Get the Jlink script that updates the FICR:: + + curl -LO https://files.nordicsemi.com/artifactory/swtools/external/scripts/nrf54h20es_trim_adjust.jlink + +#. Run the script: + + * Linux and Mac OS:: + + JLinkExe -CommanderScript nrf54h20es_trim_adjust.jlink + + * Windows:: + + jlink.exe -CommanderScript nrf54h20es_trim_adjust.jlink + +.. _transition_cs3_to_2_7_env_lcsrot: + +.. rst-class:: numbered-step + +Transitioning the nRF54H20 SoC to RoT +===================================== + +The current nRF54H20 DK is delivered with its lifecycle state (LCS) set to ``EMPTY``. +To correctly operate, its lifecycle state must be transitioned to Root of Trust (``RoT``). + +.. note:: + The forward transition to LCS ``RoT`` is permanent. + After the transition, it is not possible to transition backward to LCS ``EMPTY``. + +To transition the LCS to ``RoT``, do the following: + +1. Verify the current lifecycle state of the nRF54H20:: + + nrfutil device x-adac-discovery --serial-number + + The output will look similar to the following:: + + *serial_number* + adac_auth_version 1.0 + vendor_id Nordic VLSI ASA + soc_class 0x00005420 + soc_id [e6, 6f, 21, b6, dc, be, 11, ee, e5, 03, 6f, fe, 4d, 7b, 2e, 07] + hw_permissions_fixed [00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + hw_permissions_mask [01, 00, 00, 00, 87, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + psa_lifecycle LIFECYCLE_EMPTY (0x1000) + sda_id 0x01 + secrom_revision 0xad3b3cd0 + sysrom_revision 0xebc8f190 + token_formats [TokenAdac] + cert_formats [CertAdac] + cryptosystems [Ed25519Sha512] + Additional TLVs: + TargetIdentity: [ff, ff, ff, ff, ff, ff, ff, ff] + +#. If the lifecycle state (``psa_lifecycle``) shown is ``RoT`` (``LIFECYCLE_ROT (0x2000)``), no LCS transition is required. + If the lifecycle state (``psa_lifecycle``) shown is not ``RoT`` (``LIFECYCLE_EMPTY (0x1000)`` means the LCS is set to ``EMPTY``), set it to Root of Trust using the following command:: + + nrfutil device x-adac-lcs-change --life-cycle rot --serial-number + +#. Verify again the current lifecycle state of the nRF54H20:: + + nrfutil device x-adac-discovery --serial-number + + The output will look similar to the following:: + + *serial_number* + adac_auth_version 1.0 + vendor_id Nordic VLSI ASA + soc_class 0x00005420 + soc_id [e6, 6f, 21, b6, dc, be, 11, ee, e5, 03, 6f, fe, 4d, 7b, 2e, 07] + hw_permissions_fixed [00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + hw_permissions_mask [01, 00, 00, 00, 87, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + psa_lifecycle LIFECYCLE_ROT (0x2000) + sda_id 0x01 + secrom_revision 0xad3b3cd0 + sysrom_revision 0xebc8f190 + token_formats [TokenAdac] + cert_formats [CertAdac] + cryptosystems [Ed25519Sha512] + Additional TLVs: + TargetIdentity: [ff, ff, ff, ff, ff, ff, ff, ff] + + The lifecycle state (``psa_lifecycle``) is now correctly set to *Root of Trust* (``LIFECYCLE_ROT (0x2000)``) + +#. After the LCS transition, reset the device:: + + nrfutil device reset --reset-kind RESET_PIN --serial-number + +Next steps +********** + +.. + ##TODO update all the following links + +Your environment is now set to use the |NCS| v2.7 with the nRF54H20 DK: + +* If you want to modify your existing custom applications previously developed for |NCS| v2.4.99-cs3 to be compatible with v2.7, consult ``new_migration_guide``. +* If you want to build and program a sample application on your nRF54H20 DK, consult the building and programming section in the ``nRF54H20 DK getting started guide for the nRF Connect SDK v2.7``.