search

balena-os / jetson-flash

This tool allows users to flash BalenaOS on Jetson supported devices
Apache License 2.0
64 stars 16 forks source link

readme

jetson-flash

This tool allows users to flash balenaOS on supported Jetson devices:

Device balena machine name L4T version Provisioning method
Jetson Nano eMMC jetson-nano-emmc L4T 32.7.3 jetson-flash
Jetson Nano SD-CARD Devkit jetson-nano L4T 32.7.3 jetson-flash
Jetson Nano 2GB Devkit jetson-nano-2gb-devkit L4T 32.7.1 jetson-flash
Jetson TX2 jetson-tx2 L4T 32.7.3 jetson-flash
Jetson TX2 NX (in Jetson Xavier NX Devkit) jetson-tx2-nx-devkit L4T 32.7.3 jetson-flash
Jetson AGX Xavier jetson-xavier L4T 32.7.3 jetson-flash
Jetson Xavier NX Devkit eMMC jetson-xavier-nx-devkit-emmc L4T 32.7.3 jetson-flash
Jetson Xavier NX Devkit SD-CARD jetson-xavier-nx-devkit L4T 32.7.3 jetson-flash
Jetson AGX Orin Devkit 32GB jetson-agx-orin-devkit L4T 36.3 jetson-flash
Jetson AGX Orin Devkit 64GB jetson-agx-orin-devkit-64gb L4T 36.3 RCM-Boot script + USB Key
Jetson Orin Nano 8GB (SD) Devkit NVME jetson-orin-nano-devkit-nvme L4T 36.3 RCM-Boot script + USB Key
Jetson Orin NX in Xavier NX Devkit NVME jetson-orin-nx-xavier-nx-devkit L4T 36.3 RCM-Boot script + USB Key
Seeed reComputer J3010 jetson-orin-nano-seeed-j3010 L4T 36.3 RCM-Boot script + USB Key
Seeed reComputer J4012 16GB jetson-orin-nx-seeed-j4012 L4T 36.3 RCM-Boot script + USB Key

IMPORTANT

About

Jetson Flash will extract the balenaOS image from a downloaded provisioned image (such as from balenaCloud) and then flashes that image to a Jetson board connected to a host PC via USB.

This tool invokes NVIDIA’s proprietary software to properly partition the eMMC and place the required balenaOS software in the necessary location to make it bootable. Even on Jetson boards without eMMC, this tool may be necessary to initially flash balenaOS because of the way JetPack uses onboard QSPI flash memory for the bootloader. (In those cases, this tool can write to the QSPI so the device will be able to boot balenaOS from the SD card.)

NOTES:

Software required

Jetson Flash requires a Linux-based host (or virtual machine) and has been tested on Ubuntu 22.04 (Focal).

You can either install all the prerequisites listed below or run the provided Docker image (using Docker, not balenaOS) on the host.

non-Docker

Prerequisites:

Installation:

Make sure the prerequesites listed above are installed.

Clone this repository:

$ git clone https://github.com/balena-os/jetson-flash.git

Install Node.js dependencies by issuing the following command in the jetson-flash directory:

$ npm install

Docker

Prerequisites:

How to use

Follow the steps below to flash your Jetson board

Recovery mode

Make sure that the Jetson board is plugged into your host via USB and is in recovery mode before issuing the flashing command.

Jetson Nano:

With power off, enable Force Recovery mode by placing a jumper across the "FRC" pins of the Button Header on the carrier board.

Then power on the device.

Jetson Orin Nano Devkit NVME :

  1. Ensure the device is powered off and the power adapter disconnected. Enable Force Recovery mode by placing a jumper across the "FC REC" and "GND" pins located on the edge of the carrier board, under the Jetson Orin Nano module.
  2. Connect your host computer to the device's USB-C connector.
  3. Connect the power adapter to the Power Jack.
  4. The device will automatically power on in Force Recovery Mode.

Jetson TX2:

  1. Power down the device, removing the AC adapter.
  2. Connect the Micro-B plug on the USB cable to the Recovery (USB Micro-B) Port on the device and the other end to an available USB port on the host PC.
  3. Connect the power adapter to the device.
  4. With the system powered on:
    • Press and hold the RECOVERY FORCE button.
    • While depressing the RECOVERY FORCE button, press and release the RESET button.
    • Wait 2 seconds and release the RECOVERY FORCE button.

Jetson AGX Xavier:

  1. Connect the developer kit as described above. It should be powered off.
  2. Press and hold down the Force Recovery button.
  3. Press and hold down the Power button.Signed-off-by: Alexandru Costache <alexandru@balena.io
  4. Release both buttons.

Jetson Xavier NX:

  1. Ensure the device is powered off and the power adapter disconnected.
  2. Place a jumper across the Force Recovery Mode pins. These are pins 9 ("GND") and 10 ("FC REC") of the Button Header (J14).
  3. Connect your host computer to the device's USB Micro-B connector.
  4. Connect the power adapter to the Power Jack [J16].
  5. The device will automatically power on in Force Recovery Mode.

Jetson AGX Orin 32GB Devkit:

Jetson AGX Orin 64GB Devkit:

Jetson Orin NX in Xavier NX Devkit:

  1. Ensure the device is powered off and the power adapter disconnected.
  2. Place a jumper across the Force Recovery Mode pins. These are pins 9 ("GND") and 10 ("FC REC") of the Button Header (J14).
  3. Connect your host computer to the device's USB Micro-B connector.
  4. Connect the power adapter to the Power Jack [J16].
  5. The device will automatically power on in Force Recovery Mode.

Jetson Orin Nano 8GB (SD) Devkit NVME:

  1. Ensure the device is powered off and the power adapter disconnected.
  2. Place a jumper across the Force Recovery Mode pins. These are pins ("GND") and ("FC REC") and are located on the carrier board, under the Orin Nano module.
  3. Connect your host computer to the device's USB-C connector.
  4. Connect the power adapter to the Power Jack.
  5. The device will automatically power on in Force Recovery Mode.

Seeed reComputer J3010:

  1. Ensure the device is powered off and the power adapter disconnected.
  2. Open the top lid of the reComputer and place a jumper across the Force Recovery Mode pins. These are pins ("GND") and ("FC REC") and are located on the carrier board, under the Orin Nano module.
  3. Connect your host computer to the device's USB-C connector.
  4. Connect the power adapter to the Power Jack [J2].
  5. The device will automatically power on in Force Recovery Mode.

Seeed reComputer J4012 16GB:

  1. Ensure the device is powered off and the power adapter disconnected.
  2. Open the top lid of the reComputer and place a jumper across the Force Recovery Mode pins. These are pins ("GND") and ("FC REC") and are located on the carrier board, under the Orin NX module.
  3. Connect your host computer to the device's USB-C connector.
  4. Connect the power adapter to the Power Jack [J2].
  5. The device will automatically power on in Force Recovery Mode.

Confirmation

You can confirm your device is running in recovery mode by issuing the command lsusb | grep NVIDIA and examining the output.

You should see something similar to the below, depending on your board:

Bus 003 Device 005: ID 0955:7023 NVIDIA Corp. APX

(The APX is crucial to confirming recovery mode.)

Or

Bus 001 Device 019: ID 0955:7c18 NVIDIA Corp. T186 [TX2 Tegra Parker] recovery mode

Run the tool

For non - Docker, run the tool by specifying the path to the unzipped image (in place of "") and the desired device type (from the "balena machine name" in the table above, in place of ""):

$ ./bin/cmd.js -f <balena.img> -m <device_type>

For Docker, issue the following commands in the folder that has the Dockerfile to build the container(building may take a while and appear to hang, so be patient.) Create a folder named images in your home directory and place your balena image file there so it's available inside the container.

./build.sh [-m <device_type]

You can then enter the container using:

docker container run --rm -it --privileged -v /dev/bus/usb:/dev/bus/usb -v ~/images:/data/images jetson-flash-image /bin/bash

Alternatively, run the provided docker-compose file with docker-compose up and ssh into the container with docker exec -it <container name> /bin/bash

Once in the container, you can run jetson-flash by specifying the balena image in your host's ~/images/ folder (in place of "") and the desired device type (from the "balena machine name" in the table above, in place of "")::

./bin/cmd.js -f /data/images/<balena.img> -m <device_type> --accept-license=yes -c /tmp/Linux_for_Tegra

You can alternatively just run the jetson-flash tool in a single command by running the container with this command:

docker container run --rm -it --privileged -v /dev/bus/usb:/dev/bus/usb -v ~/images:/data/images jetson-flash-image ./bin/cmd.js -f /data/images/<balena.img> -m <device_type> --accept-license=yes -c /tmp/Linux_for_Tegra

It will exit upon completion.

The flashing process may take 5 - 15 minutes or longer during which a lot of log output will appear. If all goes well, you'll see something similar to the following upon completion:

*** The target t186ref has been flashed successfully. ***
Reset the board to boot from internal eMMC.

Emulation with the Jetson AGX Orin Development Kit

The Orin NX 8GB and 16GB can be emulated during flashing of the Jetson AGX Orin Devkit using this jetson-flash branch: https://github.com/balena-os/jetson-flash/commits/orin_nx_emulation_on_agx_orin_devkit

An example command for flashing the emulated configuration is:

sudo bin/cmd.js -m jetson-agx-orin-devkit-as-nx-16gb -f <jetson-agx-orin-devkit.img>

Important notes on Orin NX emulation:

Orin NX Flashing:

Important notes on Orin NX provisioning:

Orin NX Flashing steps:

AGX Orin Devkit 64GB Flashing:

Important notes on AGX Orin Devkit 64GB provisioning:

AGX Orin Devkit 64GB flashing steps:

Orin Nano Flashing:

Important notes on Orin Nano provisioning:

Orin Nano Flashing steps:

Seeed reComputer J3010 Flashing:

Seeed reComputer J3010 Flashing steps:

Seeed reComputer J4012 Flashing:

Seeed reComputer J4012 Flashing steps:

Depending on the device used, the machine used will be one of:

Other considerations:

Support

If you're having any problems, please raise an issue on GitHub and the balena.io team will be happy to help.

Submitting changes

Changes can be submitted in form of PRs to this repository, each PR may include multiple commits.

The header of each commit must not exceed 72 characters in length and must be in 1 line only.

The header and the subject of each commit must be separated by an empty line.

The subject of each commit must not exceed 72 characters per line and can be wrapped to several lines.

The subject and the footer of each commit must be separated by an empty line.

Every pull request must contain at least one commit annotated with the Change-type footer, and all commits should include a Signed-off-by.

An example of a valid commit is:

Update Xavier AGX to L4T 32.7.3

Change-type: patch
Signed-off-by: Your Name <user@email.com>

License

The project is licensed under the Apache 2.0 license.