Skip to content

Commit

Permalink
doc: Added nRF54H20 migration guides for NCS 2.7
Browse files Browse the repository at this point in the history 
Added nRF54H20 migration guides for NCS 2.7.

Signed-off-by: Francesco Domenico Servidio <[email protected]>
  • Loading branch information
@FrancescoSer @zycz
FrancescoSer authored and zycz committed Jun 18, 2024
1 parent a87c172 commit 2f6b34a
Show file tree
Hide file tree
Showing 11 changed files with 931 additions and 439 deletions.
222 changes: 83 additions & 139 deletions doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand All @@ -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|

Expand Down Expand Up @@ -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 <req_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 <zephyr:cmake_pkg>`.
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:

Expand Down Expand Up @@ -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 <path-to_bundle_zip_file> --serial-number <serial_number>
Expand All @@ -294,16 +228,26 @@ 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:

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::
#. 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

Expand Down
Loading

0 comments on commit 2f6b34a

Please sign in to comment.