Flashing the Board
Flashing the Board
This page covers the general flash-bundle workflow and a complete AGX Orin example for the BSP Customization guides. Use the bundle for your selected image and machine.
After generating the deploy artifacts, the next step is programming the image into the target Jetson platform.
This section explains how to deploy the generated flash bundle onto a Jetson device using the NVIDIA flashing utilities included in the Yocto generated deployment package.
The flash bundle packages the generated image artifacts together with the NVIDIA flashing assets required for deployment.
Overview
The flashing sequence consists of:
- Extracting the generated flash bundle
- Putting the Jetson device into recovery mode
- Running the generated flashing scripts
- Deploying the generated image to the target platform
The flashing environment is generated directly from the Yocto build output, ensuring alignment between the deployed system and the selected MACHINE configuration.
The exact flashing behavior may vary depending on the Jetson platform and storage target, such as eMMC, NVMe, SD card, or external storage.
Locate the Flash Bundle
After a successful build, the deploy artifacts are available under:
$WORKSPACE/build/tmp/deploy/images/$MACHINE/
The generated flash bundle typically follows this naming pattern:
demo-image-full-$MACHINE.rootfs.tegraflash-tar.zst
When building a different image recipe, the bundle name changes accordingly. For example:
demo-image-base-$MACHINE.rootfs.tegraflash-tar.zst
The exact directory contents can vary depending on the selected image recipe, machine configuration, and build targets.
The .tegraflash-tar.zst artifact is the primary deployment package used for flashing.
It contains:
- Root filesystem
- Kernel image
- Device tree binaries and overlays
- Bootloader components
- Partition configuration
- Flashing scripts
Extract the Flash Package
Create a temporary flashing workspace:
mkdir -p /tmp/tegraflash
Extract the generated bundle:
tar -C /tmp/tegraflash \
-xf $WORKSPACE/build/tmp/deploy/images/$MACHINE/demo-image-full-$MACHINE.rootfs.tegraflash-tar.zst
This creates an isolated flashing workspace separate from the original build output.
The extracted directory contains the deployment files and flashing scripts used during the flashing process.
Support for .zst compressed archives requires the appropriate host tools, such as zstd, to be installed on the host system.
After extraction, confirm that the flashing scripts are present:
ls /tmp/tegraflash ls /tmp/tegraflash/initrd-flash
Put the Board into Recovery Mode
Before flashing, the Jetson device must enter recovery mode and be connected to the host through USB.
General procedure:
- Power off the board
- Press and hold the recovery button
- Power on or reset the device
- Connect the board to the host through USB
The exact recovery button sequence can vary depending on the Jetson platform or carrier board. Refer to the hardware documentation for the specific board being used.
Verify detection from the host:
lsusb
A detected NVIDIA recovery device confirms that the platform is ready for flashing.
The output should include an NVIDIA USB device entry similar to:
NVIDIA Corp. APX
At this stage, it is also important to determine which flashing method to use for the target platform and deployment scenario.
For additional information about the available flashing methods and when to use them, see:
Related page: initrd vs doflash
Run the Flash Script
Enter the extracted workspace:
cd /tmp/tegraflash
Start the flashing process:
./initrd-flash
Run initrd-flash as your normal user; it invokes tools through sudo when required.
The initrd-flash script performs the deployment process using the artifacts packaged in the flash bundle.
Depending on the selected platform and storage configuration, the process may:
- Detect the Jetson device in recovery mode
- Prepare storage partitions
- Deploy bootloader and firmware assets
- Write the root filesystem
- Configure boot assets
- Reboot the board after completion
After completion, the board reboots automatically.
AGX Orin custom machine example
The following example uses myproduct-image and myproduct-agx-orin from the BSP Customization guides. Its eMMC layout and recovery instructions are specific to the AGX Orin development kit.
After building an image, the final step is to write the boot firmware and root filesystem to the target Jetson. meta-tegra generates a self-contained .tegraflash-tar.zst package with the image, boot artifacts, configuration, and helper scripts needed for flashing.
Prerequisites
Before continuing, complete:
The BitBake environment must be loaded, MACHINE = "myproduct-agx-orin" must be selected, and the myproduct-image target must build successfully. The device-tree, overlay, and kernel-customization guides are optional.
This procedure targets the NVIDIA Jetson AGX Orin development kit and writes the root filesystem to the module's internal eMMC.
Warning: flashing writes boot firmware and storage partitions on the Jetson. Existing data on the flashed partitions will be overwritten. Confirm that the connected device and image match before running the flash command.
1. Prepare the flashing host
Use a native x86-64 Linux host. Do not flash through a virtual machine because USB handoff during recovery boot can be unreliable.
Use a high-quality USB cable connected directly to the host instead of an external USB hub.
On Debian or Ubuntu, install the required tools:
sudo apt-get update
sudo apt-get install \
bmap-tools \
cpp \
device-tree-compiler \
gdisk \
udisks2 \
usbutils
bmaptool is technically optional, but flashing a root filesystem without it can take much longer.
Disable automatic mounting of removable media before flashing. On Ubuntu with GNOME:
gsettings set org.gnome.desktop.media-handling automount false gsettings set org.gnome.desktop.media-handling automount-open false
The initrd-flash script should normally be run as the current user. It invokes individual tools through sudo when root access is required. If USB or storage permissions prevent flashing, configure the host as described in Avoiding sudo.
2. Build the image
Load the BitBake environment and confirm that the expected machine is selected:
bitbake-getvar MACHINE
Expected value:
MACHINE="myproduct-agx-orin"
Build the image:
bitbake myproduct-image
The resulting flashing package should be:
$YOCTO_WORKSPACE/bitbake-builds/meta-tegra-wrynose/build/tmp/deploy/images/myproduct-agx-orin/myproduct-image-myproduct-agx-orin.rootfs.tegraflash-tar.zst
Confirm that it exists:
export FLASH_PACKAGE="$YOCTO_WORKSPACE/bitbake-builds/meta-tegra-wrynose/build/tmp/deploy/images/myproduct-agx-orin/myproduct-image-myproduct-agx-orin.rootfs.tegraflash-tar.zst" test -f "$FLASH_PACKAGE" && ls -lhL "$FLASH_PACKAGE"
Do not use a package built for another MACHINE. Machine selection happens at build time, and the package contains hardware-specific boot and flashing files.
3. Extract the flashing package
Extract the package into a new directory. Use tar rather than a graphical archive tool:
export FLASH_DIR="$HOME/jetson-flash/myproduct-agx-orin-$(date +%Y%m%d-%H%M%S)" mkdir -p "$FLASH_DIR" tar -xf "$FLASH_PACKAGE" -C "$FLASH_DIR" cd "$FLASH_DIR"
Confirm that the main script is present:
test -x ./initrd-flash && echo "Flash package ready"
You can inspect the available options without modifying the target:
./initrd-flash --help
Run all flashing commands from this extracted directory. The scripts expect the packaged files to be available relative to the current working directory.
4. Put the AGX Orin into Force Recovery Mode
Connect the host to the USB-C port next to the 40-pin header. This is the AGX Orin port used for flashing and USB device mode.
If the development kit is already powered on:
- Press and hold the Force Recovery button.
- Press and hold the Reset button.
- Release both buttons.
If the development kit is powered off:
- Press and hold the Force Recovery button.
- Connect power to the development kit.
- If the power LED does not turn on, press the Power button.
- Release the buttons.
The button sequence and connector locations are documented in NVIDIA's AGX Orin Developer Kit user guide.
Confirm that the host detects an NVIDIA recovery-mode USB device:
lsusb -d 0955:
Reference output may look like:
Bus 001 Device 012: ID 0955:7023 NVIDIA Corp.
Bus and device numbers vary. An AGX Orin main CPU commonly appears as 0955:7023 or 0955:7223. The supervisor CPU may also appear as 0955:7045.
Do not start flashing until the main Jetson device is visible.
5. Perform the first flash
For the first flash, write both the boot firmware and root filesystem:
./initrd-flash
For myproduct-agx-orin, this operation writes:
- boot firmware to QSPI flash;
- the root filesystem and its partitions to the module's internal eMMC.
The script RCM-boots a specialized Linux image over USB, sends the flashing commands and data, writes the configured devices, and retrieves the final status and device logs.
Do not disconnect USB, remove power, or close the terminal while flashing is in progress. Wait for a successful final status. The script prints paths similar to:
Host-side log: log.initrd-flash.YYYY-MM-DD-HH.MM.SS Device-side logs stored in: device-logs-YYYY-MM-DD-HH.MM.SS
Orin targets are instructed to reboot automatically after flashing. A manual power cycle is only required if the board does not reboot as expected.
6. Use partial flashing only when appropriate
After a successful full flash, the script supports partial operations.
Rewrite the root filesystem without updating QSPI
./initrd-flash --external-only
The option name is historical. Internally, it means “skip the bootloader.” For the AGX Orin machine used by this guide, it skips the QSPI update but still rewrites the root filesystem on internal eMMC.
Update only QSPI boot firmware
./initrd-flash --qspi-only
This skips the root filesystem and writes only the boot firmware.
--external-only and --qspi-only are mutually exclusive. Do not combine them. Use a complete ./initrd-flash whenever boot firmware and root filesystem must be updated together.
7. Validate the flashed system
After the Jetson reboots, log in through the configured console or network and check the running system.
Confirm the hardware model:
tr '\0' '\n' < /sys/firmware/devicetree/base/model
Confirm the active device-tree compatible strings:
tr '\0' '\n' < /sys/firmware/devicetree/base/compatible
Confirm the running kernel:
uname -a
Confirm the root filesystem device:
findmnt -no SOURCE /
For the AGX Orin configuration used in this guide, the root filesystem should come from the module's eMMC.
If the previous customization guides were completed, also verify their runtime markers:
tr '\0' '\n' < /sys/firmware/devicetree/base/chosen/myproduct-overlay-test zgrep '^CONFIG_NTFS3_FS=' /proc/config.gz
These checks confirm that the flashed image includes the custom machine, device tree overlay, and kernel configuration created in the previous guides.