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
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 series
• 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 series, 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 https://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.2.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
• For an Ubuntu 18.04 host:
$ sudo apt-get install nsight-graphics-for-embeddedlinux-2021.2.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.7.
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 |
Note: | Jetson AGX Xavier Industrial does not support these update packages because its partition layout is changed. |
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 series, 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.7.
Image-based OTA currently supports updates to the current release, release 32.7, from the following earlier versions. You can adapt the process to update to other versions.
Updates to Jetson Linux release 32.7 |
---|
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 32.6 |
NVIDIA Jetson TX2 NX | Jetson TX2 NX module | 32.5 32.6 |
NVIDIA® Jetson AGX Xavier™ | All Jetson AGX Xavier series modules | 32.1 32.2 32.3 32.4 32.5 32.6 |
NVIDIA Jetson Xavier NX | All Jetson Xavier NX series modules | 32.4 32.5 32.6 |
Note: | Image-based OTA is designed to update multiple Jetson devices, which is possible only if the devices are connected through an Ethernet network. If image-based OTA finds no connection, it attempts to establish one by rebooting. If your device is not connected to an Ethernet network, you must disable this reboot: 1. Go to the directory ${TARGET_BSP}/tools/ota_tools/version_upgrade/. 2. Open the file nv_recovery.sh in a text editor. 3. Comment out the first reboot_system line in the file; save and exit. |
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, which can be downloaded from the NVIDIA developer web site’s
L4T page.
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. If you are updating to release 32.6, go to step
6. Otherwise, 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.5 or 32.6. Unpack and apply its sample root filesystem.
Note: | Updating to r32.5 is not supported on the Jetson Xavier NX development module, 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. If this BSP package is release 32.6, set the environment variable
ToT_BSP to
${TARGET_BSP}.
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 ./
If this BSP package is release 32.6, go to step
12. Otherwise, go on the next step.
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 "DRAMECCFILE=\"bootloader/dram-ecc.bin\";" >>p2771-0000.conf.common
$ echo "BADPAGEFILE=\"bootloader/badpage.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 (8 GB) or P3668-0003 (16 GB): jetson-xavier-nx-devkit-emmc
• For Jetson TX2 NX: jetson-xavier-nx-devkit-tx2-nx
• For Jetson AGX Xavier P2888-0001 (16 GB), P2888-0004 (32 GB), or P2888-0005 (64 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_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.7 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.7. 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 to the 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.7, 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
The recovery kernel executes nv_ota_run_tasks.sh as a task runner. It executes OTA tasks in a sequential order. To add a task to be run when the recovery kernel is selected, you must:
• Add the script files into Linux_for_Tegra/tools/ota_tools/version_upgrade/. Ensure that the script files have execution permission.
• Modify OTA_TASKS and OTA_TASK_NEEDED_FILES in nv_ota_customer.conf to include the newly added script files.
• The script files listed in OTA_TASKS are OTA tasks, and are executed in order by the task runner. Insert each script file name at a proper position.
• The script files listed in OTA_TASK_NEEDED_FILES are the files needed by OTA tasks. Add the file names, if any, to the list.
• Re-generate the OTA update payload package.
Miscellaneous Customization: Ethernet Connectivity Requirement
If you want to ensure that no update is performed unless a stable Ethernet connection is available, enable OTA update's Ethernet connectivity requirement by setting the property REQUIRE_ETHERNET in nv_ota_customer.conf. This setting makes Jetson Linux check Ethernet connectivity before starting OTA. If no connection is found, it attempts to establish one by rebooting.
This requirement is disabled by default because a Jetson device need not use Ethernet as its primary means of connectivity.
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 updater 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.