Over-the-Air Update

Over-the-Air (OTA) Update enables you to update NVIDIA® Jetson™ devices and host computers for Jetson development.
Jetson Linux supports two forms of OTA which are used for different purposes. Debian package management-based OTA can update Jetson devices running Jetson Linux or Jetson components on a host computer. Image-based OTA lets you create OTA payload packages, and can update the full image running on a Jetson device, partition by partition. This topic describes both forms of OTA.

Updating from the NVIDIA APT Server

The first form of OTA update uses Debian packages obtained from an NVIDIA APT server. You can use this form of OTA update to update a Jetson device running Jetson Linux or to update Jetpack components installed on a host computer running Ubuntu. The APT server maintains respective groups of Debian packages for each purpose.
This section describes the tools and packages that provide basic support for Jetson Linux.
Note:
You cannot use OTA update to update a Jetson device on which Jetpack is installed.
To update JetPack and Jetson Linux components to a new JetPack release on a system where both are installed, see the instructions in the JetPack documentation.
NVIDIA does not recommend installing OTA Debian packages on a Jetson Linux release earlier than release 32.3.1, or on a system that is based on Ubuntu without the customization of Jetson Linux.

Updating a Jetson Device

Use the appropriate procedure below to update your system:
To update to a new point release of the same minor release; for example, from release 32.4.1 to 32.4.2
To update to new minor release; for example, from release 32.3.x to 32.4.2
To update to a new point release
1. Enter the command:
$ sudo apt update
apt reads a list of packages from the remote APT repository and identifies new and upgradable packages.
2. Enter the command:
apt list --upgradable
apt displays a list of new and upgradable packages.
3. To install the basic packages for Jetson Linux, enter the command:
sudo apt upgrade
4. Reboot your Jetson device when the upgrade is finished.
To update to a new minor release
1. Open the apt source configuration file in a text editor, for example:
$ sudo vi /etc/apt/sources.list.d/nvidia-l4t-apt-source.list
2. Change the repository name and download URL in the deb commands.
The original commands are:
deb https://repo.download.nvidia.com/jetson/common <release> main
deb https://repo.download.nvidia.com/jetson/<platform> <release> main
Where:
<release> is the release number of the minor release you want to update to. For example, to update to minor release 32.2, replace r32 with r32.2. OTA updates to the latest point release of the specified minor release (release 32.2.1 in this case).
<platform> identifies the platform’s processor:
t186 for NVIDIA® Jetson™ TX2 series
t194 for NVIDIA® Jetson AGX Xavier™ series or Jetson Xavier NX
t210 for NVIDIA® Jetson Nano™ devices or Jetson TX1
For example, if the current release was release 32.4 and your platform was Jetson Xavier NX, the commands would be:
deb https://repo.download.nvidia.com/jetson/common r32.4 main
deb https://repo.download.nvidia.com/jetson/t194 r32.4 main
3. Save and close the source configuration file.
4. Enter the commands:
$ sudo apt update
$ sudo apt dist-upgrade
If apt prompts you to choose a configuration file, reply Y for yes (to use the NVIDIA updated version of the file).
5. Reboot your Jetson device when the upgrade is finished.
Note:
The do-release-upgrade command is disabled because Jetson Linux does not officially support release 20.04 at this time.

Updating a Host

NVIDIA provides a group of Debian packages that add or update Jetson Linux support components on the host computer.
To prepare the host computer to install Jetson Linux support components
1. Enter this command to install the public key of the x86_64 repository of the public APT server:
$ sudo apt-key adv --fetch-key http://repo.download.nvidia.com/jetson/jetson-ota-public.asc
2. Add the following x86_64 repository to the host system’s source list:
For an Ubuntu 16.04 host:
deb http://repo.download.nvidia.com/jetson/x86_64/xenial <relno> main
For an Ubuntu 18.04 host:
deb http://repo.download.nvidia.com/jetson/x86_64/bionic <relno> main
Where <relno> is the current release’s full release number as specified in the Release Notes.
3. Enter the command:
$ sudo apt update
4. Use apt to download and install the required packages.
For an Ubuntu 16.04 host:
$ sudo apt-get install nsight-graphics-for-embeddedlinux-2021.1.1 cuda-toolkit-10-2 cuda-cross-aarch64-10-2 libvisionworks libvisionworks-dev libvisionworks-samples libvisionworks-sfm libvisionworks-sfm-dev libvisionworks-tracking libvisionworks-tracking-dev libnvvpi1 vpi1-dev vpi1-samples vpi1-cross-aarch64-l4t nsight-systems-2021.2.3
For an Ubuntu 18.04 host:
$ sudo apt-get install nsight-graphics-for-embeddedlinux-2021.1.1 nsight-systems-2021.2.3 cuda-toolkit-10-2 cuda-cross-aarch64-10-2 libvisionworks libvisionworks-dev libvisionworks-samples libvisionworks-sfm libvisionworks-sfm-dev libvisionworks-tracking libvisionworks-tracking-dev libnvvpi1 vpi1-dev vpi1-samples vpi1-cross-aarch64-l4t

Debian Packages on the NVIDIA APT Server

This section lists the Debian packages maintained on the NVIDIA APT server for a Jetson device or a host.

Update Packages for Jetson Devices

Following is a list of OTA update packages for BSP on Jetson devices as of Jetson Linux release 32.6.
For a list of other OTA packages and instructions for applying them, see the section “List of JetPack OTA Packages” in JetPack User Guide.
Component Group
Packages
BSP
jetson-gpio-common
nvidia-l4t-3d-core
nvidia-l4t-apt-source
nvidia-l4t-bootloader
nvidia-l4t-camera
nvidia-l4t-configs
nvidia-l4t-core
nvidia-l4t-cuda
nvidia-l4t-firmware
nvidia-l4t-graphics-demos
nvidia-l4t-gstreamer
nvidia-l4t-init
nvidia-l4t-initrd
nvidia-l4t-jetson-io
nvidia-l4t-jetson-multimedia-api
nvidia-l4t-kernel
nvidia-l4t-kernel-dtbs
nvidia-l4t-kernel-headers
nvidia-l4t-multimedia
nvidia-l4t-multimedia-utils
nvidia-l4t-oem-config
nvidia-l4t-tools
nvidia-l4t-wayland
nvidia-l4t-weston
nvidia-l4t-x11
nvidia-l4t-xusb-firmware
python-jetson-gpio
python3-jetson-gpio

Update Packages for Hosts

The following table lists Jetson Linux support components that you can install with apt on a host, and the packages that contain them.
Component Group
Packages
CUDA
cuda
cuda-10-2
cuda-command-line-tools-10-2
cuda-compat-11-0
cuda-compiler-10-2
cuda-cudart-10-2
cuda-cudart-dev-10-2
cuda-cuobjdump-10-2
cuda-cupti-10-2
cuda-cupti-dev-10-2
cuda-demo-suite-10-2
cuda-documentation-10-2
cuda-driver-dev-10-2
cuda-drivers
cuda-drivers-450
cuda-gdb-10-2
cuda-gdb-src-10-2
cuda-libraries-10-2
cuda-libraries-dev-10-2
cuda-memcheck-10-2
cuda-minimal-build-10-2
cuda-nsight-10-2
cuda-nsight-compute-10-2
cuda-nsight-systems-10-2
cuda-nvcc-10-2
cuda-nvdisasm-10-2
cuda-nvgraph-10-2
cuda-nvgraph-dev-10-2
cuda-nvml-dev-10-2
cuda-nvprof-10-2
cuda-nvprune-10-2
cuda-nvrtc-10-2
cuda-nvrtc-dev-10-2
cuda-nvtx-10-2
cuda-nvvp-10-2
cuda-runtime-10-2
cuda-samples-10-2
cuda-sanitizer-10-2
cuda-toolkit-10-2
cuda-tools-10-2
cuda-visual-tools-10-2
libcublas-dev
libcublas10
libcuda1-375
libcuda1-450
libcufft-10-2
libcufft-dev-10-2
libcurand-10-2
libcurand-dev-10-2
libcusolver-10-2
libcusolver-dev-10-2
libcusparse-10-2
libcusparse-dev-10-2
libnpp-10-2
libnpp-dev-10-2
libnvidia-cfg1-450
libnvidia-common-450
libnvidia-compute-450
libnvidia-decode-450
libnvidia-encode-450
libnvidia-extra-450
libnvidia-fbc1-450
libnvidia-gl-450
libnvidia-ifr1-450
libnvjpeg-10-2
libnvjpeg-dev-10-2
libxnvctrl-dev
libxnvctrl0
nsight-compute-2019.5.3
nsight-systems-2021.1.3
nvidia-375
nvidia-375-dev
nvidia-450
nvidia-450-dev
nvidia-compute-utils-450
nvidia-dkms-450
nvidia-driver-450
nvidia-headless-450
nvidia-headless-no-dkms-450
nvidia-kernel-common-450
nvidia-kernel-source-450
nvidia-libopencl1-375
nvidia-libopencl1-450
nvidia-modprobe
nvidia-opencl-icd-375
nvidia-opencl-icd-450
nvidia-settings
nvidia-utils-450
xserver-xorg-video-nvidia-450
CUDA cross-compile package (host)
cuda-cross-aarch64
cuda-cross-aarch64-10-2
cuda-cudart-cross-aarch64-10-2
cuda-cupti-cross-aarch64-10-2
cuda-driver-cross-aarch64-10-2
cuda-nsight-compute-addon-l4t-10-2
cuda-nvcc-cross-aarch64-10-2
cuda-nvgraph-cross-aarch64-10-2
cuda-nvml-cross-aarch64-10-2
cuda-nvprof-cross-aarch64-10-2
cuda-nvrtc-cross-aarch64-10-2
cuda-nvtx-cross-aarch64-10-2
libcublas-cross-aarch64
libcufft-cross-aarch64-10-2
libcurand-cross-aarch64-10-2
libcusolver-cross-aarch64-10-2
libcusparse-cross-aarch64-10-2
libnpp-cross-aarch64-10-2
nsight-compute-addon-l4t-2019.5.3
Computer vision (VisionWorks)
libvisionworks
libvisionworks-dev
libvisionworks-samples
libvisionworks-sfm
libvisionworks-sfm-dev
libvisionworks-tracking
libvisionworks-tracking-dev
Computer vision (VPI)
libnvvpi1
vpi1-cross-aarch64-l4t
vpi1-demos
vpi1-dev
vpi1-samples
 

Customizing Debian Packages

You can customize Debian packages to help you implement your solution, for example by adding support for your carrier board. For more information, see Repackaging Debian Packages and Building the Debian Bootloader Package Yourself in the topic BSP Customization.

Downloading Debian Packages for Later Use

As an alternative to installing Debian packages on a Jetson device or host from the APT server, you can download packages and store them, and later, you can install them manually.
To download packages, open https://repo.download.nvidia.com/jetson/ in a web browser. This URL displays a list of Debian packages for each Jetpack release. Each package name is a hyperlink; to download a package, click its link.

Updating Jetson Linux with Image-Based Over-the-Air Update

Applies to: Jetson Xavier NX, Jetson AGX Xavier series, and Jetson TX2 series only
Image-Based Over-the-Air Update is a failsafe way to update BSP on a Jetson device by writing pre-generated images to the partitions. It can update many old BSP versions to newer ones.
Image-based OTA further supports updates between versions with different partition layouts, which require layout changes in the course of the update. One example of such an update is the update from Jetson Linux release 28.3 to release 32.6.
Image-based OTA currently supports updates to the current release, release 32.6, from the following earlier versions. You can adapt the process to update to other versions.
Updates to Jetson Linux release 32.6
Carrier board
Modules
From release
NVIDIA Jetson TX2
Original Jetson TX2 module only
28.2
28.3
28.4
32.1
32.2
32.3
32.4
32.5
NVIDIA Jetson TX2 NX
Jetson TX2 NX module
32.5
NVIDIA® Jetson AGX Xavier™
All Jetson AGX Xavier series modules
32.1
32.2
32.3
32.4
32.5
NVIDIA Jetson Xavier NX
All Jetson Xavier NX modules
32.4
32.5

Terms and Abbreviations

This section uses the following terms and abbreviations:
BUP: Bootloader update payload, a file that contains firmware binaries of each type needed to update a Jetson device
MSI: Minimal set of images, the minimal set of images needed to boot Jetson Linux
OTA: Over-the-Air Update, the Jetson Linux feature that enables you to update Jetson devices
ToT: Top of tree, the latest revision of a file in a source control system such as Git

Overall High-Level Flow

An image-based OTA update is performed in two steps. The first step is to prepare an OTA payload package on the host machine; the second is to trigger the OTA process on the target device.

Preparing the OTA Payload Package

The current Jetson Linux BSP provides all necessary tools for generating the OTA payload package in the OTA tool package:
ota_tools_<rel>_aarch64.tbz2
Where <rel> is the current point release number, e.g. R32.6.1.
The OTA tool package can be used to create OTA payload package for:
Updating a full system
Updating Bootloader only
Updating the rootfs only
The generated OTA payload package is named ota_payload_package.tar.gz. This package includes images for all partitions that are to be updated.
Note:
NVIDIA recommends applying a security mechanism to this package, such as a signature or encryption.
Upload ota_payload_package.tar.gz and the OTA tools package ota_tools_<rel>_aarch64.tbz2 to your OTA server.

Trigger the OTA Process

You are responsible for writing the OTA client service that triggers the OTA process. It must include the following steps:
1. Download the OTA tool package ota_tools_<rel>_aarch64.tbz2 and the OTA payload package ota_payload_package.tar.gz from your own OTA server.
2. Validate the downloaded OTA payload package and its contents according to your own security requirements.
3. Use the tool in the OTA tool package to trigger the OTA update. The tool decompresses the OTA payload package and prepares it for OTA update. The tool handles cases where a partition layout change is involved, and where rootfs A/B is enabled
For detailed steps, see the following sections.

Preparing for an Image-Based OTA Update

Preparing for an image-based OTA update involves some steps on both the host machine and target device. The steps performed on each are identified in the procedure.
Steps Performed on the Host Machine
1. Set the environment variable BASE_BSP to the full pathname of the base BSP’s Linux_for_Tegra/ directory. (The base BSP is the BSP release to be updated, i.e., a supported version of release 28 or release 32.)
2. Get the package for the current release of Jetson Linux and unpack and apply its sample root filesystem. Go to the directory that contains the current BSP package and enter the following commands:
$ tar xpf Tegra186_Linux_<rel>_aarch64.tbz2
$ cd Linux_for_Tegra/rootfs/
$ sudo tar xpf \
../../Tegra_Linux_Sample-Root-Filesystem_<rel>_aarch64.tbz2
$ cd ..
$ sudo ./apply_binaries.sh
3. Set the environment variable ToT_BSP to the full pathname of the current-release BSP’s Linux_for_Tegra/ directory.
4. Install the OTA tool package ota_tools_<rel>_aarch64.tbz2 to ${ToT_BSP}:
$ cd ${ToT_BSP}/../
$ tar xpf ota_tools_<rel>_aarch64.tbz2
5. If the release you want to update to is ${ToT_BSP}, set the environment variable TARGET_BSP to ${ToT_BSP} and go to step 12. Otherwise, go on to the next step to update the BSP to the desired other release.
6. Get the package for the release of Jetson Linux that you want to update to, such as release 32.4 or 32.5. Unpack and apply its sample root filesystem.
Note:
Updating to r32.5 is not supported on the Jetson Xavier NX P3668-0000.
Go to the directory that contains the BSP package and enter the following commands:
$ tar xpf Tegra186_Linux_<rel>_aarch64.tbz2
$ cd Linux_for_Tegra/rootfs/
$ sudo tar xpf \
../../Tegra_Linux_Sample-Root-Filesystem_<rel>_aarch64.tbz2
$ cd ..
$ sudo ./apply_binaries.sh
7. Set the environment variable TARGET_BSP to the full pathname of the Linux_for_Tegra/ directory in the package you unpacked in step 6.
8. Install the OTA tool package ota_tools_<rel>_aarch64.tbz2 from ${ToT_BSP} to ${TARGET_BSP}:
$ cd ${TARGET_BSP}/../
$ tar xpf ${ToT_BSP}/../ota_tools_<rel>_aarch64.tbz2 -C ./
9. Copy files under ${ToT_BSP}/tools/ota_tools/version_upgrade to ${TARGET_BSP}:
$ cd ${TARGET_BSP}
$ cp ${ToT_BSP}/tools/ota_tools/version_upgrade/* ./tools/ota_tools/version_upgrade
10. Generate slot metadata files for ${TARGET_BSP}:
$ cd ${TARGET_BSP}
$ cp ./bootloader/smd_info.cfg ./tools/ota_tools/version_upgrade/smd_info.boot_slot_A.cfg
$ cp ./bootloader/smd_info.cfg ./tools/ota_tools/version_upgrade/smd_info.boot_slot_B.cfg
$ sed -i -e 's/^15/# 15/' -e 's/^##15/15/' -e 's/^##14/14/' ./tools/ota_tools/version_upgrade/smd_info.boot_slot_A.cfg
$ sed -i -e 's/^15/# 15/' -e 's/^##15/14/' -e 's/^##14/15/' ./tools/ota_tools/version_upgrade/smd_info.boot_slot_B.cfg
$ ./bootloader/nv_smd_generator ./tools/ota_tools/version_upgrade/smd_info.boot_slot_A.cfg ./tools/ota_tools/version_upgrade/slot_metadata.bin.A
$ ./bootloader/nv_smd_generator ./tools/ota_tools/version_upgrade/smd_info.boot_slot_B.cfg ./tools/ota_tools/version_upgrade/slot_metadata.bin.B
11. Copy the files from ${ToT_BSP} and modify p2771-0000.conf.common, p2972-0000.conf.common, and p3668.conf.common:
$ cd ${TARGET_BSP}
$ mv ./flash.sh ./flash.sh.backup
$ cp ${ToT_BSP}/flash.sh ./
$ mv ./l4t_sign_image.sh ./l4t_sign_image.sh.backup
$ cp ${ToT_BSP}/l4t_sign_image.sh ./
$ mv ./l4t_sign_image.sh ./l4t_sign_image.sh.backup
$ cp ${ToT_BSP}/l4t_sign_image.sh ./
$ mv ./l4t_generate_soc_bup.sh ./l4t_generate_soc_bup.sh.backup
$ cp ${ToT_BSP}/l4t_generate_soc_bup.sh ./
$ mv ./bootloader/tegraparser_v2 ./bootloader/tegraparser_v2.backup
$ cp ${ToT_BSP}/bootloader/tegraparser_v2 ./bootloader/
$ mv ./bootloader/tegraflash.py ./bootloader/tegraflash.py.backup
$ cp ${ToT_BSP}/bootloader/tegraflash.py ./bootloader/
$ mv ./bootloader/tegrahost_v2 ./bootloader/tegrahost_v2.backup
$ cp ${ToT_BSP}/bootloader/tegrahost_v2 ./bootloader/
$ mv ./bootloader/tegrabct_v2 ./bootloader/tegrabct_v2.backup
$ cp ${ToT_BSP}/bootloader/tegrabct_v2 ./bootloader/
$ mv ./bootloader/tegraflash_internal.py ./bootloader/tegraflash_internal.py.backup
$ cp ${ToT_BSP}/bootloader/tegraflash_internal.py ./bootloader/
$ cp ${ToT_BSP}/bootloader/tegrasign_v3_util.py ./bootloader/
$ cp ${ToT_BSP}/bootloader/tegrasign_v3_internal.py ./bootloader/
$ cp ${ToT_BSP}/bootloader/tegrasign_v3.py ./bootloader/
$ cp ${ToT_BSP}/bootloader/tegraopenssl ./bootloader/
$ sudo mv ./rootfs/opt/nvidia/l4t-bootloader-config/nv-l4t-bootloader-config.sh ./rootfs/opt/nvidia/l4t-bootloader-config/nv-l4t-bootloader-config.sh.backup
$ sudo cp ${ToT_BSP}/rootfs/opt/nvidia/l4t-bootloader-config/nv-l4t-bootloader-config.sh ./rootfs/opt/nvidia/l4t-bootloader-config/nv-l4t-bootloader-config.sh
$ sudo mv ./rootfs/usr/sbin/nvbootctrl ./rootfs/usr/sbin/nvbootctrl.backup
$ sudo cp ${ToT_BSP}/rootfs/usr/sbin/nvbootctrl ./rootfs/usr/sbin/nvbootctrl
$ sudo mv ./rootfs/usr/sbin/nv_bootloader_payload_updater ./rootfs/usr/sbin/nv_bootloader_payload_updater.backup
$ sudo cp ${ToT_BSP}/rootfs/usr/sbin/nv_bootloader_payload_updater ./rootfs/usr/sbin/nv_bootloader_payload_updater
$ sudo mv ./rootfs/usr/sbin/nv_update_engine ./rootfs/usr/sbin/nv_update_engine.backup
$ sudo cp ${ToT_BSP}/rootfs/usr/sbin/nv_update_engine ./rootfs/usr/sbin/nv_update_engine
$ echo "SMDFILE=\"slot_metadata.bin\";" >>p2771-0000.conf.common
$ echo "SMDFILE=\"slot_metadata.bin\";" >>p2972-0000.conf.common
$ echo "SMDFILE=\"slot_metadata.bin\";" >>p3668.conf.common
12. Generate the base recovery image and recovery DTB. Enter these commands:
$ cd ${TARGET_BSP}/
$ sudo ./tools/ota_tools/version_upgrade/build_base_recovery_image.sh [-u <PKC key file>] [-v <SBK key file>] <target_board> <bsp_version> ${BASE_BSP} ${BASE_BSP}/rootfs ${TARGET_BSP}
Where:
<target_board> is the appropriate configuration name:
For Jetson Xavier NX P3668-0000: jetson-xavier-nx-devkit
For Jetson Xavier NX P3668-0001: jetson-xavier-nx-devkit-emmc
For Jetson TX2 NX: jetson-xavier-nx-devkit-tx2-nx
For Jetson AGX Xavier P2888-0001 (16 GB) or P2888-0004 (32 GB): jetson-agx-xavier-devkit
For Jetson TX2 P3310-1000: jetson-tx2-devkit
<bsp_version> is the base BSP version, in the form Rmm-n, where mm and n are respectively the major and minor version numbers. The base BSP version may be any minor version from release 28.2 forward. For example, R32-3 specifies base BSP release 32.3.
<PKC key file> is an optional PKC key file. It must be the same as the one used in flashing images to the target board.
<SBK key file> is an optional SBK key file. It must be the same as the one used in flashing images to the target board.
After this command is completed successfully, the script generates the recovery image and recovery DTB and stores them under ${TARGET_BSP}/bootloader/. The recovery image and recovery DTB are used to boot the target device into the recovery kernel.
For example, the following command generates a recovery image and recovery DTB for release 32.1 on a Jetson TX2 carrier board without using a PKC key and SBK key. It generates the recovery image recovery.img.R32_1_2 and the recovery DTB recovery.dtb.R32_1_2 under ${TARGET_BSP}/bootloader/.
$ sudo ./tools/ota_tools/version_upgrade/build_base_recovery_image.sh jetson-tx2 R32-1 ${BASE_BSP}/ ${BASE_BSP}/rootfs ${TARGET_BSP}
13. Generate the OTA update payload package. Enter these commands:
$ cd ${TARGET_BSP}
$ sudo ./tools/ota_tools/version_upgrade/l4t_generate_ota_package.sh [-s] [‑b] [‑r] [-u <PKC_key_file>] [-v <SBK_key_file>] [-o <rootfs_updater>] [-f <rootfs_image>] <target_board> <bsp_version>
Where:
‑s, ‑b, and ‑r may be used separately, as shown, or may be combined in a single “word,” e.g. ‑sb or ‑sr.
‑s: Skip generating the rootfs image. Use this option if a rootfs image has been generated or specified with the -f option.
-b: Generate an OTA payload package for updating Bootloader only. This option is meaningful only for an update without layout change.
-r: Generate an OTA payload package for updating rootfs only. This option is valid only for an update without layout change.
<PKC_key_file> is an optional PKC key file. It must be the same as the one used in flashing images to the target board.
<SBK_key_file> is an optional SBK key file. It must be the same as the one used in flashing images to the target board.
<rootfs_updater> specifies the script to be used to update the rootfs partition. (For more information, see Updating the Rootfs Partition with a Customized Updater and Image.
<rootfs_image> is the path of the rootfs image to be written to the rootfs partition.
The default rootfs is built from ${TARGET_BSP)/rootfs. This option lets you overwrite the default rootfs image with a self-generated rootfs image, for example, an image cloned from a Jetson device that has been fully customized with a top-of-tree release of Jetson Linux.
<target_board> is the configuration name specified for build-base-recovery-image.sh in step 12.
<bsp_version> is the base BSP version specified for build-base-recovery-image.sh in step 12.
The script generates the file ota_payload_package.tar.gz under ${TARGET_BSP}/bootloader/<target_board>.
The ota_payload_package.tar.gz archive that the script generates from the default rootfs occupies about 2 GB. A self-generated rootfs may yield a larger or smaller archive Decompressing the archive on the Jetson device to apply the image-based OTA requires at least 6 GB of free space.
Note:
Steps 12 and 13 use the Jetson Linux sample rootfs from Linux_for_Tegra/rootfs/ to build the recovery kernel and recovery DTB and OTA package.
If you have customized the sample rootfs, for example, you must add required libraries and binaries into the rootfs, apply them before running this script.
You must put the OTA tool package and OTA payload package on to your own OTA server to implement a complete OTA solution.
Steps Performed on the Jetson Device
1. Review /boot/extlinux/extlinux.conf.
If the INITRD entry is not set, add the line under the LINUX /boot/Image line:
INITRD /boot/initrd
If the root device is not set, add it into the APPEND line, for example:
root=/dev/mmcblk0p1 rw rootwait rootfstype=ext4.
2. Download the OTA update tool package ota_tools_<rel>_aarch64.tbz2 and the OTA update payload package ota_payload_package.tar.gz to the target board.
3. Create a directory to hold files generated in the OTA update process. Set the environment variable WORKDIR to this directory’s full pathname.
4. Unpack ota_tools_<rel>_aarch64.tbz2 into the ${WORKDIR} directory.
5. Create a directory /ota/ and put the OTA update payload package ota_payload_package.tar.gz in it.
6. Unpack the OTA payload package and prepare to start OTA:
$ cd ${WORKDIR}/Linux_for_Tegra/tools/ota_tools/version_upgrade
$ sudo ./nv_ota_start.sh /dev/mmcblk0 /ota/ota_payload_package.tar.gz
/ota/ota_payload_package.tar.gz is the OTA payload package.
7. If no error occurs in the last step, reboot the target board.
If rootfs A/B is enabled on the target, Bootloader partitions and rootfs partitions on the inactive slot are updated in step 6. The target board then reboots to the slot just updated.
If rootfs A/B is disabled on the target it boots to the recovery kernel, which runs the OTA update process after executing this step. If the update fails due to power loss, the target device can reboot into the recovery kernel and continue the update. The maximum number of times the target device reboots and continues the update is determined by the script variable OTA_MAX_RETRY_COUNT, which defaults to 0 (zero). If the update fails more than that number of times the target device boots to the recovery kernel and enters the bash shell. You can change the value of OTA_MAX_RETRY_COUNT in ${TARGET_BSP}/‌tools/‌ota_tools/‌version_upgrade/‌nv_recovery.sh.
The update process stores logs in /ota_logs/ on the target device if it fails. These logs record the details of the OTA update process. At the end of a successful OTA update, the log files in this directory are deleted.
Note:
To create a complete, secure OTA update solution, you must implement an OTA client that executes this procedure on the target device, and you must apply security mechanisms according to your security policy requirements.

nv_ota_start.sh, a Utility for Triggering OTA

Image-based OTA supports updates between versions, either with or without partition layout changes. It supports updates whether rootfs A/B is enabled or disabled. You do not need to be aware of the difference because the same utility, nv_ota_start.sh, handles both cases.
nv_ota_start.sh is included in ota_tools_<rel>_aarch64.tbz2. It determines whether layout changes are needed, and executes another script to perform the appropriate type of update.
To perform an update without layout changes, the script executes nv_ota_‌update_without_‌layout_change.sh.
To perform an update with layout changes, the script executes nv_ota_‌update_with_‌layout_change.sh. The section Update with Partition Layout Changes, below, describes the process of updating a version with partition layout changes.

Update with Rootfs Redundancy Enabled

You can use image-based OTA on a device with rootfs redundancy enabled. OTA update is triggered after the nv_ota_start.sh utility is run. The whole procedure is executed in a fully booted system and the device is never rebooted to the recovery kernel. The update procedure employs two additional utilities nv_update_engine and nv_bootloader_payload_updater.
The OTA update process is the same whether or not the “Unified bootloader A/B and rootfs A/B” option is enabled:
1. Update the Bootloader partitions on the inactive slot by running nv_update_engine with the pre-generated BUP image bl_only_payload.
2. Update the kernel and kernel-dtb partitions on the inactive slot by running nv_bootloader_payload_updater with the pre-generated BUP image kernel_only_payload.
3. Update the rootfs partition on the inactive slot by running nv_update_engine with the pre-generated rootfs image and corresponding rootfs updater.
Once the OTA update is successfully completed, the device is rebooted to the updated slot. If the device fails to boot to the updated slot after several retries, it switches back to the previous, known good slot. For more information about slots switching with rootfs redundancy enabled, see Root Filesystems Redundancy in the topic Setting Up Your File System.

Update with Partition Layout Changes

An update with partition layout changes is a challenging process for an image-based OTA update. If you perform the partition changes directly, an unexpected reboot during the update may fail and leave the Jetson device in an unbootable state.
BSP supports A/B update, which maintains two sets of partitions for booting and running the operating system, designated “slot A” and “slot B.” It uses only one slot at a time, and applies updates to the partitions on the inactive slot, then swaps the roles of the slots. For example, when slot A is active, BSP boots and runs the operating system from the partitions in slot A, and applies updates to those in slot B. This ensures that an update failure cannot render the device unbootable.
For more information about the A/B update process, see Jetson Xavier NX / AGX Xavier / TX2 Update and Redundancy in the topic Bootloader.
To implement fail-safe update, the image-based OTA update process creates some intermediate partition layouts, which it uses to create alternative bootable paths in case there is an unexpected reboot during update. A bootable path is composed of many partitions located on the free space of the storage device. The images stored in these partitions are called the Minimal Set of Images (MSI).
For example, an OTA update from release 28.3 to release 32.6 on Jetson TX2 uses two intermediate partition layouts:
flash_l4t_t186_R28-3_R32i_emmc.xml is based on the default partition layout in release 28.3. It is used by jetson-tx2-R28_3-R32i-emmc.conf.
flash_l4t_t186_R32A_R32i_emmc.xml is based on the default partition layout in R32.6. It is used by jetson-tx2-R32A-R32i-emmc.conf.
l4t_generate_ota_package.sh uses these intermediate partition layouts and their corresponding .conf files to generate the OTA payload package. By default, these layouts are created based on the default partition layout from the released BSP. If any customization is done on the default partition layout, you must apply the customization to the intermediate partition layouts. During OTA, the update script verifies these layouts with layouts on the actual board. If the layouts do not match, OTA update does not proceed.

Back Up and Restore Files on the APP Partition

The script nv_ota_preserve_data.sh in ota_tools_<rel>_aarch64.tbz2 backs up and restores files on the APP partition during OTA update. It is located at Linux_for_Tegra/tools/ota_tools/version_upgrade/.
Edit the configuration file ota_backup_files_list.txt to add the pathnames of files that are to be preserved after OTA update. The distributed version of ota_backup_files_list.txt contains this:
# All the files or directories should be listed with absolute path
# Example:
# etc/passwd
# opt/nvidia
opt/nvidia
Pathnames are written in relative form, but are always interpreted relative to the filesystem root; you may think of them as absolute pathnames from which the leading slash is omitted.
You may add comment lines starting with a pound sign (‘#’) in column 1.
Note:
The script nv_ota_preserve_data.sh packs the listed files into a .tar.gz archive. You can choose other ways of backing up and restoring these files according to your own requirements.

Complete and Secure OTA

NVIDIA provides the basic functionality of updating the system through the OTA update process. You must modify the process and create a complete and secure OTA solution. According to your needs, your modified process may have to meet one or more of these requirements:
Encrypting OTA update payloads
Hosting OTA update payloads on an OTA update server
Triggering an OTA update when an update is found on the OTA server (a function of the OTA update client on the target device)
Authenticating the OTA update server
Decrypting OTA update payloads
Determining when to apply OTA update payloads

Customization

If you have customized the released BSP, for example by customizing the rootfs or changing the partition layout, you must modify some files in the distributed image-based OTA update process to apply the image-based OTA update solution. The following subsections discuss possible types of customization and the OTA update changes they require.

Rootfs Customization

Rootfs customization comprises:
Adding or removing files in the rootfs
Modifying the files in rootfs
Such changes require:
Applying changes to the rootfs

Partition Layout Customization

Partition layout customization comprises:
Adding or removing partitions
Changing size of partitions
Changing location of partitions
Such changes require:
Modifying the provided intermediate partition layout to accommodate the base system. For example, for a Jetson TX2 board flashed with release 28.3, the partition layout file is flash_l4t_t186_R28-3_R32i_emmc.xml.
Modifying the provided intermediate partition layout based on ${TARGET_BSP} the current release system. For the board above, the partition layout file is flash_l4t_t186_R32A_R32i_emmc.xml.
Modifying the current release partition layout for ${TARGET_BSP}. For Jetson TX2 it is flash_l4t_t186.xml.
Modifying MSI_EMMC_OFFSET in the *.conf file if required. Make sure that the free space starting at MSI_EMMC_OFFSET is large enough to store the MSI. For the example above, the corresponding configuration files are jetson-tx2-R28_3-R32i-emmc.conf and jetson-tx2-R32A-R32i-emmc.conf.
Note:
If you are updating release 32.3, 32.4, or 32.5 with partition layout customization to the current release, refer tothe section Examples below.

Update Process Customization

Update process customization comprises:
Changing the process of updating partitions
Updating a newly created partition in addition to default partitions
Updating only some of the default partitions
Such changes require:
Modifying the provided file upgradetasklist.txt.XXX. For example, to update release 28.2, 28.3, or 28.4 to release 32.6, you must modify upgradetasklist.txt.‌jetson-tx2.‌R28_to_R32-ToT_emmc to specify the partitions to be updated.

Recovery Image Customization

Recovery image customization comprises:
Adding some files to the recovery initrd
Such changes require:
Editing the provided file recovery_copy_binlist.txt to specify the filesystems and pathnames of any files you want to add to the recovery image. See that file for an explanation and examples of how to make the changes.

Recovery Task Customization

Recovery task customization comprises:
Adding some other tasks when the recovery kernel is running
Such changes require:
Modifying the provided script nv_recovery.sh, for example, by adding code to decrypt the payload in nv_recovery.sh if it is encrypted

Updating the Rootfs Partition with a Customized Updater and Image

When you generate an OTA payload package (step 13 in Steps Performed on the Host Machine), you can specify the rootfs updater with the -o option and specify the rootfs image with the -f option.
The rootfs updater is a script that writes the rootfs image to the rootfs partition. It is called with appropriate command line parameters and options by several Jetson Linux utilities and services, OTA update among them. NVIDIA provides a default rootfs updater named nv_ota_rootfs_updater.sh; it is in the distribution archive ota_tools_<rel>_aarch64.tbz2.
The default rootfs updater’s usage is:
nv_ota_rootfs_updater.sh [-p <devnode>] [-d <workdir>] <image>
Where:
<devnode> is the device node path of the rootfs partition, for example, /dev/mmcblk0p1.
<workdir> is the path of the OTA work directory, for example, /ota_work.
<image> is the path of the rootfs image, for example, /ota_work/system.img.
If you create a customized rootfs image, you must specify a rootfs updater that can process that image. The rootfs updater you specify must expect the same arguments and options as nv_ota_rootfs_updater.sh. Your update may use these arguments and options or not, depending on your specific needs.

Updating an Individual Partition

The current-release of BSP supports updating individual partitions (excluding the partitions BCT, mb1, and APP).
You perform an individual partition update in two steps:
1. Prepare a Bootloader update payload (BUP) on the host system.
2. Trigger an update on the target device.
To prepare the Bootloader update payload
1. Enter these commands on the host system:
$ cd ${Tot_BSP}/Linux_for_Tegra
$ sudo ./l4t_generate_soc_bup.sh <processor>
Where <processor> is:
For Jetson TX2, t18x
For Jetson AGX Xavier , t19x
The script generates a BUP named bl_update_payload in the directory at Linux_for_Tegra/payloads_<processor>/bl_update_payload/.
2. Copy the BUP to any convenient location on the target device whose partitions are to be updated.
To trigger the update process
1. Move the BUP bl_update_payload to the directory /opt/ota_package/.
2. Create a file named update_list.conf and edit it to add the names and slots of the partition(s) to be updated.
For example, you could update the partitions cpu-bootloader and bootloader-dtb in their non-current slots by adding these lines:
cpu-bootloader non-current
bootloader-dtb non-current
3. To trigger the update, run the script nv_part_update with the name of the file update_list.conf as an input parameter:
$ sudo nv_part_update update_list.conf

Examples

NVIDIA provides several examples of how to apply image-based OTA update for some specific use cases:
Modifying the intermediate partition layout
Upgrading release 32.3, 32.4, or 32.5 to the current release with partition layout customization
ota-demo-host.sh and ota-demo-target.sh sample scripts
Update on customized devices
For more details about these examples, see the file:
Linux_for_Tegra/‌tools/‌ota_tools/‌version_upgrade/‌Image_based_OTA_Examples.txt
This file is included in the OTA tool package ota_tools_<rel>_aarch64.tbz2.