Upgrading the U-Boot Bootloader
This article shows how to use the (new) bootlaoder to upgrade to an even newer version of the bootloader.
This is useful for:
- Upgrade to a newer U-Boot release.
- (Advanced) Test a custom or development build.
This guide applies to any Omega2 that is already running the modern bootloader and takes less than a minute of actual device time.
Updating the bootloader has the potential to be a destructive action and can lead to a device becoming bricked or unusable.
Take care to ensure:
- The bootloader binary that will be flashed is not corrupted and has been confirmed to be working
- The Omega2 device remains powered on during the update
Onion is not responsible for any damage to devices.
Step 1: Gather Requirements
Gather the requirements:
- The target Omega2 device with access to the following:
- serial command line
- ethernet port
- reset button (GPIO38)
- Note: Access to all of the above is provided on the Omega2 Eval Boards
- A host computer
- Ethernet Cable
- USB cable to connect to the Omega
Step 2: Computer Setup
Serial Command‑Line Drivers Installed
Follow the instructions in step 1 of the connecting to serial command line article to install the drivers required to use the serial command line.
Configure the Ethernet Network
Configure your computer’s ethernet network to manually set its IP address to 192.168.8.100 and subnet mask to 255.255.255.0. By doing so, your computer will be able to communicate with the Omega over ethernet while it is in web recovery mode.
Look up "How to set static IP address" for the host computer operating system to find guides on making the required changes.
Install TFTP Tools
The host computer needs a TFTP server to transfer files to the Omega2 during bootloader or firmware upgrades.
There are many TFTP implementations; this documentation uses the Node.js tftp package because it runs on macOS, Linux, and Windows.
Verify that Node.js and npm are installed.
If they are not, follow the official installation guide.Install the package globally:
npm install -g tftp
After installation you will have an ntftp command in your PATH; you will use it later in this guide to launch a TFTP server from the directory that contains the bootloader binary.
Step 3: Download the Bootloader Binary
Use a browser to navigate to http://repo.onioniot.com/omega2/bootloader/v2025.04/
The u-boot images are named according to this syntax: onion-omega2p_u-boot-with-spl-[UBOOT-RELEASE]-[BUILD-DATE].bin
For example:
onion-omega2p_u-boot-with-spl-v2025.04-20250605.bin
Download the latest available u-boot image and place it in a new, empty directory. This new directory is where you will run the TFTP server.
The same image can be used for the Omega2 and Omega2+ variants. The new bootloader auto-detects flash and RAM size.
Step 4: Start the TFTP Server
In the download folder run:
ntftp 0.0.0.0 -l .
Step 5: Enter the Bootloader Command Line
Connect to the Omega2 command line through serial. Then power on the device and press the SW Reset button at the same time.
The Reset button on the Omega2 Eval Boards and Omega2 Docks is connected to the active-high FW_RST/GPIO38 pin. Pressing the reset button sends a digital-high signal to the FW_RST/GPIO38 pin.
Autoboot will be disabled and the bootloader command line will be visible in the serial command line output.
If the bootloader looks like this screenshot:
Then the device is running the old bootloader. See instead the article on Upgrading the Old Bootloader
Step 6: Transfer the Bootloader Image to the Omega2
Copy the new bootloader image from the host computer to the Omega2 RAM.
First set the bootfile environment variable to the bootloader image filename on the host computer from Step 3:
env set bootfile <BOOTLOADER IMAGE FILENAME>
Then start the file transfer over TFTP:
tftpboot
U‑Boot prints the file size and the RAM address where it was loaded.
Step 7: Prepare Flash & Erase the Old Bootloader
Updating the bootloader has the potential to be a destructive action and can lead to a device becoming bricked or unusable.
Take care to ensure:
- The bootloader binary that will be flashed is not corrupted and has been confirmed to be working
- The Omega2 device remains powered on during the update
Onion is not responsible for any damage to devices.
Initialize the flash:
sf probe
Clear the existing environment variables:
sf erase u-boot-env 0x10000
Finally, erase the existing uboot
sf erase u-boot 0x30000
Each step only takes a moment.
Step 8: Write the New Bootloader
Now write the new bootloader to the flash:
sf update $loadaddr u-boot $filesize
The write will take less than 5 seconds. A success message confirms the write:
=> sf update $loadaddr u-boot $filesize
device 0 offset 0x0, size 0x2fa59
195161 bytes written, 0 bytes skipped in 2.485s, speed 80323 B/s
Step 9: Reboot and Confirm
Reboot the device by running
reset
Watch the boot log. The first line should now show the new build date, for example:
U-Boot 2025.04 (May 10 2025 – 12:34:56)
If the process was successful, Omega will boot normally. The boot log will look like the following:
U-Boot SPL 2025.04-ga92da3b468ea (Apr 23 2025 - 19:14:37 +0000)
Trying to boot from NOR
U-Boot 2025.04-ga92da3b468ea (Apr 23 2025 - 19:14:37 +0000)
CPU: MediaTek MT7688A ver:1 eco:2
Boot: DDR2, SPI-NOR 3-Byte Addr, CPU clock from XTAL
Clock: CPU: 580MHz, Bus: 193MHz, XTAL: 40MHz
Model: Onion Omega2+
DRAM: 128 MiB
Core: 52 devices, 13 uclasses, devicetree: separate
Loading Environment from SPIFlash... SF: Detected w25q256 with page size 256 Bytes, erase size 4 KiBB
OK
In: uartlite@c00
Out: uartlite@c00
Err: uartlite@c00
Initializing MT7688 GPIO system.
Net: eth0: eth@10110000
SF: Detected w25q256 with page size 256 Bytes, erase size 4 KiB, total 32 MiB
Reading 4194304 byte(s) at offset 0x00000000
## Booting kernel from Legacy Image at 81800000 ...
Image Name: MIPS OpenWrt Linux-5.15.150
Image Type: MIPS Linux Kernel Image (lzma compressed)
Data Size: 2348656 Bytes = 2.2 MiB
Load Address: 80000000
Entry Point: 80000000
Verifying Checksum ... OK
Working FDT set to 0
Uncompressing Kernel Image to 80000000
[ 0.000000] Linux version 5.15.150 (builder@buildhost) (mipsel-openwrt-linux-musl-gcc (OpenWrt GC4
[ 0.000000] Board has DDR2
[ 0.000000] Analog PMU set to hw control
[ 0.000000] Digital PMU set to hw control
[ 0.000000] SoC Type: MediaTek MT7688 ver:1 eco:2
[ 0.000000] printk: bootconsole [early0] enabled
[ 0.000000] CPU0 revision is: 00019655 (MIPS 24KEc)
[ 0.000000] MIPS: machine is Onion Omega2+
...