Milk-V Meles Image Flashing Guide
This page provides a tutorial for flashing images to the Milk-V Meles, specifically for Linux.
To view image flashing tutorials for other operating systems, please click the links in the table below:
| Other Flashing Tutorials | Link |
|---|---|
| LicheePi4A | Linux Flashing Tutorial |
| LicheePi4A | Windows Flashing Tutorial |
| Milk-V Pioneer | Flashing Tutorial |
Before proceeding with this tutorial, please ensure that the board you have matches the image below. Only continue if they are identical.
Introduction to the Demonstration Environment
All image flashing operations in this tutorial are performed using the following environment:
- System and Version: Ubuntu 22.04.5 LTS
- Architecture: x86_64
- Board Specifications: 8GB RAM
- Python Version: 3.10.12
All operations in this tutorial are reproducible in this environment. If you encounter any issues during image flashing in this environment, please refer to this page to submit an issue.
Using a Python version higher than 3.12 may cause the the procedure of writing bootloader to SPI Nor Flash to fail. Please use a Python version prior to 3.12.
Tool Installation
This section introduces the software packages and tools required for downloading and flashing the image. Please download and install them before proceeding with the subsequent image flashing operations.
File Download Tool
When using a graphical interface, you can download images from the image repository by directly clicking the download link. If you want to download via the command line, there are many ways, such as wget and curl. Here, we choose wget as the download tool.
In the demonstration environment, wget is usually pre-installed. You can check whether wget is installed by querying the wget version in the command line.
wget --version
If wget is not installed, please use the following command to install it:
sudo apt install wget
The sudo command requires the user to enter a password for confirmation before execution. Please ensure that you know the password before executing this command. This will not be repeated later.
File Unzipping Tool
In the above demonstration environment, there are several ways to decompress zst file compression packages, such as zstd, tar, and 7z. This tutorial only lists one of them. Use the zstd tool to decompress via the command line. This method requires us to install the zstd software package in the system before decompressing.
If you do not know whether ztsd has been installed in the system, please execute the following command. This command is used to view the zstd version. You can determine whether the system has pre-installed the ztsd software package through the echo.
zstd --version
If the version number is displayed normally, it proves that the installation has been successful. For example, the following echo indicates that zstd has been installed:
*** zstd command line interface 64-bits v1.4.8, by Yann Collet ***
If no version number is displayed, please install zstd via the command line:
sudo apt update
sudo apt install zstd
Introduction to Broad's Boot Methods
Milk-V Meles currently supports two boot methods: Booting from SD card and Booting from eMMC. This tutorial provides instructions for both boot methods. Please click to jump to the instructions according to the flashing method you need.
Regardless of which flashing method is used, the original user data will be lost, so be sure to back up your data before flashing!
Before introducing the two flashing methods, it should be noted that regardless of which flashing method is used, you must ensure that the correct firmware is flashed into the SPI Nor Flash. Next, we will introduce how to flash the SPI Nor Flash firmware.
Flashing SPI Nor Flash Firmware
The Milk-V Meles development board has a SPI nor Flash. It is used to store the Bootloader to implement system startup and SoC download mode. The Soc itself does not support booting from Micro SD card or USB or other storage media.
When you replace a brand new SPI Nor Flash or the firmware is damaged, you may need to burn an image to it. At this time, you need to use a serial port connection to burn it.
For how to connect the serial port, please refer to the official hardware introduction. The connection with the host should follow the TX to RX, RX to TX, and GND to GND wiring.
Preparation
First, you need to install yoctools to the local device. In the demonstration environment, you can directly install it through the pip command:
sudo pip install yoctools -U
If the pip command cannot be executed, please install pip first if pip is not installed:
sudo apt install python3-pip
After yoctools is installed, you can check whether the installation is successful by checking the version. If the version number is successfully echoed, it means the installation is successful.
yoc --version
2.1.11
Secondly, you need to download the image burning software:
wget https://github.com/milkv-meles/thead-bin/raw/main/image-writer/iw-single-line.bin
Finally, you need to download the U-Boot file of the board. Please select the U-Boot file corresponding to your board in the download link. If your development board is the 8GB version, you need to download u-boot-with-spl-meles.bin. If your development board is the 16GB version, download u-boot-with-spl-meles-16g.bin. The 8GB version of the board is used in this demonstration environment, so u-boot-with-spl-meles.bin is downloaded.
wget https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250323/u-boot-with-spl-meles.bin
After the above preparations are completed, you can perform the operation of flashing the SPI Nor Flash firmware.
Write Bootloader to SPI Nor Flash
First you need to use the cct tool to check for available devices.
Before this, we need to confirm the address of the serial port device. /dev/ttyUSB0 is usually the first serial port device name assigned by the system when you plug in the first USB to serial port adapter or some devices with built-in USB to serial port functions. We run the following command in the terminal:
sudo cct list -u /dev/ttyUSB0
Wait ..............
The log "Wait ......" output here means that the cct program is waiting for Meles to respond. If the serial port is not connected, it will continue to wait until the serial port is connected before continuing to execute. So it is a normal phenomenon, just continue to perform the operation according to the steps below.
If it is not connected for too long, the terminal will display the following text:
- First connect the USB to TTL serial port module to the Meles debugging interface
- Connect TXD to RXD
- Connect RXD to TXD
- Connect GND to GND
- Then press and hold the download button
- Connect the power supply to power on Meles
- Release the download button
At this time, the terminal will print the storage list, as shown below:
sudo cct list -u /dev/ttyUSB0
Wait ............................
Memory device list:
dev = ram0 , size = 1.1MB
dev = qspi0 , size = 16.0MB
Then we download the image burning software to SRAM:
sudo cct download -u /dev/ttyUSB0 -d ram0 -f iw-single-line.bin -v checksum -r
After executing this command, there will be a percentage progress bar. Please wait for about 30 seconds.
Then the download is complete:
sudo cct download -u /dev/ttyUSB0 -d ram0 -f iw-single-line.bin -v checksum -r
Wait
Send file 'iw-single-line.bin' to 2:0 ...
File iw-single-line.bin download success.
Start to verify data with method:[checksum]
checksum value is: 0x880572
读出并校验成功!
Start to run image...
Finally, download the Bootloader to SPI Nor Flash. Before this step, please confirm again whether the board specifications and the downloaded .bin file correspond. The demonstration uses the 8GB version of the board, so u-boot-with-spl-meles.bin is downloaded. Please replace the file name yourself when copying the command.
At the same time, please pay attention to the file directory. The demonstration file is in the current directory. If it is not in the current directory, please replace the file path yourself.
$ sudo cct download -u /dev/ttyUSB0 -d qspi0 -f u-boot-with-spl-meles.bin -v checksum -r -t 1200
After executing this command, there will also be a percentage progress bar. Please wait for about one minute.
Then the download is complete:
sudo cct download -u /dev/ttyUSB0 -d qspi0 -f u-boot-with-spl-meles.bin -v checksum -r -t 1200
Wait
Send file 'u-boot-with-spl-meles.bin' to 23:0 ...
File u-boot-with-spl-meles.bin download success.
Start to verify data with method:[checksum]
checksum value is: 0x43bce40
读出并校验成功!
Start to run image...
So far, the flashing is complete. Subsequent boot methods are divided into Booting from SD card and Booting from eMMC. Please select and flash according to your needs.
Booting from SD card
Hardware Preparation
Prepare a MicroSD card reader and a MicroSD card. Currently, there are compatibility issues with MicroSD cards. RevyOS provides a MicroSD card list(Chinese only) that has been tested.
If the MicroSD card you are using is not on the list of known available cards, and you encounter problems such as being unable to flash the image correctly or being unable to start the image after flashing, please refer to this page to submit an issue, and try referring to the Booting from eMMC image flashing tutorial to flash the image.
SD Card Image Preparation
The latest version of the SD card image is 20250323, which can be downloaded via the following command:
wget https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250323/sdcard-meles-20250323_154525.img.zst
This file is a .zst compressed package, which needs to be decompressed after downloading. You can use the zstd tool to decompress it.
unzstd sdcard-meles-20250323_154525.img.zst
After decompression, an image file named sdcard-meles-20250323_154525.img will be generated.
Introduction to Burning Methods
If you choose to boot from SD card, you can choose to burn the image to the MicroSD card in two different ways. One is to use graphical interface software to burn, and the other is to use the dd command to burn in the command line. Here we will introduce the operation steps of the two burning methods, you can choose one of them according to your needs.
Writing the image to the MicroSD card using BalenaEtcher
Get the burning tool BalenaEtcher from the official website https://etcher.balena.io/. When downloading, please select the file to download according to your machine's situation. According to the description in Demonstration Environment, select Etcher for Linux x64 (64-bit) (zip) to download, decompress and install.
Insert the SD card into the card reader and insert it into the computer.
Run BalenaEtcher to write the image to the SD card.
In the BalenaEtcher window, first click "Flash from file" to select the image file.
After selecting the image file, select the device to be written in the second column.
After selecting both items, click "Flash" to write the image.
After waiting for a while, it will show that the burning is complete.
Writing the image using dd command
dd is a powerful command line tool in Linux and Unix-like systems, mainly used to copy files or data according to the specified size and format, and is generally pre-installed in the system.
Writing an image using the dd command requires following these steps:
First, you need to view the device list. Run the following command before and after inserting the SD card to find the device name corresponding to the SD card:
lsblk
The device name of the SD card may be /dev/sda or /dev/mmcblk0. In the demonstration environment, after executing lsblk, confirm that the sd card partition is /dev/sda.
Before writing the image, you need to unmount the mounted partition of the SD card. If there are multiple partitions, please unmount them one by one:
sudo umount /dev/sda1
If no partition is mounted, the umount command will display not mounted, then no further action is required.
After unmounting the partition, it is recommended to run the sudo sync command to ensure that all data has been synchronized.
After performing the above steps, you can start flashing. Before flashing, please ensure that you have set the correct device in of=. In the demonstration environment, the sd card is identified as sda. Please fill in the partition according to your own device after of=.
sudo dd if=./sdcard-meles-20250323_154525.img of=/dev/sda bs=4M status=progress
After the flashing is completed, please also execute the sudo sync command to ensure that the data has been synchronized. Then you need to confirm that the sd card is in an unmounted state. Only after these two points are executed can you remove the sd card and insert it into the development board.
Booting the system via SD card
After writing the image, insert the SD card into the card slot shown in the figure.
Booting from eMMC
Before flashing, make sure that the eMMC module has been successfully installed on the back of the development board.
eMMC Image Preparation
The latest version of the eMMC image is 20250323, which can be downloaded via the following command:
wget https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250323/u-boot-with-spl-meles.bin
wget https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250323/boot-meles-20250323_154525.ext4.zst
wget https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250323/root-meles-20250323_154525.ext4.zst
The three files are the u-boot boot file, the boot partition and the root partition image files, respectively. After downloading, you need to decompress them. You can use the zstd tool to decompress them.
unzstd boot-meles-20250323_154525.ext4.zst
unzstd root-meles-20250323_154525.ext4.zst
After decompression, two image files named boot-meles-20250323_154525.ext4 and root-meles-20250323_154525.ext4 will be generated.
Burning Tool Preparation
To boot from eMMC, you need to flash the u-boot file, boot file, and root file into the eMMC through the fastboot tool, so you need to confirm whether fastboot has been installed first.
If you do not know whether fastboot has been installed in the system, please execute the following command. This command is used to view the fastboot version. You can determine whether the system has pre-installed the fastboot software package through the echo.
fastboot --version
If the version number is displayed normally, it proves that the installation has been successful. For example, the following echo indicates that fastboot has been installed:
fastboot version 28.0.2-debian
Installed as /usr/lib/android-sdk/platform-tools/fastboot
If no version number is displayed, please install fastboot via the command line:
sudo apt install fastboot
Writing the image to eMMC
First, you need to put the board into burning mode. Please perform the following operations in order:
- Press and hold the Meles download button
- Insert the Type-C data cable into the power port once, and connect the other end of the data cable to the host
- Release the download button
At this time, you can judge whether the device is connected normally according to the output content in lsusb.
After a normal connection, the following device ID 2345:7654 T-HEAD USB download gadget will be displayed under the lsusb command.
fastboot flash ram u-boot-with-spl-meles.bin
fastboot reboot
# Pause here for 3-5 seconds to wait for Meles to restart
fastboot flash boot boot-meles-20250323_154525.ext4
fastboot flash root root-meles-20250323_154525.ext4
After the flashing is completed, it can be started normally.