Flash your ZED Box Orin

Should I flash my ZED Box?

The ZED Box Orin is shipped with a pre-configured operating system and drivers optimized for its hardware.

Flashing (resetting or upgrading the device firmware) is only recommended if you need to:

• Install a different OS or JetPack version,
• Recover from a corrupted system,
• Resolve issues preventing the device from booting or functioning properly.

Flashing Procedure

Force the ZED Box in Recovery mode

• First method:

  To automatically start the ZED Box Orin in Force Recovery mode:

  1. Power off the device by removing both the barrel jack and any connected PoE+ Ethernet cable.
  2. Connect a Type-A to micro USB cable from the Ubuntu host PC to the micro USB port labeled OTG on the device.
  3. Power on the device by plugging in the barrel jack.

  If the above procedure does not work and your ZED Box is in working status, you can force the “Recovery Mode” with the command line below.

• Second method:

  This is applicable only if your device can normally boot.

  Open a terminal console (Ctrl+Alt+t) and enter the command

  sudo reboot --force forced-recovery

  This command will reboot the ZED Box Orin in Recovery Mode.

You can verify that the ZED Box correctly started in “Recovery Mode” by entering this command in a command line console of the host PC:

lsusb -d '0955:'

• ZED Box Orin Nano 8 GB: an NVIDIA® device with VID:PID 0955:7523 should be listed. e.g. Bus xxx Device yyy: ID 0955:7523 NVIDIA Corp. APX
• ZED Box Orin NX 16 GB: an NVIDIA® device with VID:PID 0955:7323 should be listed. e.g. Bus xxx Device yyy: ID 0955:7323 NVIDIA Corp. APX
• ZED Box Orin NX 8 GB: an NVIDIA® device with VID:PID 0955:7423 should be listed. e.g. Bus xxx Device yyy: ID 0955:7423 NVIDIA Corp. APX

Flashing the ZED Box Orin model

Requirements:

• JetPack version <= 5.1.2, use a host PC running Ubuntu 18.04 or Ubuntu 20.04.
• JetPack version >= 6.0, use a host PC running Ubuntu 20.04 or Ubuntu 22.04.

On the host PC:

1. Open a terminal console from an empty folder of your choice.

   • For example:

     mkdir -p ~/zedbox_flash
     cd ~/zedbox_flash

2. Install QEMU to build the image:

   sudo apt install qemu-user-static

3. Ensure that you previously forced the ZED Box Orin in “Recovery mode”.

4. Download the Flash Script:

   • Download the flash script for the NVIDIA® JetPack version you want to install:
     • NVIDIA® JetPack 5.1.1 / L4T 35.3.1 - JetPack details
     • NVIDIA® JetPack 5.1.2 / L4T 35.4.1 - JetPack details
     • NVIDIA® JetPack 6.0 / L4T 36.3 - JetPack details
     • NVIDIA® JetPack 6.2 / L4T 36.4.3 - JetPack details
     • NVIDIA® JetPack 7.2 / L4T 39.2 - JetPack details

5. Flash the ZED Box:

   • Ensure you have at least 80GB of free space on your working hard drive.

   • Use the following commands to flash the ZED Box:

     chmod +x <script_name>.sh
     BSP_ROOT=./stereolabs_bsp/ ./<script_name>.sh
     • Replace <script_name> with the name of the downloaded script, e.g., zedbox_all_usb_flash_6.2.
     • All necessary files will be downloaded in the folder $BSP_ROOT. The script will create this folder if it does not exist and will ask you to log in as root.

6. Wait for the operation to complete. You will see the following output if the flash is successful:

If you encounter any problems during this procedure, please consult the troubleshooting guide.

Post-Flash operations

After flashing your device, follow these steps to install the necessary NVIDIA® and StereoLabs packages to ensure your ZED camera works correctly.

1. Boot and Login:

   Power on the device and log in with your credentials.

   The new default credentials of your ZED Box are:

   • username: user
   • password: admin

2. Check the OS Version:

   Follow this support guide to determine the version of the operating system installed on your device.

3. Connect to the Internet:

   Connect your device to the internet using an Ethernet cable (WiFi may not yet be available, depending on the script you used to flash the device).

   If WiFi is not detected or not connecting, please follow this troubleshooting guide.

4. Open a Terminal:

   Press Ctrl+Alt+T to open a terminal window.

5. Update the APT cache:

   Run the following commands to update the APT cache:

   sudo apt update
   Do not run the command sudo apt upgrade before performing the next steps!

6. Install NVIDIA® JetPack Packages:

   Run the following command to install the NVIDIA® JetPack packages, which include the required Jetson™ drivers, CUDA, and all necessary NVIDIA® libraries:

   sudo apt install nvidia-jetpack

7. Install the ZED Box Orin GMSL2 driver (for ZED X and ZED X One cameras):

   Download and install the appropriate drivers from the driver web page:

   cd ~/Downloads
   sudo dpkg -i stereolabs-zedbox-<ver_info>_arm64.deb

8. Hold the kernel packages to not upgrade them and invalidate the setup:

   • Create a hold-zedbox-kernel.sh script file with the following content:

     • nano hold-zedbox-kernel.sh

       'hold-zedbox-kernel.sh'

       Fill the file with this script:

       #!/bin/bash
       #
       # hold-zedbox-kernel.sh
       #
       # Prevents `apt upgrade` from installing nvidia-l4t-kernel versions
       # that are incompatible with the stereolabs-zedbox-* driver package.
       #
       # The stereolabs-zedbox-* driver package requires an nvidia-l4t-kernel version within the
       # range supported by the L4T release it was built for. For example, the
       # L4T 36.4 (JetPack 6.2) driver requires:
       #   >= 5.15.148-tegra-36.4.0-20240912212859
       #   <= 5.15.148-tegra-36.4.4-20250616085344
       # The range differs for other JetPack versions. Check your driver with:
       #   dpkg-query -W -f='${Package}: ${Depends}\n' 'stereolabs-zedbox*'
       #
       # This script holds all NVIDIA L4T kernel-related packages at their
       # currently installed versions so they won't be upgraded past the
       # compatible range.
       #
       # The package list is discovered dynamically from dpkg rather than
       # hardcoded. L4T/JetPack images ship these packages
       # under names that vary between releases (sometimes version-suffixed, e.g.
       # nvidia-l4t-kernel-5.15.148, sometimes via a different meta-package), so a
       # fixed list often matches nothing and every entry is skipped.
       #
       # Usage:
       #   sudo ./hold-zedbox-kernel.sh hold     # Hold the packages (default)
       #   sudo ./hold-zedbox-kernel.sh unhold   # Release the hold
       #   sudo ./hold-zedbox-kernel.sh status   # Show current hold status
       set -euo pipefail
       # Regex matching the L4T kernel package family we want to hold. This is
       # anchored at the start and allows arbitrary suffixes (e.g. -headers,
       # version suffixes) so it catches naming variants across L4T releases.
       PKG_REGEX='^nvidia-l4t-(kernel|rt-kernel|display-kernel|bootloader|xusb-firmware|init)'
       # --- helpers ---------------------------------------------------------------
       require_root() {
          if [[ $EUID -ne 0 ]]; then
             echo "Error: this script must be run with sudo or as root." >&2
             exit 1
          fi
       }
       # Discover installed L4T kernel-related packages by pattern. Populates the
       # global PACKAGES array. Exits with an error if nothing matches, since that
       # means the regex (or the image) needs to be inspected manually.
       discover_packages() {
          mapfile -t PACKAGES < <(
             dpkg-query -W -f='${Package} ${db:Status-Abbrev}\n' 2>/dev/null \
             | awk '$2 ~ /^.i/ {print $1}' \
             | grep -E "$PKG_REGEX" \
             | sort -u
          )
          if [[ ${#PACKAGES[@]} -eq 0 ]]; then
             echo "Error: no installed nvidia-l4t kernel packages matched." >&2
             echo "Inspect manually with:" >&2
             echo "  dpkg -l | grep -i nvidia-l4t-kernel" >&2
             echo "  dpkg -l | grep -i nvidia-l4t | grep -iE 'kernel|boot|init|firmware'" >&2
             echo "Then adjust PKG_REGEX in this script if the names differ." >&2
             exit 1
          fi
       }
       hold_packages() {
          require_root
          discover_packages
          echo "Holding NVIDIA L4T kernel packages at their current versions..."
          echo
          local held=0
          for pkg in "${PACKAGES[@]}"; do
             local ver
             ver=$(dpkg-query -W -f='${Version}' "$pkg" 2>/dev/null || echo "unknown")
             apt-mark hold "$pkg" >/dev/null
             printf "  [HELD]    %-45s (version: %s)\n" "$pkg" "$ver"
             held=$((held + 1))
          done
          echo
          echo "Done. Held: $held"
          echo
          echo "These packages will now be ignored by 'apt upgrade'."
          echo "Use 'apt-mark showhold' to verify, or run this script with 'status'."
       }
       unhold_packages() {
          require_root
          discover_packages
          echo "Releasing hold on NVIDIA L4T kernel packages..."
          echo
          local released=0
          local all_holds
          all_holds=$(apt-mark showhold)
          for pkg in "${PACKAGES[@]}"; do
             if echo "$all_holds" | grep -qxF "$pkg"; then
                   apt-mark unhold "$pkg" >/dev/null
                   printf "  [UNHELD]  %s\n" "$pkg"
                   released=$((released + 1))
             else
                   printf "  [SKIPPED] %s (was not held)\n" "$pkg"
             fi
          done
          echo
          echo "Done. Released: $released"
          echo
          echo "WARNING: these packages may now be upgraded by 'apt upgrade',"
          echo "which can break the stereolabs-zedbox-* driver if an incompatible kernel"
          echo "version is installed."
       }
       show_status() {
          discover_packages
          echo "Current hold status for NVIDIA L4T kernel packages:"
          echo
          local all_holds
          all_holds=$(apt-mark showhold)
          for pkg in "${PACKAGES[@]}"; do
             local ver
             ver=$(dpkg-query -W -f='${Version}' "$pkg" 2>/dev/null)
             if echo "$all_holds" | grep -qxF "$pkg"; then
                   printf "  [HELD]      %-45s (version: %s)\n" "$pkg" "$ver"
             else
                   printf "  [NOT HELD]  %-45s (version: %s)\n" "$pkg" "$ver"
             fi
          done
          echo
          echo "stereolabs-zedbox-* driver status:"
          local zedpkgs
          zedpkgs=$(dpkg-query -W -f='${Package} ${db:Status-Abbrev} ${Version}\n' 'stereolabs-zedbox*' 2>/dev/null \
             | awk '$2 ~ /^.i/ {print $1 " (version: " $3 ")"}' || true)
          if [[ -n "$zedpkgs" ]]; then
             echo "$zedpkgs" | sed 's/^/  Installed: /'
          else
             echo "  Not installed"
          fi
       }
       usage() {
          cat <<EOF
       Usage: sudo $0 [hold|unhold|status]
       hold     Hold NVIDIA L4T kernel packages at their current versions (default)
       unhold   Release the hold so packages can be upgraded again
       status   Show whether each package is currently held
       Why this is needed:
       the stereolabs-zedbox-* driver depends on nvidia-l4t-kernel within a specific
       version range. Newer kernels from NVIDIA's apt repo fall outside this
       range and break the package. Holding the kernel keeps 'apt upgrade'
       from touching it.
       Note:
       The package list is discovered dynamically from dpkg using PKG_REGEX,
       so version-suffixed or renamed kernel packages are matched automatically.
       Holding only prevents FUTURE upgrades; it cannot roll back a kernel that
       has already been installed outside the compatible range.
       EOF
       }
       # --- main ------------------------------------------------------------------
       cmd="${1:-hold}"
       case "$cmd" in
          hold)    hold_packages ;;
          unhold)  unhold_packages ;;
          status)  show_status ;;
          -h|--help|help) usage ;;
          *)
             echo "Error: unknown command '$cmd'" >&2
             echo
             usage
             exit 1
             ;;
       esac

   • Make the script executable:

     chmod +x hold-zedbox-kernel.sh

   • Run the script:

     sudo ./hold-zedbox-kernel.sh

   • Verify the result:

     sudo ./hold-zedbox-kernel.sh status

     All the listed nvidia-l4t-* kernel packages should be reported as [HELD] nvidia-l4t-* (version: xx.y.z-dddddddddddddd).

9. Download and install the ZED SDK:

   • Visit the StereoLabs website and download the ZED SDK for Jetson that matches your installed JetPack/L4T version.

   • Navigate to your Downloads directory and run the installer:

     cd ~/Downloads
     chmod +x ZED_SDK_Tegra_L4T<l4t_version>_v<x.y.z>.zstd.run
     ./ZED_SDK_Tegra_L4T<l4t_version>_v<x.y.z>.zstd.run

10. Reboot:

    Restart your device to apply all changes:

    sudo reboot

11. Enjoy Your Device:

    Your device is now ready for use with the ZED cameras.

Entering recovery mode with a live USB flashdrive

If the bootloader of the ZED Box Orin is “broken”, or you own a first-gen ZED Box Orin (serial number not beginning with GTW-ONX1- or GTW-ONX2-), you will not be able to enter recovery mode automatically by using the standard methods described above.

This tutorial will help you recover from such a situation.

Requirements:

• for JetPack version <= 5.1.2, use a host PC running Ubuntu 18.04 or Ubuntu 20.04.
• for JetPack version >= 6.0, use a host PC running Ubuntu 20.04 or Ubuntu 22.04.
• a 32 GB or larger USB 3.0 key.

Setting up the USB Key

• Plug the USB Key to the Ubuntu host machine

• Download the flash script for the NVIDIA® JetPack version you want to install:

  • NVIDIA® JetPack 5.1.1 / L4T 35.3.1 - JetPack details
  • NVIDIA® JetPack 5.1.2 / L4T 35.4.1 - JetPack details
  • NVIDIA® JetPack 6.0 / L4T 36.3 - JetPack details
  • NVIDIA® JetPack 6.2 / L4T 36.4.3 - JetPack details
  • NVIDIA® JetPack 7.2 / L4T 39.2 - JetPack details

• Install the necessary dependencies:

  sudo apt install qemu-user-static abootimg libxml2-utils sshpass nfs-kernel-server

• Use lsblk to identify the USB disk you want to flash. In the caption below, we can identify that the USB disk ID is sda:

  Please be careful and use the name of the drive and not the name of a partition. For instance, use sda instead of sda1.

• Make the script executable:

  chmod +x <script_name>.sh

  Replace <script_name> with the name of the downloaded script, e.g. zedbox_onx_usb_flash_5.1.2 or zedbox_all_usb_flash_6.2.

• Launch the script to flash your disk. The operation requires 80GB of free space. You need to specify the USB disk you want to install it on (e.g. sda) and the working directory you want to create (e.g. ./stereolabs_bsp). It will ask you to log in as root several times. Replace the BSP_ROOT and SDX variables with yours in this command:

  BSP_ROOT=./stereolabs_bsp SDX=<sdX> ./<script_name>.sh

  Replace <script_name> with the name of the downloaded script, as in the previous step.

• Upon success, you will read the following message:

• The USB drive is now flashed. You will have to run almost the same command to flash the ZED Box later.

Booting from the USB disk

• Shut down your ZED Box.

• Plug your USB disk into the single vertical USB type A port of the ZED Box Orin.

• Power the ZED Box and wait for it to boot from USB, it will take some time.

• You can now open a terminal console (Ctrl+Alt+t) and enter the following command to reboot into force recovery mode:

  sudo reboot --force forced-recovery

  If you do not have a connected display, you can use a Serial Console. Read the guide on Remote access via Serial Console.

You can verify that the ZED Box correctly started in “Recovery Mode” by entering this command in a command line console of the host PC:

lsusb -d '0955:'

• ZED Box Orin Nano 8 GB: an NVIDIA® device with VID:PID 0955:7523 should be listed. e.g. Bus xxx Device yyy: ID 0955:7523 NVIDIA Corp. APX

• ZED Box Orin NX 16 GB: an NVIDIA® device with VID:PID 0955:7323 should be listed. e.g. Bus xxx Device yyy: ID 0955:7323 NVIDIA Corp. APX

• ZED Box Orin NX 8 GB: an NVIDIA® device with VID:PID 0955:7423 should be listed. e.g. Bus xxx Device yyy: ID 0955:7423 NVIDIA Corp. APX

• Remove the USB drive from the ZED Box.

• You can now follow the instructions in Flashing the ZED Box Orin model.

If you encounter any problems during this procedure, you can contact the support team by sending an email to support@stereolabs.com.