StarFive VisionFive 2 Firmware / Bootloader 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

Prepare SD Card with Older Image

At time of writing if you go to the official StarFive debian.starfivetech.com 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 https://github.com/starfive-tech/VisionFive2/releases/download/VF2_v2.8.0/u-boot-spl.bin.normal.out
james@pop-os:/srv/tftp$ sudo curl -o visionfive2_fw_payload.img -k -L https://github.com/starfive-tech/VisionFive2/releases/download/VF2_v2.8.0/visionfive2_fw_payload.img
% 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:

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 192.168.120.222
setenv serverip 192.168.120.9
setenv gatewayip 192.168.1.1
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.

Conclusion

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