StarFive VisionFive 2 Firmware / Bootloader Update Guide

StarFive VisionFive 2 Firmware Update Guide
StarFive VisionFive 2 Firmware Update Guide

If you’ve just received a new StarFive VisionFive 2 you may be having trouble to get it to boot with the latest images. This is because your firmware needs to be updated before using the latest version.

In this guide we’ll cover how to update the firmware on the StarFive VisionFive 2. Let’s begin!

Hardware Used

StarFive VisionFive 2
StarFive VisionFive 2

The StarFive VisionFive 2 is a quad-core high performance single board computer that runs the RISC-V open-hardware architecture. It also has a dedicated GPU making it suitable for desktop use!

Links:*, AliExpress*

Geekworm Copper Heat Sink Set
Geekworm Copper Heat Sink Set

The Geekworm copper heat sink set is designed to fit many different single board computers. It uses thermal conductive adhesive which many “cheap” heat sink kits for SBCs don’t have. Eliminates hot spots and reduces throttling. Can be further enhanced by powered cooling over the heat sinks.


Prepare SD Card with Older Image

At time of writing if you go to the official StarFive page you will see two versions:

  • Image-55
  • Image-69

You want to download image 55 (the oldest one) because the firmware on your VisionFive 2 will not run version 69 yet.

Download version 55 and extract the .bz2 file which will give you a .img file.

Once you have the .img file write it to a SD card.

Now boot the VisionFive 2 using the old image. It should boot correctly.

Getting Necessary Files

Log into the device with the default credentials of root / starfive. If you would like to do this over SSH then log into the device with user / starfive. You can then use the command “su” and the password starfive to use root.

Now we need to install mtd-utils with:

apt update && apt install mtd-utils -y

Now head to the GitHub releases section for the VisionFive 2 firmware here.

Download the latest versions of the following files:

  • u-boot-spl.bin.normal.out
  • visionfive2_fw_payload.img

Easy Way vs. Hard Way

There is an easy way to update the firmware on the VisionFive 2 but you can’t use it unless you are using version 2.5.0 or later. If you are using V1.2A of board or got the board reasonably close to when I wrote this you do not have this yet and need to use the hard way first.

The hard way requires a Linux PC as you will need to set up a TFTP server for flashing. It also requires a USB to serial adapter as the boot loader cannot display on a monitor and we will be typing commands into the uboot prompt to flash it.

The full documentation for both methods from StarFive is here.

UPDATE 1/26/2023: LivingLinux has let me know on Twitter about an additional image available via the official StarFive GitHub repository that should be able to flash the VisionFive 2 without having to do it the “Hard Way” below. If you are struggling with the uboot-based network TFTP flash and want to try using this image the full instructions are available here. It’s essentially a barebones image that will let us update the firmware via SSH or the serial console.

Updating Firmware – The Hard Way

Setting up TFTP server

First you need to quickly set up a TFTP server on a Linux PC/SBC to host the files we downloaded earlier:

sudo apt install tftpd-hpa

Now change directories to where you downloaded the files such as:

cd ~/Downloads

On my Linux install the tftp server defaults to using the directory /srv/tftp. You can check this with:

systemctl status tftpd-hpa

For example:

systemctl status tftpd-hpa
● tftpd-hpa.service - LSB: HPA's tftp server
Loaded: loaded (/etc/init.d/tftpd-hpa; generated)
Active: active (running) since Tue 2023-01-24 14:28:20 MST; 2min 9s ago
Docs: man:systemd-sysv-generator(8)
Process: 627792 ExecStart=/etc/init.d/tftpd-hpa start (code=exited, status=0/SUCCESS)
Tasks: 1 (limit: 38184)
Memory: 840.0K
CPU: 15ms
CGroup: /system.slice/tftpd-hpa.service
└─627800 /usr/sbin/in.tftpd --listen --user tftp --address :69 --secure /srv/tftp

You can see on the bottom it’s set up to serve on /srv/tftp. Move the files you downloaded to that folder (use root/sudo).

Here’s an example of how I did it:

james@pop-os:/srv$ cd tftp
james@pop-os:/srv/tftp$ sudo curl -o u-boot-spl.bin.normal.out -k -L
james@pop-os:/srv/tftp$ sudo curl -o visionfive2_fw_payload.img -k -L
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0
james@pop-os:/srv/tftp$ ls
uboot-spl.bin.normal.out visionfive2_fw_payload.img

I strongly recommend using the latest versions though and not copy/pasting my exact command which will be release 2.8.0 at time of writing.

The TFTP server is now set up!

Booting into uboot console

To use the uboot console we need to connect the USB to serial console. The wiring for that looks like this:

StarFive VisionFive 2 GPIO Serial Debug Wiring
StarFive VisionFive 2 GPIO Serial Debug Wiring

Once you have everything connected power on the VisionFive 2. You should see a screen that allows you to interrupt the boot process by pressing a key.

For what it’s worth I had to reverse the green and blue wires on my USB to serial adapter and then it worked perfectly. Mine didn’t work with the TX/RX indicated in the picture above but that is from the official documentation. If you are having trouble try switching the TX and RX (leave the GND where it is).

Quickly press a key (it’s okay if you missed it, just try again) and it should take you to a prompt that just says “StarFive”. This is the uboot prompt.

Completing the Updates

First we need to set up some IP addresses. Substitute the IPs with the IPs for your server (the PC running the SFTP server) and VisionFive2.

setenv ipaddr
setenv serverip
setenv gatewayip
sf probe

Now we’re going to update the files with:

tftpboot 0xa0000000 ${serverip}:u-boot-spl.bin.normal.out
sf update 0xa0000000 0x0 $filesize

tftpboot 0xa0000000 ${serverip}:visionfive2_fw_payload.img
sf update 0xa0000000 0x100000 $filesize

Before you reboot make sure none of the commands failed. None of them should have resulted in 0 bytes or any errors. If they did then you need to figure out what went wrong with the IPs / connections and make sure you get a successful flash before rebooting.

My commands did not all work the first time. I had problems with my gatewayip (which I added to the article because it’s not included in the official quick start guide) and other issues. You want to watch and make sure that things completed and that things aren’t 0 bytes or giving some kind of error.

If everything completed then you are all set and can reboot.

Updating Firmware – The Easy Way

The easy way is done on the VisionFive 2 itself.

Change directories to where you downloaded the files such as:

cd ~/Downloads

We can now flash the updated SPL with:

sudo flashcp -v u-boot-spl.bin.normal.out /dev/mtd0
sudo flashcp -v visionfive2_fw_payload.img /dev/mtd1

Before you reboot make sure none of the commands failed. None of them should have resulted in 0 bytes or any errors. If they did then you need to figure out what went wrong and make sure you get a successful flash before rebooting. You want to watch and make sure that things completed and that things aren’t 0 bytes or giving some kind of error.


Now that your firmware is up to date you should be able to boot all of the latest images! I tried my Debian build 69 after doing this process and it boots just fine now.

I can also use the easy way in the future for updates going forward (and so can you)!

Other Resources

I’ve written a review for the StarFive VisionFive 2 available here

I also have a SSD boot guide available for the StarFive VisionFive 2 here

You can see all of my RISC-V articles here

All of my single board computer reviews are available here

Notify of

Inline Feedbacks
View all comments

2 months ago

I want to share a bad experience to avoid that someone else makes the same mistakes…

I started my visionfive 2 last week, and it looked nice. I was running the 69 build I think.

I then tried to update the u-boot flash and spi flash on using the mtd-utils method …

The /dev/mtd0 and /dev/mtd1 devices was present, so I wanted to use flashcp to update them as I had read above. However there was no flashcp command available although I searched several possible locations. So I thought, maybe a normal cp would work ok…. I shouldn’t… I took copies of the contents of the mtd0 and mtd1 devices afterwards (before reboot) and realized the contents of those were not identical (although similar) to the files I had copied. There were bits differing here and there. Strange…

When I rebooted it did not start anymore… When connecting to a USB-serial connector it just tells me “Main section boot fail,use backup section” and then it goes quiet.

If I change the switches to the serial boot mode, it gives me CCC, then (C)StarFive) then CCCCCCCC…. for ever.

I tried to use minicom there and send the jh7110-recovery-20221205.bin file to it but it does not seem to understand that I try to use the xmodem protocol. The CCC:s just keep coming.

Finally I flashed the sdcard.img and to changed the switches to sd-disk boot mode, and was able to transfer the files from a USB-card to the device, and flash them using flashcp (it was present in that image). So now it finally boots again. 🙂

2 months ago

Thanks James,

I can add that currently the board boots nicely with the 69 build, but with the 202302 build it still does not boot.

It does the initial u-boot sequence, and waits for the keyboard interrupt for two seconds, but if it’s not interrupted it fails directly after.

Below is the end of the u-boot sequence before it stops.

It complains early about a CRC error before, but I have seen that in other examples of the boot as well, so that seems not uncommon.

Do you have any input on what is the problem now?

It says FDT_ERR_BADMAGIC, maybe that’s a clue?
U-Boot 2021.10 (Dec 25 2022 – 20:59:18 +0800), Build: jenkins-github_visionfive2-4

CPU: rv64imacu
Model: StarFive VisionFive V2
MMC: sdio0@16010000: 0, sdio1@16020000: 1
Loading Environment from SPIFlash… SF: Detected gd25lq128 with page size 256 Bytes, erase size 4 KiB, total 16 B
*** Warning – bad CRC, using default environment

StarFive EEPROM format v2

Vendor : StarFive Technology Co., Ltd.
Product full SN: VF7110B1-2253-D008E000-00001572
data version: 0x2
PCB revision: 0xb2
BOM revision: A
Ethernet MAC0 address: 6c:cf:39:00:2a:4d
Ethernet MAC1 address: 6c:cf:39:00:2a:4e
--------EEPROM INFO--------

In: serial@10000000
Out: serial@10000000
Err: serial@10000000
Model: StarFive VisionFive V2
Net: eth0: ethernet@16030000, eth1: ethernet@16040000
switch to partitions #0, OK
mmc1 is current device
found device 1
bootmode flash device 1
406 bytes read in 2 ms (198.2 KiB/s)
Importing environment from mmc1 ...
Can't set block device
Hit any key to stop autoboot: 0
Can't set block device
## Warning: defaulting to text format
Can't set block device
libfdt fdt_check_header(): FDT_ERR_BADMAGIC
Retrieving file: /boot/extlinux/extlinux.conf
Can't set block device
Error reading config file
StarFive #

2 months ago
Reply to  Kenneth

Now I realized what my problem was!

I did not realize that the u-boot and fw_payload files were specific to each OS build! Now I flashed the u-boot and fw_payload files bundled with the newer release, and it boots with that.

I would suggest they start naming the released files so it’s easier to understand which version they are supposed to work with as long as they are not compatible with foreseeable future versions…

I can admit am not used to trying out boards that are in “the frontline” and not yet supported, but improved naming could help all I think.

2 months ago

Yes, I agree, it has been a shaky experience, so lets hope they get up to a more stable firmware deliveries soon now.

To their defense, this is one of the first SBCs using RISC-V, so I guess we can’t expect the stability of ARM-based boards quite yet.
Maybe the Star64 board will help stabilize the platform if it is ever released…

Dick MIddleton
Dick MIddleton
2 months ago

Thank heavens you wrote that. I would have been completely lost without it. You don’t need need to download the 55 version and install mda-utils. You just need the latest release (starfive-jh7110-202302-SD-minimal-desktop.img). It’s only 700M rather than 5.6G! And you need to do the tftpd stuff which can you do without SD card. Must enter uboot prompt by responding to press any key – otherwise it complains bitterly about lack of media. Then you can boot your SD image. Easy when you know how. Many many thanks.

James Michael Wall
James Michael Wall
3 months ago

Thanks James! I got it done!

James Michael Wall
James Michael Wall
3 months ago

Hello James, Thanks for the excellent post, I’m currently trying to flash my VF2 board, which is a version 1.2, and using the 55 image. It boots fine, and I have the TTY/USB working perfectly. Problem for me is that cannot get the setenv or sf commands to work for me as per your directions, even after installing the u-boot-tools package and some other development packages, so I’m at a stop point now. I can pull up the man pages for them on my workstation, but when I try to use them on the CLI, I get setenv: command not found, or same thing for sf probe. I’m using Debian 11 Bullseye on my workstation (WS), and am wondering – Are you using Ubuntu on your WS? Maybe I am missing some tools? Also, I had one more Idea here – Can I just copy the updated flash files on my WS to the root my existing (working) 55 image sd-card, and just flash from there?