diff --git a/build.txt b/build.txt new file mode 100644 index 0000000..830c3e3 --- /dev/null +++ b/build.txt @@ -0,0 +1,22 @@ +. +├── ./CMakeLists.txt +├── ./data +│   └── ./data/edges_readable.csv +├── ./output +│   ├── ./output/kruskal +│   │   ├── ./output/kruskal/mst.svg +│   │   ├── ./output/kruskal/route.txt +│   │   └── ./output/kruskal/steps.txt +│   ├── ./output/prim +│   │   ├── ./output/prim/mst.svg +│   │   ├── ./output/prim/route.txt +│   │   └── ./output/prim/steps.txt +│   └── ./output/shared +│   └── ./output/shared/adjacency_matrix.csv +├── ./README.md +└── ./src + ├── ./src/kruskal_algo.cpp + ├── ./src/main.cpp + └── ./src/prim_algo.cpp + +7 directories, 13 files diff --git a/docs/intro.mdx b/docs/intro.mdx index afaf24f..d60044a 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -62,6 +62,3 @@ __RevyOS__ 的用户版镜像目前在 ISCAS（中国科学院软件研究所） RevyOS 有自己的 Telegram 群组：[邀请链接](https://t.me/+Pi6px22-OsUxM2M1) -## 实习生招聘 - -现在正在招聘测试实习生，详情请看：[RevyOS 小队测试实习生招聘](https://github.com/plctlab/weloveinterns/blob/master/open-internships.md#j143-revyos%E5%B0%8F%E9%98%9F%E6%B5%8B%E8%AF%95%E5%AE%9E%E4%B9%A0%E7%94%9F20241111%E5%BC%80%E6%94%BE100%E5%90%8D) diff --git a/docs/npu/lpi4a/object-detection/yolov5.mdx b/docs/npu/lpi4a/object-detection/yolov5.mdx new file mode 100644 index 0000000..b391392 --- /dev/null +++ b/docs/npu/lpi4a/object-detection/yolov5.mdx @@ -0,0 +1,217 @@ +--- +title: YOLOv5 +description: 在 RevyOS 系统上部署和运行 YOLOv5 模型的教程 +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## YOLOv5 + +本教程将引导你如何通过 CPU 或 NPU 在 RevyOS 系统上运行 YOLOv5 模型。 + +:::info[初始环境配置] +在按照本教程操作前，请确保你已经完成了[环境配置](../../env)部分的内容。 +::: + +## 示例代码获取 + +本教程配套的示例代码已更新到 [Github](https://github.com/zhangwm-pt/lpi4a-example) 中，使用 `git` 命令将其克隆到本地。 + +```shell-session +$ git clone https://github.com/zhangwm-pt/lpi4a-example.git +``` + +适用于本教程的代码位于 `detection/yolov5` 目录下。 + +## 模型获取 + +本教程中使用的模型来自 yolov5 模型仓库，可通过其 `export.py` 脚本导出。 +```python +$ git clone https://github.com/ultralytics/yolov5.git +$ cd yolov5 +$ pip3 install ultralytics +$ python3 export.py --weights yolov5n.pt --include onnx --imgsz 384 640 +``` + +:::note[关于 Github 的网络代理] +如果你在中国大陆访问 GitHub 时遇到网络问题，可以考虑使用网络代理工具来加速访问。 +::: + + +## 转换和编译模型 + +环境配置完成后，即可使用 HHB 编译模型为 c920 上的可执行程序。 + +本教程中使用的检测模型是 yolov5n，针对 yolov5n，hhb 命令中截取到最后的卷积层为止，卷积层之后的后处理，交由示例中已准备好的 yolov5n.c 文件处理。 + +进入 `detection/yolov5` 目录，执行以下命令： + + + +```shell-session +$ hhb -D --model-file yolov5n.onnx --data-scale-div 255 \ + --board c920 --input-name "images" --output-name \ + "/model.24/m.0/Conv_output_0;/model.24/m.1/Conv_output_0;/model.24/m.2/Conv_output_0" \ + --input-shape "1 3 384 640" --quantization-scheme float16 +``` + + +```shell-session +$ hhb -D --model-file yolov5n.onnx --data-scale-div 255 \ + --board th1520 --input-name "images" --output-name \ + "/model.24/m.0/Conv_output_0;/model.24/m.1/Conv_output_0;/model.24/m.2/Conv_output_0" \ + --input-shape "1 3 384 640" --calibrate-dataset kite.jpg \ + --quantization-scheme "int8_asym" +``` + + + +:::info[关于参数] +- `-D`：指定 HHB 流程执行到生成可执行文件的阶段为止 +- `--model-file`：指定输入模型文件 +- `--data-mean`：指定均值 +- `--data-scale`：指定缩放值 +- `--board`：指定目标平台为 C920（CPU） 或 TH1520（NPU) +- `--input-name`： 模型的输入 tensor 名 +- `--output-name`：模型的输出 tensor 名 +- `--input-shape`：模型的输入 tensor 形状 +- `--postprocess`：指定 HHB 生成的胶水代码的后处理行为。`save_and_top5` 表示保存输出结果，并且打印 top5 结果 +- `--quantization-scheme`：指定量化类型 + +你可以通过运行 `hhb --help` 查看所有可用的参数和选项。 +::: + +:::info[关于 HHB 生成的文件] +命令执行完成后，会在当前目录生成 hhb_out 子目录，里面的包括了 `hhb_runtime` `model.c` 等多个文件： + +- `hhb.bm`：HHB 的模型文件，包括了量化后的权重数据等信息 +- `hhb_runtime`：适用于开发板的可执行文件，由目录中的C文件编译而成 +- `main.c`：HHB 生成的示例程序的参考入口 +- `model.c`：HHB 模型结构表示文件，与模型结构相关 +- `model.params`：模型权重文件 +- `io.c`：HHB 生成的示例程序，包含读写文件的辅助函数 +- `io.h`：HHB 生成的示例程序，包含读写文件的辅助函数声明 +- `process.c`：HHB 生成的示例程序，包含图像预处理函数 +- `process.h`：HHB 生成的示例程序，包含图像预处理函数声明 +::: + +### gcc 编译后处理 + +本教程中，使用了 c 代码实现模型的后半部分和 NMS，后处理输出图片对应的检测结果。 +```C +$ riscv64-unknown-linux-gnu-gcc yolov5n.c -o yolov5n_example hhb_out/io.c \ + hhb_out/model.c -Wl,--gc-sections -O2 -g -mabi=lp64d -I hhb_out/ -L \ + /usr/local/lib/python3.8/dist-packages/hhb/install_nn2/th1520/lib/ \ + -lshl -L /usr/local/lib/python3.8/dist-packages/hhb/prebuilt/decode/install/lib/rv \ + -L /usr/local/lib/python3.8/dist-packages/hhb/prebuilt/runtime/riscv_linux \ + -lprebuilt_runtime -ljpeg -lpng -lz -lstdc++ -lm -I \ + /usr/local/lib/python3.8/dist-packages/hhb/install_nn2/th1520/include/ -mabi=lp64d \ + -march=rv64gcv0p7_zfh_xtheadc -Wl,-unresolved-symbols=ignore-in-shared-libs -I \ + /usr/local/lib/python3.8/dist-packages/hhb/install_nn2/th1520/include/shl_public/ \ + -I /usr/local/lib/python3.8/dist-packages/hhb/install_nn2/th1520/include/csinn/ +``` + +本教程的示例代码中链接了 shl 库，比如 shl 的安装目录在 `/usr/local/lib/python3.8/dist-packages/shl`。 + +:::info[选项说明] +- `-Ihhb_out -I/usr/local/lib/python3.8/dist-packages/shl/install_nn2/c920/include/`：头文件的搜索路径，指定到 shl 的头文件路径 +- `-L/usr/local/lib/python3.8/dist-packages/shl/install_nn2/c920/lib`：库的搜索路径，指定到预编译好的 shl 的二进制库路径 +- `-static`：指定为静态链接 +- `-o yolov5n_example`：指定生成名为 yolov5n_example 的可执行文件 +::: + +编译命令正确执行完成后会在示例目录生成 yolov5n_example 文件。 + +## 执行 + +交叉编译完成后，即可将程序执行所需的文件复制到开发板的目录中。 + +以开发板 ip 为 10.63.x.x，使用 /demo 目录为例，主机上将示例程序的目录通过 scp 复制到目录中： + +```bash +scp -r yolov5n th1520@10.63.x.x:/demo/ +``` + +linux 命令行执行时，开发板的命令行终端上，到示例目录执行命令。执行完成后，会在终端上提示执行到的各个阶段： +1. 预处理：将原图填充缩放到 384 * 640 的大小 +2. 模型执行和后处理：执行模型推理，并做 nms 等后处理 +3. 画框：将检测结果画在 384 * 640 尺寸的图上，并输出新图片 + +:::info[执行需要的文件] +- `kite.jpg`：输入图片 +- `image_preprocessed.bin`：预处理阶段，根据输入图片生成的中间结果 +- `yolov5n_example`：模型执行阶段使用的文件，由x86主机上 gcc 编译生成 +- `hhb_out/hhb.bm`：模型执行阶段使用的文件，由x86主机上 HHB 生成 +- `detect.txt`：后处理阶段的输出文件，包括了图片中检测出来的 4 个目标 +- `kite_result.jpg`：输出图片，将检测框加入到输入图上的结果 +::: + +## 参考结果 + +本教程中输入如下图，是一个一家三口放风筝的图片，预期 yolov5 的检测结果是检测到三个人和一个风筝。 +![输入图像](/img/image-for-flash/yolov5.png) +![检测图像](/img/image-for-flash/yolov5_2.png) + +示例正常执行时，会有类似如下打印： + + + +```shell-session +$ .python3 inference.py + ********** preprocess image ********** + ******* run yolov5 and postprocess ******* +Run graph execution time: 401.13336ms, FPS=2.49 +detect num: 4 +id: label score x1 y1 x2 y2 +[0]: 0 0.899609 274.486389 158.510849 359.157715 332.118591 +[1]: 0 0.880201 80.017410 184.470093 190.141861 349.840637 +[2]: 0 0.844358 219.474869 221.711838 283.615723 333.643250 +[3]: 33 0.667759 67.194008 174.118088 203.020660 220.667618 + ********** draw bbox ********** +[274.486389, 158.510849, 359.157715, 332.118591, 0.899609, 0] +[80.01741, 184.470093, 190.141861, 349.840637, 0.880201, 0] +[219.474869, 221.711838, 283.615723, 333.64325, 0.844358, 0] +[67.194008, 174.118088, 203.02066, 220.667618, 0.667759, 33] +``` + + +```shell-session +$ python3 inference.py + ********** preprocess image ********** + ******* run yolov5 and postprocess ******* +INFO: NNA clock:1001624 [kHz] +INFO: Heap :anonymous (0x2) +INFO: Heap :dmabuf (0x2) +INFO: Heap :unified (0x5) +WARNING: Mapping to the on chip ram failed (128 > 0), continuing... +FATAL: Importing 737280 bytes of CPU memory has failed (Invalid argument) +Run graph execution time: 11.96299ms, FPS=83.59 +detect num: 4 +id: label score x1 y1 x2 y2 +[0]: 0 0.895277 273.492188 161.245056 359.559814 330.644257 +[1]: 0 0.887368 79.860062 179.181244 190.755692 354.304474 +[2]: 0 0.815214 222.054565 224.477600 279.828979 333.717285 +[3]: 33 0.563324 67.625580 173.948883 201.687988 219.065765 + ********** draw bbox ********** +[273.492188, 161.245056, 359.559814, 330.644257, 0.895277, 0] +[79.860062, 179.181244, 190.755692, 354.304474, 0.887368, 0] +[222.054565, 224.4776, 279.828979, 333.717285, 0.815214, 0] +[67.62558, 173.948883, 201.687988, 219.065765, 0.563324, 33] +``` + + + diff --git a/docs/npu/lpi4a/object-detection/yolox.mdx b/docs/npu/lpi4a/object-detection/yolox.mdx new file mode 100644 index 0000000..422943b --- /dev/null +++ b/docs/npu/lpi4a/object-detection/yolox.mdx @@ -0,0 +1,114 @@ +--- +title: YOLOX +description: 在 RevyOS 系统上运行 YOLOX 模型的教程 +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +## YOLOX + +本教程介绍如何在 **LicheePi 4A** 上部署 YOLOX 目标检测模型，并使用 **HHB-onnxruntime** 实现高效推理。 + + +:::info[初始环境配置] +在按照本教程操作前，请确保你已经完成了[环境配置](../../env)部分的内容。 +::: + +## 示例代码获取 + +本教程配套的示例代码已更新到 [Github](https://github.com/zhangwm-pt/lpi4a-example) 中，使用 `git` 命令将其克隆到本地。 + +```shell-session +$ git clone https://github.com/zhangwm-pt/lpi4a-example.git +``` +适用于本教程的代码位于 `detection/yolox` 目录下。 + +## 模型获取 + +我们使用的模型来自 [Megvii-BaseDetection/YOLOX](https://github.com/Megvii-BaseDetection/YOLOX)，可以通过以下命令下载 YOLOX 模型： + +```shell-session +$ git clone https://github.com/Megvii-BaseDetection/YOLOX.git +$ cd YOLOX/demo/ONNXRuntime +$ wget https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.1rc0/yolox_s.onnx +``` + +:::note[关于 Github 的网络代理] +如果你在中国大陆访问 GitHub 时遇到网络问题，可以考虑使用网络代理工具来加速访问。 +::: + +## 修改源码 +修改文件 demo/ONNXRuntime/onnx_inference.py 的开头，新增如下所示的第四和第五行代码 +```python +#!/usr/bin/env python3 +# Copyright (c) Megvii, Inc. and its affiliates. + ++import sys ++sys.path.insert(0, "../../") + +import argparse +import os +``` +代码中使用 sys.path.insert 指定搜索路径，以此免去从源码中安装 YOLOX 的安装包的操作。 + +## 环境准备 + +本教程中的 YOLOX 示例依赖了较多的 python 包，下载预编译好的 python 包 +```shell-session +$ git clone -b python3.11 https://github.com/zhangwm-pt/prebuilt_whl.git +$ cd prebuilt_whl +``` + +或者也可以通过手动下载进行处理 +``` +$ pip3 install numpy-1.25.0-cp311-cp311-linux_riscv64.whl +$ pip3 install opencv_python-4.5.4+4cd224d-cp311-cp311-linux_riscv64.whl +$ pip3 install kiwisolver-1.4.4-cp311-cp311-linux_riscv64.whl +$ pip3 install Pillow-9.5.0-cp311-cp311-linux_riscv64.whl +$ pip3 install matplotlib-3.7.2.dev0+gb3bd929cf0.d20230630-cp311-cp311-linux_riscv64.whl +$ pip3 install pycocotools-2.0.6-cp311-cp311-linux_riscv64.whl +$ pip3 install loguru-0.7.0-py3-none-any.whl +$ pip3 install MarkupSafe-2.1.3-cp311-cp311-linux_riscv64.whl +$ pip3 install torch-2.0.0a0+gitc263bd4-cp311-cp311-linux_riscv64.whl +$ pip3 install torchvision-0.15.1a0-cp311-cp311-linux_riscv64.whl +$ pip3 install psutil-5.9.5-cp311-abi3-linux_riscv64.whl +$ pip3 install tqdm-4.65.0-py3-none-any.whl +$ pip3 install tabulate-0.9.0-py3-none-any.whl +``` +安装过程中会涉及到其他纯 python 依赖包，pip 会自动从官方源下载。 + + +## 推理执行 + +在示例目录中执行 onnx_inference.py 示例 + +```bash +$ python3 onnx_inference.py -m yolox_s.onnx -i ../../assets/dog.jpg -o outdir -s 0.7 --input_shape 640,640 +``` + +:::info[关于参数] + +- `-m`：指定模型文件 +- `-i`：输入图片路径 +- `-o`：输出结果目录 +- `-s`：检测阈值 +- `--input_shape`：输入图像尺寸 +::: + +## 参考结果 + +本教程中输入如下图，0.7的阈值下，预期 YOLOX 的检测结果如下。 + + +![输入图像](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/assets/application/yolox_detection_soccer_input.jpg) + +示例正常执行后，会在 outdir 目录下生成结果图片 dog.jpg。图片中会用框画出检测到的目标，并标注概率，效果如下图： + +![检测结果](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/assets/application/yolox_detection_soccer_output.jpg) + +检测到两个人和一个足球。 + + diff --git a/docs/typical-applications/bert-on-npu.md b/docs/typical-applications/bert-on-npu.md deleted file mode 100644 index a05f920..0000000 --- a/docs/typical-applications/bert-on-npu.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Licheepi 4A TH1520 NPU 上运行 BERT 模型（HHB 量化 & 推理） -sidebar_position: 3 ---- - -# Licheepi 4A TH1520 NPU 上运行 BERT 模型（HHB 量化 & 推理） - -本文详细介绍如何在 LicheePi 4A 的 TH1520 NPU 上部署和运行 BERT 模型，包括使用 HHB 工具进行量化和推理的完整流程。 - -## BERT模型简介 - -BERT (Bidirectional Encoder Representations from Transformers) 是一种预训练语言模型，在自然语言处理领域有广泛应用。 - -本教程介绍如何在 **Licheepi 4A TH1520 开发板** 上使用 **HHB（Heterogeneous Hybrid Binary）** 工具链，编译并运行 **BERT 模型**，实现阅读理解任务的推理。 - ------- - -## **1. 环境准备** - -### **1.1. 确保已安装 HHB** - -参考[文档](https://github.com/jason-hue/plct/blob/main/%E6%B5%8B%E8%AF%95%E6%96%87%E6%A1%A3/LIcheepi%204A%E9%83%A8%E7%BD%B2%20mobilenetv2%20%E6%A8%A1%E5%9E%8B%E5%AE%8C%E6%88%90%E5%9B%BE%E5%83%8F%E5%88%86%E7%B1%BB%E7%9A%84%E7%A4%BA%E4%BE%8B.md)搭建好 NPU 使用相关环境后，进入到 HHB 环境的 Docker 镜像中。 - -### **1.2. 下载 BERT 模型和示例代码** - -首先获取模型，本教程中使用的模型来自 google bert 仓库，已转换成 onnx 版本的 BERT 模型，可以用如下命令下载到 `/home/example/c920/bert_small` 目录下: - -```bash -cd /home/example/c920/bert_small - -wget https://github.com/zhangwm-pt/bert/releases/download/onnx/bert_small_int32_input.onnx -``` - ------- - -## **2. 使用 HHB 编译 BERT 模型** - -将 ONNX 模型交叉编译成 NPU 上可执行的程序，需要使用 hhb 命令。注意，NPU 上仅支持8位或者16位定点运算，本示例中指定为 int8 非对称量化。编译时需要先进入到示例所在目录 - -### **2.1. 进入 BERT 目录** - -```bash -cd /home/example/c920/bert_small -``` - -### **2.2. 运行 HHB 编译** - -注意必须要使用这这里的工具链，否则编译出的二进制文件无法在 LicheePi 4A 上运行。 - -```bash -export PATH=/tools/Xuantie-900-gcc-linux-5.10.4-glibc-x86_64-V2.6.1-light.1/bin/:$PATH -``` - -```bash -hhb --model-file bert_small_int32_input.onnx --input-name "input_ids;input_mask;segment_ids" --input-shape '1 384;1 384;1 384' --output-name "output_start_logits;output_end_logits" --board c920 --quantization-scheme "float16" --postprocess save_and_top5 -D --without-preprocess - -``` - -### **2.3. 选项说明** - -| 选项 | 说明 | -| ----------------------- | ------------------------ | -| `-D` | 生成可执行文件 | -| `--model-file` | 指定 ONNX BERT 模型 | -| `--input-name` | 模型输入名 | -| `--output-name` | 模型输出名 | -| `--input-shape` | 输入数据形状 | -| `--board` | 指定目标平台（TH1520） | -| `--quantization-scheme` | 量化方式（int8/float16） | -| `--postprocess` | 输出结果并打印 top5 | - ------- - -## **3. 生成的文件** - -HHB 运行后，在当前目录生成 `hhb_out/` 目录，其中包括： - -``` -hhb_out/ -├── hhb.bm # 量化后模型文件 -├── hhb_runtime # 可执行推理程序 -├── main.c # 参考示例入口 -├── model.c # 模型结构代码 -├── model.params # 量化后的权重数据 -├── io.c / io.h # 读写文件辅助代码 -├── process.c / process.h # 预处理函数 -``` - ------- - -## **4. 传输到开发板** - -将编译好的模型和文件拷贝到宿主机： - -```bash -docker cp 65f872394fa5837ef2c24ade731b152da074ac6091f0766c04ac54092ff32780:/home/example/c920/bert_ -small C:\Users\knifefire\Downloads\ -``` - -然后上传到开发板后，在开发板上： - -```bash -cd ~/bert_small -chmod +x hhb_out/hhb_runtime # 赋予执行权限 -``` - ------- - -## **5. 运行推理** - -```bash -python3 inference.py -``` - ------- - -## **6. 预期输出** - -BERT 处理 SQuAD 数据集的问题： - -本示例中的参考输入来自 SQuAD 数据集，SQuAD 是一个阅读理解数据集，由一组维基百科文章提出的问题组成，其中每个问题的答案都是来自相应阅读文章或问题的一段文本。 -本示例的输入如下，文章内容描述了一次橄榄球比赛的赛况，提出的问题是谁参加了比赛。 - -```bash -[Context]: Super Bowl 50 was an American football game... -[Question]: Which NFL team represented the AFC at Super Bowl 50? -``` - -**BERT 输出答案** - -根据阅读理解的结果，预期输出将是 Denver Broncos - -``` -[Answer]: Denver Broncos -``` - -**运行时间** - -``` -Run graph execution time: 1713.15491ms, FPS=0.58 -``` - -##### 参考输出： - -```bash -# python3 inference.py - ********** preprocess test ********** -[Context]: Super Bowl 50 was an American football game to determine the champion of the National Football League (N -FL) for the 2015 season. The American Football Conference (AFC) champion Denver Broncos defeated the National Footba -ll Conference (NFC) champion Carolina Panthers 24–10 to earn their third Super Bowl title. The game was played on Fe -bruary 7, 2016, at Levi's Stadium in the San Francisco Bay Area at Santa Clara, California. As this was the 50th Sup -er Bowl, the league emphasized the "golden anniversary" with various gold-themed initiatives, as well as temporarily - suspending the tradition of naming each Super Bowl game with Roman numerals (under which the game would have been k -nown as "Super Bowl L"), so that the logo could prominently feature the Arabic numerals 50. -[Question]: Which NFL team represented the AFC at Super Bowl 50? - ******* run bert ******* -Run graph execution time: 1713.15491ms, FPS=0.58 - -=== tensor info === -shape: 1 384 -data pointer: 0x183d60 - -=== tensor info === -shape: 1 384 -data pointer: 0x185380 - -=== tensor info === -shape: 1 384 -data pointer: 0x1869a0 - -=== tensor info === -shape: 1 384 -data pointer: 0x2a8610 -The max_value of output: 3.826172 -The min_value of output: -9.968750 -The mean_value of output: -8.412353 -The std_value of output: 5.128320 - ============ top5: =========== - 46: 3.826172 - 57: 3.142578 - 39: 1.303711 - 38: 1.179688 - 27: 0.624512 - -=== tensor info === -shape: 1 384 -data pointer: 0x2a8300 -The max_value of output: 3.617188 -The min_value of output: -9.625000 -The mean_value of output: -7.798176 -The std_value of output: 4.820137 - ============ top5: =========== - 47: 3.617188 - 58: 3.482422 - 32: 2.523438 - 29: 1.541992 - 41: 1.473633 - ********** postprocess ********** -[Answer]: Denver Broncos -``` - -这样，你就成功在 **Licheepi4A 开发板** 上运行了 **BERT 量化推理**！🚀 - -参考文档：https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/8_application.html \ No newline at end of file diff --git a/docs/typical-applications/mobilenetv2-image-classification.md b/docs/typical-applications/mobilenetv2-image-classification.md deleted file mode 100644 index ed4bcb1..0000000 --- a/docs/typical-applications/mobilenetv2-image-classification.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: LIcheepi 4A部署 mobilenetv2 模型完成图像分类的示例 -sidebar_position: 2 ---- - -# LIcheepi 4A部署 mobilenetv2 模型完成图像分类的示例 - -本文将介绍如何在Licheepi 4A上部署MobileNetV2模型进行图像分类任务。 - -## 前提条件 - -- Licheepi 4A硬件设备 -- RevyOS操作系统 -- 基本的机器学习知识 - -## 模型介绍 - -MobileNetV2是一个轻量级深度学习模型，专为移动和边缘设备设计，具有高效率和良好的性能表现。 - -本教程是一个如何在 LicheePi4A 平台上部署 mobilenetv2 模型完成图像分类的示例。 - -教程中包括了： - -- 使用 HHB 编译 onnx 模型为 LicheePi4A 上可用的二进制 -- 在 LicheePi4A 上使用 opencv c++ 版本做 mobilenetv2 模型的预处理 -- 在 LicheePi4A 上使用 CPU 和 NPU 的差异 - - - -### NPU环境配置 - -需要先安装 python 虚拟环境，再使用 pip3 安装 python 包。 -使用如下命令，安装 venv 包，用于创建python虚拟环境（以在 root 目录中创建 python 虚拟环境为例）： - -```bash -sudo apt install python3.11-venv -python3 -m venv venv -source venv/bin/activate -``` - -#### SHL 库安装 - -使用 pip 安装 - -```bash -pip3 install shl-python -``` - -安装后，使用 --whereis 查看安装位置 - -```bash -python3 -m shl --whereis th1520 -# 若使用纯 CPU 推理，则替换为 python3 -m shl --whereis c920 -``` - -根据打印的位置，将目录中的动态库复制到 /usr/lib 目录中，比如，打印的是： - -```bash -/home/sipeed/ort/lib/python3.11/site-packages/shl/install_nn2/th1520 -``` - -可以使用复制命令： - -```bash -sudo cp -r /home/sipeed/ort/lib/python3.11/site-packages/shl/install_nn2/th1520/lib/* /usr/lib/ -``` - -#### HHB-onnxruntime 安装 - -HHB-onnxuruntime 是移植了 SHL 后端（execution providers），让 onnxruntime 能复用到 SHL 中针对玄铁 CPU 的高性能优化代码。 - -CPU 版本 - -```bash -wget https://github.com/zhangwm-pt/onnxruntime/releases/download/riscv_whl_v2.6.0/hhb_onnxruntime_c920-2.6.0-cp311-cp311-linux_riscv64.whl -pip install hhb_onnxruntime_c920-2.6.0-cp311-cp311-linux_riscv64.whl -``` - -NPU 版本 - -```bash -wget https://github.com/zhangwm-pt/onnxruntime/releases/download/riscv_whl_v2.6.0/hhb_onnxruntime_th1520-2.6.0-cp311-cp311-linux_riscv64.whl -pip install hhb_onnxruntime_th1520-2.6.0-cp311-cp311-linux_riscv64.whl -``` - -#### **x86主机配置** - -安装好docker后，在docker应用中打开terminal输入： - -```bash -docker pull hhb4tools/hhb:2.4.5 -``` - -拉取镜像完毕后，使用下面的命令进入 Docker 镜像： - -```bash -docker run -itd --name=your.hhb2.4 -p 22 "hhb4tools/hhb:2.4.5" -docker exec -it your.hhb2.4 /bin/bash -``` - -进入 Docker 镜像后，可使用下面的命令确认 HHB 版本： - -```bash -hhb --version -``` - -进入 Docker 镜像中后，还需要配置交叉编译环境。注意必须要使用这这里的工具链，否则编译出的二进制文件无法在 LicheePi4A 上运行。 - -```bash -export PATH=/tools/Xuantie-900-gcc-linux-5.10.4-glibc-x86_64-V2.6.1-light.1/bin/:$PATH -``` - -![image-20250227142739955](https://raw.githubusercontent.com/jason-hue/plct/main/image-20250227142739955.png) - -至此，HHB 环境初步搭建完成。 - -### 部署MobilenetV2 - -进入docker中 - -首先获取本节教程的模型，下载到示例目录 `/home/example/th1520_npu/onnx_mobilenetv2_c++` 下： -[mobilenetv2-12.onnx](https://github.com/onnx/models/raw/main/validated/vision/classification/mobilenet/model/mobilenetv2-12.onnx) - -并获取本次教程所使用的优化版本 opencv 所需的库文件，前往 [github仓库下载](https://xuantie.t-head.cn/community/download?id=4112956065753141248)下载到上一级目录 `/home/example/th1520_npu/` 下。 - -```bash -cd /home/example/th1520_npu/ -git clone https://github.com/zhangwm-pt/prebuilt_opencv.git -``` - -#### 编译 - -**HHB 编译模型：** -将 ONNX 模型交叉编译成 NPU 上可执行的程序，需要使用 hhb 命令。注意，NPU 上仅支持8位或者16位定点运算，本示例中指定为 int8 非对称量化。编译时需要先进入到示例所在目录 `/home/example/th1520_npu/onnx_mobilenetv2_c++`： - -```bash -cd /home/example/th1520_npu/onnx_mobilenetv2_c++ -hhb -D --model-file mobilenetv2-12.onnx --data-scale 0.017 --data-mean "124 117 104" --board th1520 --postprocess save_and_top5 --input-name "input" --output-name "output" --input-shape "1 3 224 224" --calibrate-dataset persian_cat.jpg --quantization-scheme "int8_asym" -``` - -选项说明： - -- -D ：指定 HHB 流程执行到生成可执行文件的阶段为止 -- --model-file ：指定当前目录中已经下载好的 mobilenet 模型 -- --data-mean ：指定均值 -- --data-scale ：指定缩放值 -- --board ：指定目标平台为 th1520 -- --input-name： 模型的输入名 -- --output-name：模型的输出名 -- --input-shape：模型的输入大小 -- --postprocess：保存输出结果，并且打印 top5 结果 -- --calibrate-dataset：指定量化时所需的校准图片 -- --quantization-scheme：指定量化方式为 int8 非对称 - -命令执行完成后，会在当前目录生成 hhb_out 子目录，里面的包括了 hhb_runtime，model.c 等多个文件： - -- hhb.bm：HHB 的模型文件，包括了量化后的权重数据等信息 -- hhb_runtime：th1520 平台上的可执行文件，由目录中的c文件编译而成 -- main.c：临时文件，示例程序的参考入口 -- model.c：临时文件，模型结构文件，与模型结构相关 -- model.params：临时文件，权重数值 -- io.c：临时文件，读写文件的辅助函数 -- io.h：临时文件，读写文件的辅助函数声明 -- process.c：临时文件，图像预处理函数 -- process.h：临时文件，图像预处理函数声明 - -更详细的 HHB 选项说明可以参考 [HHB用户手册](https://www.yuque.com/za4k4z/oxlbxl/keyg70qggt5n3fpa)中的命令行选项说明。 - -**g++编译示例：** - -```bash -riscv64-unknown-linux-gnu-g++ main.cpp -I../prebuilt_opencv/include/opencv4 -L../prebuilt_opencv/lib -lopencv_imgproc -lopencv_imgcodecs -L../prebuilt_opencv/lib/opencv4/3rdparty/ -llibjpeg-turbo -llibwebp -llibpng -llibtiff -llibopenjp2 -lopencv_core -ldl -lpthread -lrt -lzlib -lcsi_cv -latomic -static -o mobilenetv2_example -``` - -编译命令正确执行完成后会在示例目录生成 mobilenetv2_example 文件。 - -#### 执行 - -交叉编译完成后，即可将程序执行所需的文件复制到开发板的目录中。 - -将docker中的文件夹传输到宿主机： - -```bash -docker cp 65f872394fa5837ef2c24ade731b152da074ac6091f0766c04ac54092ff32780:/home/example/th1520_npu/onnx_mobilenetv2_c++ C:\Users\knifefire\Downloads\ -``` - -然后上传到开发板即可。 - -先确认开发板中驱动是否加载： - -```shell -lsmod -``` - -若在输出中有 `img_mem`，`vha` 和 `vha_info` 这三个模块，NPU驱动即加载成功。 - -手动加载NPU驱动: - -```bash -sudo insmod /lib/modules/5.10.113-th1520/kernel/drivers/nna/img_mem/img_mem.ko - -sudo modprobe vha onchipmem_phys_start=0xffe0000000 onchipmem_size=0x100000 freq_khz=792000 - -sudo insmod /lib/modules/5.10.113-th1520/kernel/drivers/nna/vha/vha_info.ko - -sudo chmod a+rw /dev/vha0 -``` - -参考 [YOLOX章节](https://github.com/jason-hue/plct/blob/main/%E6%B5%8B%E8%AF%95%E6%96%87%E6%A1%A3/%E5%9C%A8%20LicheePi%204A%20%E4%B8%8A%E9%83%A8%E7%BD%B2%20YOLOX%20%E5%B9%B6%E4%BD%BF%E7%94%A8%20HHB-onnxruntime%20%E8%BF%9B%E8%A1%8C%E6%8E%A8%E7%90%86.md) 安装并配置好 python 虚拟环境 - -在开发板相应目录下运行刚刚编译好的示例： - -```bash -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/th1520/lib -./mobilenetv2_example -``` - -执行完成后，会在终端上提示执行到的各个阶段： - -1. 预处理 -2. 模型执行 -3. 后处理 - -mobilenetv2_example 执行会使用到的文件： - -- persian_cat.jpg：输入图片 -- input_img.bin：预处理阶段，根据输入图片生成的中间结果 -- hhb_out/hhb_runtime：模型执行阶段使用的文件，由x86主机上 HHB 生成 -- hhb_out/hhb.bm：模型执行阶段使用的文件，由x86主机上 HHB 生成 -- input_img.bin_output0_1_1000.txt：模型执行阶段的输出文件，包括了模型执行输出的 1000 个结果数值 - -#### 参考结果： - -```bash -(venv) sipeed@revyos-lpi4a:~/onnx_mobilenetv2_c++$ ./mobilenetv2_example - ********** preprocess image ********** - ********** run mobilenetv2 ********** -INFO: NNA clock:792000 [kHz] -INFO: Heap :ocm (0x18) -INFO: Heap :anonymous (0x2) -INFO: Heap :dmabuf (0x2) -INFO: Heap :unified (0x5) -FATAL: Importing 150528 bytes of CPU memory has failed (wrong memory alignment) -Run graph execution time: 15.03903ms, FPS=66.49 - -=== tensor info === -shape: 1 3 224 224 -data pointer: 0x2b4aca0 - -=== tensor info === -shape: 1 1000 -data pointer: 0x3fdd40b000 -The max_value of output: 16.053827 -The min_value of output: -8.026914 -The mean_value of output: -0.001889 -The std_value of output: 9.203342 - ============ top5: =========== -283: 16.053827 -281: 14.165141 -287: 11.709850 -285: 11.615416 -282: 11.332113 -free(): invalid pointer -Aborted - ********** postprocess result ********** - ********** probability top5: ********** -n02123394 Persian cat -n02123045 tabby, tabby cat -n02127052 lynx, catamount -n02124075 Egyptian cat -n02123159 tiger cat -``` - - - -### CPU - -将上述 NPU 步骤中的 HHB 编译命令替换为： - -```bash -hhb -D --model-file mobilenetv2-12.onnx --data-scale 0.017 --data-mean "124 117 104" --board c920 --postprocess save_and_top5 --input-name "input" --output-name "output" --input-shape "1 3 224 224" -``` - -g++ 编译后处理命令替换为： - -```bash -riscv64-unknown-linux-gnu-g++ main.cpp -I../prebuilt_opencv/include/opencv4 -L../prebuilt_opencv/lib -lopencv_imgproc -lopencv_imgcodecs -L../prebuilt_opencv/lib/opencv4/3rdparty/ -llibjpeg-turbo -llibwebp -llibpng -llibtiff -llibopenjp2 -lopencv_core -ldl -lpthread -lrt -lzlib -lcsi_cv -latomic -static -o mobilenetv2_example -``` - -再将编译的到的二进制文件发送到开发板上运行即可。参考结果如下： - -```bash -(ort) root@lpi4a:/home/sipeed/onnx_mobilenetv2_c++# ./mobilenetv2_example - ********** preprocess image ********** - ********** run mobilenetv2 ********** -Run graph execution time: 79.77252ms, FPS=12.54 - -=== tensor info === -shape: 1 3 224 224 -data pointer: 0x259240 - -=== tensor info === -shape: 1 1000 -data pointer: 0x1c5200 -The max_value of output: 16.843750 -The min_value of output: -7.414062 -The mean_value of output: 0.001131 -The std_value of output: 9.056762 - ============ top5: =========== -283: 16.843750 -281: 13.789062 -287: 12.257812 -282: 10.898438 -285: 10.765625 - ********** postprocess result ********** - ********** probability top5: ********** -n02123394 Persian cat -n02123045 tabby, tabby cat -n02127052 lynx, catamount -n02123159 tiger cat -n02124075 Egyptian cat -``` - - - -参考文档： - -https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/8_application.html#MobilenertV2 - -https://blog.csdn.net/weixin_44404482/article/details/134118924 \ No newline at end of file diff --git a/docs/typical-applications/yolox-deployment.md b/docs/typical-applications/yolox-deployment.md deleted file mode 100644 index ece28e6..0000000 --- a/docs/typical-applications/yolox-deployment.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: 在 LicheePi 4A 上部署 YOLOX 并使用 HHB-onnxruntime 进行推理 -sidebar_position: 5 ---- - -# 在 LicheePi 4A 上部署 YOLOX 并使用 HHB-onnxruntime 进行推理 - -本文详细介绍如何在 LicheePi 4A 上部署 YOLOX 目标检测模型，并使用 HHB-onnxruntime 进行高效推理。 - -## YOLOX简介 - -YOLOX 是一种高效的目标检测算法，在保持高精度的同时提供了出色的速度表现，非常适合边缘设备部署。 - -## 1. 环境准备 - -### 1.1 硬件准备 - -- LicheePi 4A（LPi4A）开发板 -- MicroSD 卡（用于存储系统） -- 电源适配器 -- USB 串口调试工具（可选） - -### 1.2 软件准备 - -- LicheePi 4A 官方 Linux 系统 -- Python 3.11 -- pip 及必备依赖项 -- ONNX 运行时（onnxruntime） -- HHB 工具（可用于模型转换） -- YOLOX 模型及其 ONNX 版本 - -```sh -# 更新系统 -sudo apt update && sudo apt upgrade -y -``` - -安装一些软件，用于示例中后续使用 - -```bash -sudo apt install wget git vim -``` - -安装 SHL 库 - -```bash -wget https://github.com/T-head-Semi/csi-nn2/releases/download/v2.4-beta.1/c920.tar.gz - -tar xf c920.tar.gz - -cp c920/lib/* /usr/lib/riscv64-linux-gnu/ -rf -``` - -**Python 环境配置** -LPi4A 烧录的系统中已默认安装 python 3.11 版本。可以使用如下命令确认 - -```bash -python3 --version -``` - -后续均以 python3.11 版本为例，其他版本在安装依赖时需要修改到对应版本的命令。 -各种 python 程序软件依赖的软件包大多可通过 pip 安装，可以使用如下命令安装 pip - -```bash -apt install python3-pip -``` - -安装其他python包之前，先安装 venv 包，用于创建python虚拟环境 - -```bash -apt install python3.11-venv -``` - -创建 python虚拟环境，并激活 - -```bash -cd /root -python3 -m venv ort -source /root/ort/bin/activate -``` - -至此，基本 python 环境已经创建完成，与其他体系结构类似，可以直接通过 pip install 安装纯 python 包。 - -##### 安装opencv - -```shell -sudo apt install python3 python3-pip -sudo apt install python3-opencv -sudo apt install libqt5gui5-gles -``` - -## 2. 获取并转换 YOLOX 模型 - -在 LPi4A 上执行以下步骤： - -```sh -# 克隆 YOLOX 仓库 -git clone https://github.com/Megvii-BaseDetection/YOLOX.git - -cd YOLOX/demo/ONNXRuntime - -wget https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.1rc0/yolox_s.onnx - -``` - -**修改源码** - -本教程将使用 HHB-onnxruntime 执行模型，因此切换到。在源码中的 onnxruntime 示例目录，修改文件 demo/ONNXRuntime/onnx_inference.py 的开头新增两行代码 - -```bash -#!/usr/bin/env python3 -# Copyright (c) Megvii, Inc. and its affiliates. - -+import sys -+sys.path.insert(0, "../../") - -import argparse -import os -``` - -代码中使用 sys.path.insert 指定搜索路径，以此免去从源码中安装 YOLOX 的安装包的操作。 - -**安装依赖包** - -RISC-V 体系结构的 python 生态还有欠缺，未来完善之后，YOLOX 中依赖的包可以通过 [requirements.txt](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/requirements.txt) 文件直接安装。 -本教程中的 YOLOX 示例依赖了较多的 python 包，下载预编译好的 python 包 - -```bash -git clone -b python3.11 https://github.com/zhangwm-pt/prebuilt_whl.git -cd prebuilt_whl -``` - -可以按照以下顺序，手工处理。 - -```bash -pip install numpy-1.25.0-cp311-cp311-linux_riscv64.whl - -pip install opencv_python-4.5.4+4cd224d-cp311-cp311-linux_riscv64.whl - -pip install kiwisolver-1.4.4-cp311-cp311-linux_riscv64.whl - -pip install Pillow-9.5.0-cp311-cp311-linux_riscv64.whl - -pip install matplotlib-3.7.2.dev0+gb3bd929cf0.d20230630-cp311-cp311-linux_riscv64.whl - -pip install pycocotools-2.0.6-cp311-cp311-linux_riscv64.whl - -pip3 install loguru-0.7.0-py3-none-any.whl - -pip3 install torch-2.0.0a0+gitc263bd4-cp311-cp311-linux_riscv64.whl - -pip3 install MarkupSafe-2.1.3-cp311-cp311-linux_riscv64.whl - -pip3 install torchvision-0.15.1a0-cp311-cp311-linux_riscv64.whl - -pip3 install psutil-5.9.5-cp311-abi3-linux_riscv64.whl - -pip3 install tqdm-4.65.0-py3-none-any.whl - -pip3 install tabulate-0.9.0-py3-none-any.whl -``` - -安装过程中会涉及到其他纯 python 依赖包，pip 会自动从官方源下载。 - -**安装 HHB-onnxruntime** - -HHB-onnxuruntime 是移植了 SHL 后端（execution providers），让 onnxruntime 能复用到 SHL 中针对玄铁 CPU 的高性能优化代码。 - -```bash -wget https://github.com/zhangwm-pt/onnxruntime/releases/download/riscv_whl/onnxruntime-1.14.1-cp311-cp311-linux_riscv64.whl -pip install onnxruntime-1.14.1-cp311-cp311-linux_riscv64.whl -``` - -**执行** - -在示例目录中执行 onnx_inference.py 示例 - -```bash -export PYTHONPATH=$PYTHONPATH:/root/YOLOX - -python3 onnx_inference.py -m yolox_s.onnx -i soccer.png -o outdir -s 0.3 --input_shape 640,640 -``` - -参数说明： - -- -m：指定模型 -- -i：指定图片 -- -o：指定输出目录 -- -s：指定检测的阈值 -- --input_shape：指定检测时使用的图片尺寸 - -**参考结果** - -本教程中输入如下图，是运动员踢足球的图片，预期的检测结果是检测到两个人和一个足球。 - -> 图片来源于网络 - -![yolox_detection_soccer_input.jpg](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/assets/application/yolox_detection_soccer_input.jpg) - -示例正常执行后，会在 outdir 目录下生成结果图片 soccer.png。图片中会用框画出检测到的目标，并标注概率，效果如下图： - -![yolox_detection_soccer_output.jpg](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/assets/application/yolox_detection_soccer_output.jpg) - -参考文档： - -https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/8_application.html \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/Installation/intro.mdx b/i18n/en/docusaurus-plugin-content-docs/current/Installation/intro.mdx index 17ca02c..499d7a8 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/Installation/intro.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/Installation/intro.mdx @@ -2,23 +2,35 @@ sidebar_position: 1 --- -# Installation Instructions Overview +# Image Flashing Notes -RevyOS currently supports multiple devices. The table below provides the status of installation guides for each supported device. Please click the relevant link as needed. Some guides are still in progress and will be completed in the future. +RevyOS currently supports multiple devices. The table below summarises which flashing guides are available for each device; follow the link that matches your needs. Some guides are still being compiled and will be added later. -## Installation Guide Availability +:::warning +**If you are upgrading from an image dated `20240720` or earlier, you must reset the U-Boot environment variables.** + +To reset: +Connect to the board via the serial console, power it on, press Enter when U-Boot starts to interrupt the boot sequence, and run the following commands at the U-Boot prompt: + +```bash +env default -a -f; env save; reset +``` + +This resets all U-Boot environment variables and reboots the board. +::: + +## Flashing Guide Availability import { DownloadLink } from "@site/src/components/ImageLinks"; import { RedirectBasedOnUA } from "@site/src/components/RedirectBasedOnUA"; -| Supported Device | Image Download (Latest Version) | Installation Guide | -| ------------------ | ---------------------------------------------------- | ---------------------------------------------- | -| Lichee Pi 4A | {} | { } | -| Milk-V Meles | {} | [Official Milk-V Installation Guide](https://milkv.io/docs/meles/installation) | -| Milk-V Pioneer | {} | [Installation Guide](../milkv-pioneer/) | -| Lichee Cluster 4A | {} | In Progress | -| Lichee Console 4A | {} | In Progress | -| Lichee Book 4A | {} | In Progress | -| Beagle-Ahead | {} | In Progress | -| Huiwei book | {} | In Progress | - +| Supported Device | Image Download (Latest Version) | Flashing Guide | +| ------------------ | ------------------------------- | -------------- | +| Lichee Pi 4A | {} | { } | +| Milk-V Meles | {} | [Milk-V official flashing guide](https://milkv.io/zh/docs/meles/installation) | +| Milk-V Pioneer | {} | [Flashing Guide](../milkv-pioneer/) | +| Lichee Cluster 4A | {} | In progress | +| Lichee Console 4A | {} | In progress | +| Lichee Book 4A | {} | In progress | +| Beagle-Ahead | {} | In progress | +| Huiwei book | {} | In progress | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/Installation/licheepi4a-windows.mdx b/i18n/en/docusaurus-plugin-content-docs/current/Installation/licheepi4a-windows.mdx index b6a18d5..2f222f4 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/Installation/licheepi4a-windows.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/Installation/licheepi4a-windows.mdx @@ -4,259 +4,343 @@ sidebar_position: 4 import { DownloadLink } from "@site/src/components/ImageLinks"; -# Installing RevyOS on the LicheePi 4A (Windows) +# Lichee Pi 4A Image Flashing Guide (Windows) -This page provides a tutorial for flashing the LicheePi 4A image on Windows. -If you want to flash the image on a Linux, or view other image flashing tutorials, please view the links in the table below. +This document describes how to flash Lichee Pi 4A images on Windows. +For the Linux workflow or other device guides, use the links below. -| Other Flashing Tutorial | Link | -| ----------------- | -------------- | -| LicheePi4A (Installing using Linux)| [Installation guilde for Linux](../licheepi4a/) | -| Milk-V Pioneer | [Flashing Tutorial](./milkv-pioneer.mdx) | +| Other Flashing Tutorials | Link | +| -------------------------------- | ---- | +| Lichee Pi 4A (Linux) | [Linux flashing guide](../licheepi4a/) | +| Milk-V Pioneer | [Flashing guide](../milkv-pioneer/) | +| Milk-V Meles | [Flashing guide](../milkv-meles/) | -## Attention! +:::warning +Before following the instructions, **compare your board with the reference image below**. Proceed only after confirming that the hardware matches. -Before following this tutorial, please compare your board with the image below to ensure it matches. Only proceed with the tutorial after confirming the match. - -![LicheePi4A Example Image](/img/image-for-flash/lpi4a.png) +![Lichee Pi 4A reference](/img/image-for-flash/lpi4a.png) +::: ## Demonstration Environment -All image flashing operations in this tutorial use the following environment: +All steps in this tutorial were validated in the following environment: -- Operating System: Windows 11 24H2 OS Build 26100.3194 +- Operating system: Windows 11 24H2 (OS build 26100.3194) - Architecture: x86_64 -- LicheePi4A Board Specifications: 16G RAM + 128G eMMC +- Lichee Pi 4A configuration: 16 GB RAM + 128 GB eMMC + +:::note +Every procedure documented here is reproducible in this environment. If you encounter any issues during flashing, please refer to [issue submission](../../issue/). +::: -All operations in this tutorial are reproducible in this environment. If you encounter any issues while flashing the image in this environment, please refer to [this page](../issue.md) to submit an issue. +## Boot Options -## Boot Methods Introduction +Lichee Pi 4A supports two boot modes: [boot from an SD card](#boot-from-sd-card) and [boot from eMMC](#boot-from-emmc). Select the mode that fits your scenario. -LicheePi4A currently supports two boot methods: [Booting from SD card](#booting-from-sd-card) and [Booting from eMMC](#booting-from-emmc). This tutorial provides instructions for both methods. Please click to jump to the section that matches your desired flashing method. +:::warning +Flashing an image erases all existing data. **Back up important information before you start.** +::: -Please note that regardless of the flashing method used, existing user data will be lost. Make sure to back up your data before proceeding with the flashing process! +## Boot from SD Card -## Booting from SD card +:::warning +**DIP switch reminder** -Note: Booting from an SD card does not require changing the DIP switch! Set the DIP switch to eMMC boot! +Booting from SD card does not require changing the DIP switch; keep it in the eMMC position. -![DIP Switch Example](/img/image-for-flash/Switch.png) +![DIP switch reference](/img/image-for-flash/Switch.png) -The DIP switch is located on the bottom of the carrier board and can only be seen after removing the LM4A SoM. The correct setting should be `BOOT_SEL[1:0]=0 0`, i.e. `SW1=SW2=off`. +The DIP switch is located on the underside of the board and becomes visible after removing the core board. Both toggles should point downward. -**Note!** Some early versions of LicheePi4A boards do not have a DIP switch. +**Note:** Early revisions of the Lichee Pi 4A board may not include a DIP switch. +::: -Additionally, SD cards may have compatibility issues. Please check the [LicheePi 4A SD Card Compatibility List](../../miscellaneous/lpi4a-sdcard-list/) to see if your SD card has any known compatibility issues. +:::warning +**SD card compatibility** + +Some SD cards may not work reliably. Check the [Lichee Pi 4A SD card compatibility list](../../miscellaneous/lpi4a-sdcard-list/) to confirm whether your card has known issues. +::: ### Preparation -#### Obtaining the SD card image +:::warning +**Upgrading from images dated `20240720` or earlier requires resetting the U-Boot environment variables.** -Download the LicheePi4A SD card boot system image with the prefix `sdcard-` from the following links: +Reset procedure: +Connect to the board over the serial console, power it on, interrupt U-Boot by pressing Enter, and run: -- [RevyOS20240720 (5.10 kernel)](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20240720/) +```bash +env default -a -f; env save; reset +``` -- [RevyOS20250123 (6.6 kernel)](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250123/) +This restores all U-Boot environment variables and reboots the board. +::: -- Latest version: {} +#### Obtain the SD Card Image -The 20240720 image uses the 5.10 kernel, which is currently in a more mature state and performs more stably in video encoding/decoding and various applications. +Download the Lichee Pi 4A system image that starts with `sdcard-` from the following locations: -The 20250123 image uses the 6.6 kernel, which may have some unknown issues. Known issues include video stuttering and USB power loss, which are currently being fixed. +- [RevyOS 20240720 (Kernel 5.10)](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20240720/) +- Latest release (Kernel 6.6): {} -Please choose the appropriate image based on your needs after reading the above information. +:::note +**About kernel versions** -Using the 20250123 image as an example: +The 20240720 image uses Kernel 5.10, which is stable for multimedia and general workloads. -There are two ways to download the image: +The latest image uses Kernel 6.6. It may still contain unresolved issues—video stutter and USB power loss have been observed and are being fixed. +::: -- Through a web browser. Simply click the link to download. +The example below uses the 20250123 image. -![Download image through web](/img/image-for-flash/web-download-windows-en.png) +Two download methods are available: -- Through command line. Open PowerShell and run the following command: +- **Browser download:** click the link to start downloading. + +![Browser download](/img/image-for-flash/web-download-windows.png) + +- **Command-line download:** open PowerShell and run: ```powershell curl.exe -OL https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250123/sdcard-lpi4a-20250123_195216.img.zst ``` -> **Note**: `curl.exe` is [shipped in Windows as a default component since Windows 10](https://curl.se/windows/microsoft.html). If `curl.exe` isn't working, use web browser. +:::note +`curl.exe` [has shipped with Windows since Windows 10](https://curl.se/windows/microsoft.html). If it is unavailable, use the browser download method instead. +::: -Wait for the progress to reach 100% to complete the download. +Wait until the progress reaches 100%; the download then completes. -![Download image through command line](/img/image-for-flash/download-image-command-line-windows.png) +![Command-line download](/img/image-for-flash/download-image-command-line-windows.png) -Both methods will result in a compressed image file named `sdcard-lpi4a-20250123_195216.img.zst`. Due to the possibility of transmission errors during download, it is recommended to perform a hash verification step to verify the accuracy of the image. +Regardless of the method, the result is the compressed archive `sdcard-lpi4a-20250123_195216.img.zst`. Because transmission errors can occur, verifying the download with a checksum is recommended. -#### Image Verification (Optional, Recommended) +#### Verify the Image (Optional but Recommended) -Open File Explorer, navigate to the folder containing the image file, right-click and select "Open in terminal" +Open File Explorer, navigate to the folder containing the image, right-click, and choose **Open in Terminal**. -![Select "Open in terminal" from the context menu](/img/image-for-flash/context_menu_terminal_open_windows-en.png) +![Open in Terminal](/img/image-for-flash/context_menu_terminal_open_windows.png) -Click to open the PowerShell terminal. Enter the following command to get the `md5sum.txt` checksum from the mirror site: +In the PowerShell window, fetch the reference checksums from the mirror: ```powershell curl.exe -L https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250123/md5sum.txt ``` -This should display the checksums for various image files. Run the following command to calculate the local image checksum: +Then compute the checksum for the local file: ```powershell Get-FileHash -Algorithm MD5 .\sdcard-lpi4a-20250123_195216.img.zst ``` -![Verify image file checksum](/img/image-for-flash/checksum-verification-image.png) +![Checksum verification](/img/image-for-flash/checksum-verification-image.png) + +Compare the two values. If they differ, re-download the image. -Compare the two checksums, they should match. If not, you need to re-download the image. +#### Extract the Image -#### Extracting the Image +The image is compressed with `zstd`. Use an archive tool that supports `.zst`, such as [PeaZip](https://peazip.github.io/) or [7-Zip (Zstd build)](https://github.com/mcmilk/7-Zip-zstd). -The image is compressed with `zstd`, you can use compression tools like [PeaZip](https://peazip.github.io/) or [7-zip Zstd version](https://github.com/mcmilk/7-Zip-zstd) to extract it. +![Extract with PeaZip](/img/image-for-flash/peazip_extraction_illustration.png) -**Note**: After extraction, the image itself and the compressed file will occupy about **10.2GB** of space, please ensure you have enough space! +:::warning +**Extraction size reminder** + +The extracted file is about **10.2 GB**. Ensure sufficient disk space before unpacking. +::: #### Hardware Preparation -Prepare a MicroSD card reader and a MicroSD card. There are currently compatibility issues with MicroSD cards. RevyOS provides a [list of tested MicroSD cards](https://github.com/revyos/revyos/blob/main/Installation/card%20list.md). +Prepare a MicroSD card reader and a MicroSD card. Because of compatibility concerns, consult the [tested card list](https://github.com/revyos/revyos/blob/main/Installation/card%20list.md). + +:::note +If your card is not on the list and you experience flashing or boot failures, submit an issue via [this page](../../issue/) and consider using the [eMMC flashing method](#boot-from-emmc) instead. +::: -If your MicroSD card is not on the known working list and you encounter issues with flashing the image or booting after flashing, please refer to [this page](../issue.md) to submit an issue, and try following the [Booting from eMMC](#booting-from-emmc) image flashing tutorial. +#### Write the Image with BalenaEtcher -#### Using BalenaEtcher to Write the Image to MicroSD Card +Download BalenaEtcher from [https://etcher.balena.io/](https://etcher.balena.io/). Select [Etcher for Windows](https://github.com/balena-io/etcher/releases/download/v1.19.25/balenaEtcher-1.19.25.Setup.exe) and install it. -Download the flashing tool BalenaEtcher from the official website [https://etcher.balena.io/](https://etcher.balena.io/). When downloading, please choose the file according to your machine's specifications. Choose [Etcher for Windows](https://github.com/balena-io/etcher/releases/download/v1.19.25/balenaEtcher-1.19.25.Setup.exe) to download and install. +![BalenaEtcher version selection](/img/image-for-flash/balenaetcher-version-selection.png) -![BalenaEtcher Version Selection](/img/image-for-flash/balenaetcher-version-selection.png) +1. Insert the SD card into the reader and connect it to the PC. +2. Launch BalenaEtcher. +3. Click **Flash from file** and choose the image. +4. Select the target device. +5. Click **Flash** to start writing. +6. Wait for the success message. -1. Insert the SD card into the card reader and plug it into your computer. -2. Run BalenaEtcher to write the image to the SD card. -3. In the BalenaEtcher window, first click "Flash from file" to select the image file. -4. After selecting the image file, choose the device to write to in the second column. -5. After selecting both items, click "Flash" to write the image. -6. After waiting for a while, it will show that the flashing is complete. +![BalenaEtcher flashing flow](/img/image-for-flash/balenaetcher-flashing-guide.png) -![BalenaEtcher Flashing Process](/img/image-for-flash/balenaetcher-flashing-guide-en.png) +:::warning +**Safe removal reminder** -### Booting the System from SD Card +Before removing the SD card, ensure BalenaEtcher reports completion, the SD card LED has stopped blinking, and eject the card via the system tray. Otherwise, the card or data may be corrupted. +::: -After writing the image, insert the SD card into the slot shown in the image. +### Boot the System via SD Card + +After flashing, insert the SD card into the slot shown below. ![](/img/image-for-flash/lpi4a5.png) -First connect the HDMI cable (if you need an external display), then connect the USB-C end of the USB-A to USB-C data cable (included in the box) to the development board, and the other end to a USB power supply with at least 5V2A output to start. +Connect an HDMI cable if a monitor is required. Use the supplied USB-A-to-USB-C cable: plug the USB-C end into the board and the USB-A end into a power source that can supply at least 5 V / 2 A to power on the system. -## Booting from eMMC +## Boot from eMMC -When booting the image from eMMC, there are two ways to flash the image: with or without connecting to a serial port. Considering that connecting to a serial port is not necessary, the default method is flashing without connecting to a serial port. If you have a serial cable, you can also choose to refer to the section on flashing with a serial connection. There are some differences in the operations involved. If you want to flash with a serial cable connected, please refer to the relevant section in the [Linux Flashing Tutorial](./licheepi4a.mdx). +You can flash the eMMC image with or without a serial cable. Because a serial cable is optional, the default workflow below assumes no serial connection. If you plan to use a serial console, refer to the relevant sections in the [Linux flashing guide](./licheepi4a.mdx). -**Please note**: Remove the SD Card before booting from eMMC! +:::warning +Remove the SD card before booting from eMMC. +::: ### Preparation -#### Installing the Image Flashing Tool +:::warning +**Upgrading from images dated `20240720` or earlier requires resetting the U-Boot environment variables.** + +Reset procedure: +Connect to the board via serial, power it on, interrupt U-Boot, and run: + +```bash +env default -a -f; env save; reset +``` + +This restores all U-Boot environment variables and reboots the board. +::: -Booting from eMMC requires flashing u-boot files, boot files, and root files into eMMC using the fastboot tool, so you need to first confirm whether fastboot is installed. +#### Install the Flashing Tools -You can use an indexing tool like Everything to search for `fastboot.exe` on your computer. If you don't have it, please download the [Android SDK Platform Tools](https://developer.android.google.cn/tools/releases/platform-tools?hl=zh-cn#downloads) and extract it to an appropriate location. +Flashing eMMC requires writing the `u-boot`, `boot`, and `root` images with `fastboot`. Determine whether `fastboot.exe` is installed. If it is missing or older than version 34, install the latest Platform Tools: -Open PowerShell in the folder containing `fastboot.exe`, run `.\fastboot.exe --version` to determine if `fastboot.exe` can run normally. +```powershell +winget install google.platformtools +``` + +(Older `fastboot` releases fail when flashing recent images.) + +Open PowerShell in the folder containing `fastboot.exe` and verify it runs: + +```powershell +.\fastboot.exe --version +``` -![Fastboot Tool Detection](/img/image-for-flash/fastboot_tool_detection.png) +![Fastboot tool detection](/img/image-for-flash/fastboot_tool_detection.png) -If it can display the version number normally as shown above, it proves the installation was successful. +A version string indicates that `fastboot` is ready. -#### Obtaining the Image +#### Obtain the Images -Download the LicheePi4A system image through the above links. +Download the Lichee Pi 4A system images from: -**Note**: The uboot files for different memory versions of LicheePi4A are not interchangeable. Please choose the corresponding image according to your LiChee Pi4A SoM version. +- [RevyOS 20240720 (Kernel 5.10)](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20240720/) +- Latest release (Kernel 6.6): {} -|Memory Storage Combination|Corresponding uboot Image| -|---|---| -|8G RAM + 8G eMMC|u-boot-with-spl-lpi4a-main_8gemmc.bin| -|8G RAM + 32G eMMC|u-boot-with-spl-lpi4a-main.bin| -|16G RAM|u-boot-with-spl-lpi4a-16g-main.bin| +:::note +**About kernel versions** -If you can't confirm the specifications of the Lichee Pi4A SoM, you can scan the QR code on the SoM to check. When LicheePi4A boards are sold, there will be a QR code sticker on both the SoM and the motherboard. After scanning the QR code sticker on the SoM/motherboard, it will display the memory and storage configuration of the SoM. +The 20240720 image (Kernel 5.10) is stable for multimedia workloads. -For example, on a 16G RAM + 128G SoM, the sticker is in the part shown in the image +The latest image (Kernel 6.6) may still expose issues such as video stutter or USB power loss; fixes are underway. +::: + +:::warning +**Selecting the correct U-Boot image** + +Different memory configurations require different U-Boot binaries. Match your core board to the table below: + +| Memory and storage | U-Boot image | +| --- | --- | +| 8 GB RAM + 8 GB eMMC | u-boot-with-spl-lpi4a-main_8gemmc.bin | +| 8 GB RAM + 32 GB eMMC | u-boot-with-spl-lpi4a-main.bin | +| 16 GB RAM | u-boot-with-spl-lpi4a-16g-main.bin | + +If you cannot confirm the configuration, scan the QR code sticker on the core board. Each shipped board includes stickers on both the core and base boards. Scanning the core board sticker reveals the RAM and storage combination. + +Example for a 16 GB RAM + 128 GB eMMC board: ![core-card](/img/image-for-flash/core-card.png) -The display after scanning the QR code is as follows +The scanned result looks like this: ![Core board-info](/img/image-for-flash/card-info.png) -In the result after scanning, the second part of the number is the memory + storage configuration of the SoM. +The second line specifies the RAM plus storage configuration. +::: + +After identifying the correct build, download, verify, and extract the `uboot`, `boot`, and `root` images (the U-Boot binary does not require extraction) as described in the SD card section. -After confirming the board specifications, download, verify, and extract the corresponding uboot, boot, and root files (the uboot file does not need to be extracted). This part can refer to the "Booting from SD Card" section above. +![Downloaded images](/img/image-for-flash/downloaded_image.png) -![Downloaded image files](/img/image-for-flash/downloaded_image.png) +#### Connect the Board and Install Drivers -#### Connecting the Board and Installing the Driver +Press and hold the BOOT button, then connect the Type-C port nearest the BOOT button to the PC. The board enters flashing mode. -While holding down the BOOT button on the board, connect the Type-C port near the BOOT button to the computer. The board will enter flashing mode. +Open **Device Manager**. If you see `USB download gadget` under **Other devices**, the device is detected but lacks a driver. -Right-click on the Windows logo, open Device Manager. If you see "USB download gadget" under "Other devices", it means the device has been correctly recognized. However, the driver is not installed. +Download the [Google USB Driver](https://dl.google.com/android/repository/usb_driver_r13-windows.zip) (a proxy may be required), extract it, and install it: -To install the fastboot driver, you need to download the [Google USB Driver (proxy required)](https://dl.google.com/android/repository/usb_driver_r13-windows.zip), download and extract it to a location. +1. Right-click `USB download gadget` and choose **Update driver**. +2. Select **Browse my computer for drivers**. +![Driver update step 2](/img/image-for-flash/driver-update-step2.png) +3. Choose **Let me pick from a list of available drivers on my computer**. +4. Select **Show All Devices**, then click **Next**. +![Driver update step 4](/img/image-for-flash/driver-update-step-4.png) +5. Click **Have Disk**. +6. Click **Browse**, select the `.inf` file inside the Google USB Driver folder, and confirm. +![Driver update step 6](/img/image-for-flash/driver-update-step-6.png) +7. Choose **Android Bootloader Interface**, click **Next**, approve the prompts, and select **Install** when Windows Security asks for confirmation. +![Driver update step 7](/img/image-for-flash/driver-update-step7.png) +8. The fastboot driver finishes installing. +![Driver update step 8](/img/image-for-flash/driver_update_step8.png) -1. Right-click on "USB download gadget" in Device Manager, click "Update driver" -2. Choose "Browse my computer for drivers" -![Driver Update Step 2](/img/image-for-flash/driver-update-step2-en.png) -3. Select "Let me pick from a list of available drivers on my computer" -4. Select "Show All Devices" and click "Next" -![Driver Update Step 4](/img/image-for-flash/driver-update-step-4-en.png) -5. Click "Have Disk" -6. Click "Browse", select the inf file under the Google USB Driver, click OK -![Driver Update Step 6](/img/image-for-flash/driver-update-step-6-en.png) -7. Select "Android Bootloader Interface", click "Next", click "Yes" in the pop-up dialog, click "Install" in the Windows Security Center dialog that pops up -![Driver Update Step 7](/img/image-for-flash/driver-update-step7-en.png) -8. Successfully installed the fastboot driver -![Driver Update Step 8](/img/image-for-flash/driver_update_step8-en.png) +If installation fails, uninstall the device from Device Manager, reconnect the board, and repeat the steps. -If there are problems with the above steps, please go back to Device Manager, find the device, click "Uninstall driver", then unplug and replug the development board and try again. +### Flash the Images -Return to the PowerShell terminal containing `fastboot.exe`, enter the following command, the program should output one line of information indicating that one device is connected. +Back in the PowerShell window that contains `fastboot.exe`, verify the device connection: ```powershell .\fastboot.exe devices ``` -![Fastboot Device Detection](/img/image-for-flash/fastboot_device_detection.png) +![Fastboot device detection](/img/image-for-flash/fastboot_device_detection.png) + +Flash a temporary U-Boot to RAM and reboot: ```powershell -.\fastboot.exe flash ram .\u-boot-with-spl-lpi4a-16g.bin # Replace with the path to the uboot file corresponding to your board specifications, you can drag and drop the file in File Explorer to the terminal to quickly input the file path -.\fastboot reboot +.\fastboot.exe flash ram .\u-boot-with-spl-lpi4a-16g.bin # Replace with the path to the U-Boot image for your configuration +.\fastboot.exe reboot ``` -![Flash uboot into memory](/img/image-for-flash/uboot_memory_flash.png) +![Flash U-Boot to RAM](/img/image-for-flash/uboot_memory_flash.png) -Then proceed with flashing the image files +After the board restarts, Windows may again report an unknown `USB download gadget`. Install the driver once more if needed. -**Note**: After the development board restarts, the computer may again detect an unknown device named "USB download gadget". Please follow the driver installation tutorial above to reinstall the driver for this device before continuing with the steps below. +Then flash the persistent images (drag-and-drop files into PowerShell to insert their paths quickly): ```powershell -# Replace the following three lines with the paths to the uboot, boot, root files corresponding to your board specifications, you can drag and drop the files in File Explorer to the terminal to quickly input the file paths .\fastboot.exe flash uboot u-boot-with-spl-lpi4a-16g.bin .\fastboot.exe flash boot boot-lpi4a-20240720_171951.ext4 .\fastboot.exe flash root root-lpi4a-20240720_171951.ext4 ``` -![Fastboot System Installation Guide](/img/image-for-flash/fastboot_installation_guide.png) +![Fastboot flashing](/img/image-for-flash/fastboot_installation_guide.png) -The uboot file and boot file flash quickly, while the root file takes about 5 minutes to complete. If when flashing the root file, it's not 30+ data blocks but 2000+ or 3000+(shown below), it indicates that the previous flashing operation was incorrect. In this case, the image will not boot after writing is complete. Please perform the flashing operation again. +:::warning +**Progress and timing note** -![](/img/image-for-flash/bad-fastboot-flash.png) +Flashing `uboot` and `boot` completes quickly. Writing `root` takes roughly five minutes. If `fastboot` shows an unusually small number of data blocks (e.g. only a few thousand), the earlier steps likely failed—repeat the flashing procedure. -At this point, the image flashing is complete, and you can start the system by unplugging and plugging in the power cord. +![Incorrect fastboot flashing](/img/image-for-flash/bad-fastboot-flash.png) +::: -### User Login +Once flashing finishes, power-cycle the board to boot from eMMC. -Below are the default system account and password +## User Credentials -- Login account: debian -- Account password: debian +Default login credentials: -You can use the above user password to log in when first booting the image. +- Username: `debian` +- Password: `debian` -**For security reasons, please be sure to change the password after the first login to avoid problems.** +Use these for the first boot and change the password immediately for security. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/Installation/licheepi4a.mdx b/i18n/en/docusaurus-plugin-content-docs/current/Installation/licheepi4a.mdx index 4d3e9a3..7cf95e9 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/Installation/licheepi4a.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/Installation/licheepi4a.mdx @@ -3,191 +3,248 @@ sidebar_position: 2 --- import { DownloadLink } from "@site/src/components/ImageLinks"; -import LocaleImage from "@site/src/components/LocaleImage"; +# Lichee Pi 4A Image Flashing Guide (Linux) -# Installing RevyOS on the LicheePi 4A +This page provides the Linux workflow for flashing the Lichee Pi 4A images. +If you need the Windows procedure or flashing guides for other devices, use the links in the table below. -This page provides a tutorial for flashing the LicheePi 4A image on Linux. -If you want to flash the image on a Windows, or view other image flashing tutorials, please view the links in the table below. +| Other Flashing Tutorials | Link | +| ----------------------- | ---- | +| Lichee Pi 4A (Windows) | [Windows flashing guide](../licheepi4a-windows/) | +| Milk-V Pioneer | [Flashing guide](../milkv-pioneer/) | +| Milk-V Meles | [Flashing guide](../milkv-meles/) | -| Other Flashing Tutorial | Link | -| ----------------- | -------------- | -| LicheePi4A (Installing using Windows)| [Installation guilde for Windows](../licheepi4a-windows/) | -| Milk-V Pioneer | [Flashing Tutorial](./milkv-pioneer.mdx) | +:::warning +Before you begin, **compare your board with the image below and confirm they match**. Proceed only after verifying the hardware. -## Important! - -Before proceeding, compare your board with the image below to ensure they match. Continue only if the boards are identical. - -![LicheePi4A Example](/img/image-for-flash/lpi4a.png) +![LicheePi4A reference](/img/image-for-flash/lpi4a.png) +::: ## Demonstration Environment -All installation operations in this tutorial are demonstrated using the following environment: +All operations in this tutorial were performed under the following environment: -- **System and Version**: Ubuntu 22.04.5 LTS -- **Architecture**: x86_64 -- **LicheePi4A Specs**: 16GB RAM + 128GB eMMC +- Operating system: Ubuntu 22.04.5 LTS +- Architecture: x86_64 +- Lichee Pi 4A configuration: 16 GB RAM + 128 GB eMMC -For unofficial environments that might be used, refer to [this page](../../issue/) for submitting issues. +:::note +Every step described here is reproducible in the environment above. If you encounter issues during flashing, please refer to [issue submission](../../issue/). +::: -## Boot Methods Overview +## Tooling -LicheePi4A supports two boot methods: [SD Card Boot](#sd-card-boot) and [eMMC Boot](#booting-from-emmc). Follow the relevant section based on your needs. +This section covers the software required for downloading and flashing images. Install the tools first before proceeding with the flashing workflow. -## SD Card Boot +### File Download Utility -**Attention!** No need to change the DIP switch to boot from the SD card! Set the DIP switch as per the eMMC configuration. +In a graphical environment you can download images directly through a browser. To download from the command line, tools such as `wget` or `curl` are available; this guide uses `wget`. -![Example of DIP switch](/img/image-for-flash/Switch.png) +In the [demonstration environment](#demonstration-environment), `wget` is typically pre-installed. Run the following command to check its version: -The DIP switch is located on the underside of the board. You need to remove the board to access it. The correct configuration is with both switches set to the downward position. +```bash +wget --version +``` -**Note!** Some early versions of the LicheePi4A board do not have a DIP switch. +If `wget` is not installed, install it with: -Additionally, SD cards may have compatibility issues. Please check the [LicheePi 4A SD Card Compatibility List](../../miscellaneous/lpi4a-sdcard-list/) to see if your SD card has any known compatibility issues. +```bash +sudo apt install wget +``` +![wget-install](/img/image-for-flash/wget-install.png) -### Preparation +> Executing commands with `sudo` prompts for your password. Ensure you know the password before running the command; this will not be repeated later in the document. -#### Obtain SD card images +### Archive Extraction Utility -Download the LicheePi4A SD card boot system image with the `sdcard-` prefix from the following links: +The `.zst` archives can be extracted using tools such as `zstd`, `tar`, or `7z`. This tutorial demonstrates extraction with the `zstd` command-line tool. Install the `zstd` package first, then extract the image. -- [RevyOS20240720 (Kernel version 5.10)](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20240720/) +To check whether `zstd` is already installed, run: -- [RevyOS20250110 (Kernel version 6.6)](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250110/) +```bash +zstd --version +``` -The 20240720 image uses Kernel 5.10, which is relatively mature and performs more stably in video encoding/decoding and various applications. +![zstd-version](/img/image-for-flash/zstd-version.png) -The 20250110 image uses Kernel 6.6, which may have some unknown issues. Known issues include video stuttering and USB power loss. These problems are currently being addressed. +If a version string similar to the following is printed, `zstd` is installed: -Please choose the appropriate image based on your needs after reading the above description. +```bash +*** zstd command line interface 64-bits v1.4.8, by Yann Collet *** +``` -The following demonstrates the process using the 20250110 image as an example: +If no version information appears, install `zstd` with: -**Note:** The downloaded `.zst` compressed file is approximately 1.4GB. Ensure that you have at least 12GB of free space on your device to avoid running out of space during the download and extraction process. +```bash +sudo apt update +sudo apt install zstd +``` + +![zstd-install](/img/image-for-flash/zstd-install.png) -![image-size](/img/image-for-flash/sdcard-image-size.png) +## Boot Methods -If downloading via a web browser, click the link to start the download. Your browser will automatically handle the file download. Confirm the download and ensure the file is saved locally. +Lichee Pi 4A currently supports two boot options: [booting from an SD card](#boot-from-sd-card) and [booting from eMMC](#boot-from-emmc). Choose the section corresponding to your use case. -![web-download](/img/image-for-flash/web-download.png) +:::warning +Flashing an image erases all existing data regardless of the method. **Back up important data beforehand.** +::: -If you prefer to download via the command line, tools like `wget` and `curl` can be used. In this guide, we use `wget` as the download tool. +:::warning +**Upgrading from images dated `20240720` or earlier requires resetting the U-Boot environment variables.** -In most [demonstration environments](#demonstration-environment), `wget` is pre-installed. If `wget` is not installed, use the following command to install it: +Reset procedure: +Connect to the board over the serial console, power it on, interrupt U-Boot by pressing Enter, and run the following commands: ```bash -sudo apt install wget -``` +env default -a -f; env save; reset +``` -![wget-install](/img/image-for-flash/wget-install.png) +This restores all U-Boot environment variables to their defaults and reboots the board. +::: -**Note:** The `sudo` command requires a password for execution. Ensure you know the password before proceeding. This will not be repeated in subsequent steps. +## Boot from SD Card -Once installed, use the following command to download the image archive: +:::warning +**DIP switch reminder** -```bash -wget https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250110/sdcard-lpi4a-20250110_151339.img.zst -``` +No switch changes are required for SD card boot; keep the DIP switches in the eMMC position. -![image-download](/img/image-for-flash/wget-download-sd.png) +![DIP switch reference](/img/image-for-flash/Switch.png) -After downloading, you will obtain a file named [sdcard-lpi4a-20250110_151339.img.zst](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250110/sdcard-lpi4a-20250110_151339.img.zst). This is not the final image file but a compressed archive. You need to extract the compressed file `sdcard-lpi4a-20250110_151339.img.zst` to obtain the final image file `sdcard-lpi4a-20250110_151339.img`. +The DIP switch is located on the underside of the board and is accessible after removing the baseboard. Set both toggles to the downward position. -In the [demonstration environment](#Demonstratio- Environment) mentioned earlier, `.zst` files can be extracted using various tools such as `zstd`, `tar`, or `7z`. This guide demonstrates one method using the `zstd` tool via the command line. First, you need to install the `zstd` package on your system before extracting the file. +**Note:** Some early Lichee Pi 4A revisions do not provide a DIP switch. +::: -If you are unsure whether `zstd` is already installed on your system, execute the following command to check the version of `zstd`. If a version is displayed, it indicates that `zstd` is installed. +:::warning +**SD card compatibility** -```bash -zstd --version -``` +Certain SD cards may exhibit compatibility issues. Consult the [Lichee Pi 4A SD card compatibility list](../../miscellaneous/lpi4a-sdcard-list/) to confirm whether your card is known to work. +::: -![zstd-version](/img/image-for-flash/zstd-version.png) +### Preparation -If the version is displayed, like the example below, you have `zstd` is already installed. +#### Obtain the SD Card Image -```bash -*** zstd command line interface 64-bits v1.4.8, by Yann Collet *** -``` +Download the Lichee Pi 4A system image that has the `sdcard-` prefix from the following locations: + +- [RevyOS 20240720 (Kernel 5.10)](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20240720/) +- Latest release (Kernel 6.6): {} + +:::note +**About kernel versions** + +The 20240720 image uses Kernel 5.10, which is mature and offers stable performance for multimedia and general applications. + +The latest image uses Kernel 6.6. It may still contain unresolved issues; known ones include video stutter and USB power loss. Fixes are in progress. +::: + +The example below uses the 20250110 image. + +> The downloaded `.zst` archive is approximately 1.4 GB. Ensure you have at least 12 GB of free space to avoid running out of storage during download or extraction. + +![image-size](/img/image-for-flash/sdcard-image-size.png) + +Two download methods are available: + +- **Browser download:** click the link; the browser starts downloading automatically. Confirm that the file is saved locally. + +![web-download](/img/image-for-flash/web-download.png) + +- **Command-line download:** use `wget` as shown below. -If no version information is displayed, install `zstd` using the following commands: ```bash -sudo apt update -sudo apt install zstd -``` +wget https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250110/sdcard-lpi4a-20250110_151339.img.zst +``` + +![image-download](/img/image-for-flash/wget-download-sd.png) -![zstd-install](/img/image-for-flash/zstd-install.png) +After downloading, you obtain `sdcard-lpi4a-20250110_151339.img.zst`. This is a compressed archive rather than the final image. Extract `sdcard-lpi4a-20250110_151339.img.zst` to obtain `sdcard-lpi4a-20250110_151339.img`. -After installing `zstd`, you can extract the image file. **Note:** The extracted file will be approximately **10.2GB** in size. Ensure you have enough local storage space before proceeding with the extraction! +With `zstd` installed, extract the archive: + +:::warning +**Extraction size reminder** + +The extracted image is roughly **10.2 GB**. Verify that you have sufficient disk space before running the extraction. +::: ```bash sudo unzstd sdcard-lpi4a-20250110_151339.img.zst -``` +``` -Once the extraction is complete, you will have the file `sdcard-lpi4a-20250110_151339.img`. At this point, the image file has been successfully obtained in the demonstration environment. +After extraction you will have `sdcard-lpi4a-20250110_151339.img` and the image acquisition step is complete. -![imgsize](/img/image-for-flash/sdcard-image.png) +![unzstd-sdcard](/img/image-for-flash/unzstd.png) -#### Hardware preparation +#### Hardware Preparation -Prepare a MicroSD card reader and a MicroSD card. Note that there are compatibility issues with MicroSD cards. RevyOS provides a list of [tested MicroSD cards](https://github.com/revyos/revyos/blob/main/Installation/card%20list.md). +Prepare a MicroSD card reader and a MicroSD card. Compatibility issues with SD cards are known; refer to the [tested card list](https://github.com/revyos/revyos/blob/main/Installation/card%20list.md). -If your MicroSD card is not on the list of known compatible cards and you encounter issues such as failure to write the image or failure to boot after writing, refer to [this page](../../issue/) to submit an issue. You can also try the [eMMC boot guide](#booting-from-emmc) for writing the image. +:::note +If your MicroSD card is not listed and you encounter flashing or boot failures, submit an issue via [this page](../../issue/) and consider following the [eMMC boot](#boot-from-emmc) instructions instead. +::: -### Image Writing Methods +### Writing the SD Card Image -If you choose to boot from an SD card, there are two methods to write the image to the MicroSD card:[Using a graphical interface tool](#writing-the-image-with-balenaetcher) like BalenaEtcher, or [Using the `dd` command in the command line](#writing-the-image-with-dd). +Two methods are available for writing an SD card image: using a [graphical tool](#writing-with-balenaetcher) such as BalenaEtcher, or the [command-line `dd` utility](#writing-with-dd). -#### Writing the Image with BalenaEtcher +#### Writing with BalenaEtcher -Download the BalenaEtcher tool from its official website: [https://etcher.balena.io/](https://etcher.balena.io/). Select the appropriate file for your system. For the [demonstration environment](#Demonstratio- Environment), download and extract [Etcher for Linux x64 (64-bit) (zip)](https://github.com/balena-io/etcher/releases/download/v1.19.25/balenaEtcher-linux-x64-1.19.25.zip). +Download BalenaEtcher from the official site: [https://etcher.balena.io/](https://etcher.balena.io/). Choose the build that matches your host. In the [demonstration environment](#demonstration-environment), download and extract [Etcher for Linux x64 (64-bit) (zip)](https://github.com/balena-io/etcher/releases/download/v1.19.25/balenaEtcher-linux-x64-1.19.25.zip). -![BE-version](/img/image-for-flash/BE-version.png) +![BE-version](/img/image-for-flash/BE-version.png) -Insert the SD card into the card reader and connect it to your computer. +Insert the SD card into the reader and connect it to the computer. -Run BalenaEtcher to write the image to the SD card. -In the BalenaEtcher window, click **"Flash from file"** to select the image file. -{} -After selecting the image file, choose the target device in the second field. -{} -Once both options are selected, click **"Flash"** to write the image. -{} -After some time, a message will indicate that the writing process is complete. -{} +Launch BalenaEtcher and follow the prompts to write the image: +- Click **Flash from file** and select the image file. +![](/img/image-for-flash/BE1.png) +- In the second column, choose the target device. +![](/img/image-for-flash/BE2.png) +- Click **Flash** to start writing. +![](/img/image-for-flash/BE3.png) +- Wait until the completion dialog appears. +![](/img/image-for-flash/BE4.png) -#### Writing the Image with `dd` +:::warning +**Safe removal reminder** -`dd` is a powerful command-line tool in Linux and Unix-like systems, used to copy files or data with specified sizes and formats. It is usually pre-installed. +Ensure the BalenaEtcher process has finished and the SD card activity LED has stopped blinking before removing the card. Interrupting power early may corrupt the card or the image. +::: -Follow these steps to write the image using `dd`: +#### Writing with `dd` -First, check the list of devices by running the following command before and after inserting the SD card to identify the corresponding device name of the SD card: +`dd` is a powerful command-line utility for copying data with explicit control over block size and format. It is usually pre-installed on Linux systems. + +Follow the steps below to write the image with `dd`. + +1. Inspect the device list before and after inserting the SD card to determine the device node: ```bash lsblk ``` -The device name for the SD card might be `/dev/sda` or `/dev/mmcblk0`. In the demonstration environment, the SD card partition is identified as `/dev/sda` after executing `lsblk`. +Typical SD card devices include `/dev/sda` or `/dev/mmcblk0`. In this tutorial the SD card appears as `/dev/sda`. ![lsblk](/img/image-for-flash/lsblk.png) -Before writing the image, unmount any mounted partitions of the SD card. If there are multiple partitions, unmount each one: +2. Unmount any mounted partitions before writing. If multiple partitions exist, unmount each one: ```bash sudo umount /dev/sdX1 ``` -If no partitions are mounted, the `umount` command will display `not mounted`, and no further action is needed. +If nothing is mounted, `umount` reports `not mounted`; no further action is required. -After unmounting the partitions, it is recommended to run the `sudo sync` command to ensure all data is synchronized. +3. Run `sudo sync` to flush pending IO: ![sync](/img/image-for-flash/sync.png) -After completing the above steps, you can proceed with writing the image. Before writing, ensure that the correct device is set in the `of=` parameter. In the demonstration environment, the SD card is recognized as `sda`. Replace `of=` with your device's partition accordingly. +4. Write the image. Confirm that the `of=` argument references the correct device (replace `sdX` with the appropriate value from `lsblk`). In this example the device is `sda`: ```bash sudo dd if=./sdcard-lpi4a-20250110_151339.img of=/dev/sdX bs=4M status=progress @@ -195,32 +252,32 @@ sudo dd if=./sdcard-lpi4a-20250110_151339.img of=/dev/sdX bs=4M status=progress ![dd](/img/image-for-flash/dd.png) -After the writing process is complete, run the `sudo sync` command again to ensure data synchronization. Then confirm that the SD card is in an unmounted state before safely removing it and inserting it into the development board. +:::warning +**Caution when using `dd`** + +Always double-check the target device (e.g. `/dev/sdX`) before executing `dd`. Selecting the wrong disk—such as your system drive—will cause irreversible data loss. Use `lsblk` or `fdisk -l` to verify the device path. After writing, run `sudo sync`, unmount the SD card, and only then remove it and insert it into the development board. +::: -### Booting the System via SD Card +### Booting the System -After writing the image, insert the SD card into the slot shown below. +After writing the image, insert the SD card into the slot shown below. ![](/img/image-for-flash/lpi4a5.png) -First, connect the HDMI cable (if an external display is needed). Then, use the USB-A to USB-C cable included in the package: connect the USB-C end to the development board and the USB-A end to a USB power source with at least 5V2A output to boot the system. +Connect an HDMI cable if you require an external display. Use the supplied USB-A-to-USB-C cable: connect the USB-C end to the board, the USB-A end to a power supply that can provide at least 5 V / 2 A, and the system will boot. -## Booting from eMMC +## Boot from eMMC -When booting the image from eMMC, there are two methods for writing the image: with or without a serial connection. The operations differ slightly, and both methods are introduced below. +Two procedures are available for flashing the eMMC image: one without a serial console and one with it. Since a serial cable is optional, the default workflow assumes no serial connection, while the serial procedure is provided for users who have a cable. -**Note!** When booting from eMMC, remove the SD card first! +:::warning +Remove the SD card before booting from eMMC. +::: ### Preparation -#### Hardware Preparation - - - -#### Installing the Image Writing Tool +#### Install the Flashing Toolchain -To boot from eMMC, you need to write the `u-boot`, `boot`, and `root` files into the eMMC using the `fastboot` tool. First, confirm whether `fastboot` is installed. - -If you are unsure whether `fastboot` is installed, run the following command. This command checks the version of `fastboot`, and the output will indicate whether the `fastboot` package is pre-installed. +Flashing the eMMC requires writing the `u-boot`, `boot`, and `root` images via the `fastboot` utility. Verify that `fastboot` is installed: ```bash fastboot --version @@ -228,184 +285,237 @@ fastboot --version ![fastboot-version](/img/image-for-flash/fastboot-version.png) -If the version is displayed correctly, it means `fastboot` is successfully installed. For example, the following output indicates that `fastboot` is installed: +If output similar to the following appears, `fastboot` is installed: ```bash fastboot version 28.0.2-debian Installed as /usr/lib/android-sdk/platform-tools/fastboot ``` -If no version is displayed, please install `fastboot` in your command line +If no version info is printed, install `fastboot`: ```bash sudo apt install fastboot ``` -![fastboot-install](/img/image-for-flash/zstd-install.png) - -```bash -sudo apt install fastboot -``` - -#### Install Serial Console Tool +![fastboot-install](/img/image-for-flash/fastboot-install.png) -When using a serial connection, a serial console tool is required for monitoring. There are many serial console tools available, such as `minicom`, `screen`, and `picocom`. In this guide, we will use `minicom` for demonstration. +#### Obtain the Images -```bash -sudo apt install minicom -``` +Download the Lichee Pi 4A system images from the following locations: -After installation, you can confirm if `minicom` was successfully installed by checking its version: +- [RevyOS 20240720 (Kernel 5.10)](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20240720/) +- Latest release (Kernel 6.6): {} -```bash -minicom -version -``` +:::note +**About kernel versions** -#### Obtain the Image +The 20240720 image uses Kernel 5.10, which is stable for video codecs and general workloads. -Download the system image for LicheePi4A from the following links: +The latest image uses Kernel 6.6. It may encounter unresolved issues, such as video stutter or USB power loss. Fixes are actively being developed. +::: -- [RevyOS20240720](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20240720/) -- [RevyOS20250110](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250110/) +:::warning +**Choosing the correct U-Boot firmware** -**Note!** +Different memory configurations require different U-Boot binaries. Use the table below to match your core board configuration: -The u-boot images for different memory configurations of LicheePi4A are not interchangeable. Please select the appropriate image based on the version of your core board. +| Memory and storage | U-Boot image | +| --- | --- | +| 8 GB RAM + 8 GB eMMC | u-boot-with-spl-lpi4a-main_8gemmc.bin | +| 8 GB RAM + 32 GB eMMC | u-boot-with-spl-lpi4a-main.bin | +| 16 GB RAM | u-boot-with-spl-lpi4a-16g-main.bin | -| Memory and Storage Combination | Corresponding u-boot Image | -|--------------------------------|----------------------------| -| 8G RAM + 8G eMMC | u-boot-with-spl-lpi4a-main_8gemmc.bin | -| 8G RAM + 32G eMMC | u-boot-with-spl-lpi4a-main.bin | -| 16G RAM | u-boot-with-spl-lpi4a-16g-main.bin | +If you are unsure about the configuration, scan the QR code sticker on the core board. When the board ships, stickers are attached to both the core board and the baseboard. Scanning the core board sticker reveals the RAM and storage specification. -If you are unsure about the specifications of your core board, you can scan the QR code on the core board to check. When LicheePi4A is shipped, a QR code sticker is attached to the core board. Scanning it will display the memory and storage configuration of the core board. - -For example, for a 16G RAM + 128G eMMC configuration, you can find the QR code sticker here: +Example for a 16 GB RAM + 128 GB eMMC configuration: ![core-card](/img/image-for-flash/core-card.png) -Scanning the QR code will display the following: +Scanning the QR code yields: ![Core board-info](/img/image-for-flash/card-info.png) -After confirming the board specifications, use `wget` to download the u-boot, boot, and root files: +The second line lists the RAM plus storage configuration. +::: + +After confirming the board specification, download the U-Boot, boot, and root images with `wget`: ```bash -sudo wget u-boot-with-spl-lpi4a-16g-main.bin -sudo wget boot-lpi4a-20250110_151339.ext4.zst -sudo wget root-lpi4a-20250110_151339.ext4.zst +sudo wget https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250110/u-boot-with-spl-lpi4a-16g-main.bin +sudo wget https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250110/boot-lpi4a-20250110_151339.ext4.zst +sudo wget https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20250110/root-lpi4a-20250110_151339.ext4.zst ``` ![emmc-download](/img/image-for-flash/wget-download.png) -After downloading, use the `unzstd` command to decompress the root and boot files: +Extract the boot and root archives with `unzstd`: ```bash unzstd boot-lpi4a-20250110_151339.ext4.zst unzstd root-lpi4a-20250110_151339.ext4.zst ``` -Once decompression is complete, you will have the files required for writing the eMMC image. +After extraction, the required files for flashing the eMMC are ready. ![file](/img/image-for-flash/unzstd-bootandroot.png) -### Writing the Image to eMMC (Without Serial Connection) +### Writing the eMMC Image (No Serial Console) -Press and hold the BOOT button on the board, then connect it to your computer. The board will enter flashing mode. +Press and hold the BOOT button on the board and connect it to the computer. The board enters flashing mode. -### Writing the Image to eMMC (With Serial Connection) +Use `lsusb` to verify the connection: -#### Using `minicom` +![lsusb](/img/image-for-flash/lsusb.png) + +A successful connection appears as `ID 2345:7654 T-HEAD USB download gadget`. -First, open `minicom` from the terminal to access the serial console: +After confirming the connection, flash a temporary U-Boot to RAM and reboot: ```bash -sudo minicom +fastboot flash ram u-boot-with-spl-lpi4a-16g.bin # Replace with the U-Boot image for your configuration +fastboot reboot +sleep 1 ``` -If you need to specify the serial device (e.g., the commonly used USB-to-serial device `ttyUSB0`), you can use: +![flash-ram](/img/image-for-flash/flash-ram.png) + +Next, flash the persistent images: + +```bash +fastboot flash uboot u-boot-with-spl-lpi4a-16g.bin +fastboot flash boot boot-lpi4a-20240720_171951.ext4 +fastboot flash root root-lpi4a-20240720_171951.ext4 +``` + +![flash-ubootandboot](/img/image-for-flash/flash-ubootandboot.png) + +:::warning +**Progress and timing note** + +Flashing `uboot` and `boot` completes quickly. Writing `root` requires roughly five minutes. If the number of data blocks reported during the `root` flash is unexpectedly small (e.g. only in the low thousands), earlier steps likely failed—repeat the flashing process. +::: + +![flash-root](/img/image-for-flash/flash-root.png) + +Flashing is now complete. Power-cycle the board to boot into the system. + +### Writing the eMMC Image (With Serial Console) + +#### Install a Serial Console Tool + +When using a serial connection, a terminal program is required for monitoring. Tools such as `minicom`, `screen`, and `picocom` are suitable; this guide uses `minicom`. ```bash -sudo minicom -D /dev/ttyUSB0 +sudo apt install minicom ``` -#### Using `screen` -Open `screen` from the terminal. Replace `/dev/ttyUSB0` with your device, and `115200` with the baud rate: +![minicom-install](/img/image-for-flash/minicom-install.png) + +Verify the installation by checking its version: ```bash -sudo screen /dev/ttyUSB0 115200 +minicom -version ``` -As shown in the diagram, connect the serial port to the board. The USB end connects to the computer, while the Type-C port on the board connects to the computer using a USB-Type-C cable. +![minicom-version](/img/image-for-flash/minicom-version.png) + +#### Using `minicom` + +Wire the serial adapter to the board as illustrated below. Connect the USB side to the host computer. The board’s USB Type-C port is connected by a USB Type-C cable. -For the serial connection, the red circle (first row, second pin from the left) is GND, the yellow circle (first row, fifth pin) is TX, and the green circle (second row, fifth pin) is RX. The connection to the host should follow TX to RX, RX to TX, and GND to GND. +GND corresponds to the red circle (first row, second pin from the left), TX to the yellow circle (first row, fifth pin), and RX to the green circle (second row, fifth pin). Connect TX to RX, RX to TX, and GND to GND. ![](/img/image-for-flash/lpi4a6.png) -After connecting, press any key in the serial console to interrupt the auto-start process. You will see the following u-boot command line (see the last line): +Determine the serial device by listing `/dev/tty*` before and after plugging in the adapter: -![](/img/image-for-flash/image-start.png) +```bash +ls /dev/tty* +``` -In the serial console window, enter: +After connecting the adapter, an additional entry such as `/dev/ttyUSB0` appears. + +![lstty](/img/image-for-flash/lstty.png) + +Start `minicom`, specifying the device and baud rate (115200 in this example): + +```bash +sudo minicom -D /dev/ttyUSB0 -b 115200 +``` + +![minicom-start](/img/image-for-flash/minicom-start.png) + +#### Enter Fastboot + +Once `minicom` is running, connect the USB Type-C cable to power the board. On the serial console, interrupt the boot process when `Hit any key to stop autoboot` appears (the countdown lasts about three seconds). The U-Boot command line is then presented. + +![start](/img/image-for-flash/image-start.png) + +Enter the following command in the serial console: ```bash fastboot usb 0 ``` -The output will show: +You should see output similar to: + ```bash Light LPI4A 16G# fastboot usb 0 dwc3_gadget_start maximum_speed:5 revision:0x5533330b dwc3_gadget_start DWC3_DCFG:0x80804 +dwc3_gadget_start_conndone_interrupt speed:0 dwc3_dsts:0x20000 +dwc3_gadget_start_conndone_interrupt speed:0 dwc3_dsts:0x2f938 ``` -This indicates that `fastboot` can be used for flashing. Open another terminal window to proceed with image flashing. +![usb0](/img/image-for-flash/fastboot-usb0.png) -### Flashing the Image -All commands below should be executed in the directory where the image files are located. Pay attention to the file paths and names. +This indicates that `fastboot` is ready. Open another terminal to execute the flashing commands. -#### Put the Device into U-Boot Fastboot Mode -If the `lsusb` result is not `ID 1234:8888 Brain Actuated Technologies USB download gadget`, run the following commands: -```bash -fastboot flash ram u-boot-with-spl-lpi4a-16g.bin # Replace with the u-boot image for your specific model -fastboot reboot -sleep 1 -``` +#### Flash the Images + +Run the following commands in the directory where the image files were downloaded. If you execute them elsewhere, adjust the file paths accordingly. -#### Flash the Image ```bash fastboot flash uboot u-boot-with-spl-lpi4a-16g.bin fastboot flash boot boot-lpi4a-20240720_171951.ext4 fastboot flash root root-lpi4a-20240720_171951.ext4 ``` -`fastboot` will display the flashing progress. If a serial connection is established, you can view the detailed progress in the serial console (the example below shows flashing `boot`, with a size of 92,886,476 bytes. You can see the flashed content at `cmd_parameter: boot, imagesize: 92886476`). +`fastboot` reports progress. If the serial console is connected, detailed logs are visible there—for example, when flashing `boot` (92,886,476 bytes), the log shows `cmd_parameter: boot, imagesize: 92886476`. -![](/img/image-for-flash/flash-root-minicom.png) +![flash-boot](/img/image-for-flash/flash-root-minicom.png) -Once flashing is complete, disconnect the USB-Type-C cable from the computer and the board, connect the power cable, and the system will boot up. +After flashing, disconnect the USB Type-C cable linking the board and the host, connect a power cable, and the system will boot automatically. +## Troubleshooting -### Potential Issues +### Linux: `< waiting for any device >` -#### Linux only: stuck at < waiting for any device > +If `lsusb` lists the download gadget but `fastboot` remains at `< waiting for any device >`, rerun the command with `sudo`. -If the `lsusb` output shows a download device but the `fastboot` command remains stuck at `< waiting for any device >`, try running the `fastboot` command with `sudo`. +![waiting](/img/image-for-flash/waiting.png) -#### Issues After Major Version Upgrade +### Issues After Major Upgrades -If you **use a serial connection to enter U-Boot** and start fastboot flashing (see [here](#writing-the-image-to-emmc-with-serial-connection)), the issue might be caused by U-Boot retaining old environment variables. Please enter the following command in the U-Boot serial console: +If problems occur after a major upgrade, the U-Boot environment may need to be reset. -``` -env default -a -f; env save; reset -``` +Reset procedure: +Connect to the board via serial, power it on, interrupt U-Boot, and run: -If this version includes partition table changes, additionally run: -``` -run gpt_partition +```bash +env default -a -f; env save; reset ``` -### User Login +This resets all environment variables and reboots the board. + +If the partition layout differs from the previous image, additionally run `run gpt_partition`. + +## User Credentials + +Default login credentials are: + +- Username: `debian` +- Password: `debian` -- Login account: `debian` -- Password: `debian` \ No newline at end of file +Use these for first boot. For security, change the password immediately after logging in. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/Installation/milkv-meles.mdx b/i18n/en/docusaurus-plugin-content-docs/current/Installation/milkv-meles.mdx index 8131f86..9a8aa7c 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/Installation/milkv-meles.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/Installation/milkv-meles.mdx @@ -6,53 +6,48 @@ import { DownloadLink } from "@site/src/components/ImageLinks"; # Milk-V Meles Image Flashing Guide -This page provides a tutorial for flashing images to the Milk-V Meles, specifically for Linux. +This page describes the Linux workflow for flashing images to Milk-V Meles. Use the links below for other devices or operating systems. -To view image flashing tutorials for other operating systems, please click the links in the table below: +| Other Flashing Tutorials | Link | +| --- | --- | +| Lichee Pi 4A (Linux) | [Linux flashing guide](../licheepi4a/) | +| Lichee Pi 4A (Windows) | [Windows flashing guide](../licheepi4a-windows/) | +| Milk-V Pioneer | [Flashing guide](../milkv-pioneer/) | -| Other Flashing Tutorials | Link | -| ------------------------ | -------------------------------------------- | -| LicheePi4A | [Linux Flashing Tutorial](../licheepi4a/) | -| LicheePi4A | [Windows Flashing Tutorial](../licheepi4a-windows/) | -| Milk-V Pioneer | [Flashing Tutorial](../milkv-pioneer/) | - -:::note - -Before proceeding with this tutorial, please ensure that the board you have matches the image below. Only continue if they are identical. +:::warning +Before you proceed, compare your board against the reference image and make sure the hardware matches. -![Milk-V Meles Broad Example](/img/image-for-flash/meles.png) +![Milk-V Meles reference](/img/image-for-flash/meles.png) ::: -## Introduction to the Demonstration Environment +## Demonstration Environment -All image flashing operations in this tutorial are performed using the following environment: +All steps were validated under the following environment: -- System and Version: Ubuntu 22.04.5 LTS +- Operating system: Ubuntu 22.04.5 LTS - Architecture: x86_64 -- Board Specifications: 8GB RAM -- Python Version: 3.10.12 +- Milk-V Meles configuration: 8 GB 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](../../issue/) to submit an issue. +If you follow this procedure in the same environment and encounter issues, submit an issue via [the support page](../../issue/). -:::note -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. +:::warning +Python versions newer than 3.12 may fail when writing the bootloader to SPI NOR flash. Use Python 3.11 or earlier. ::: ## 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 +The following packages are required for downloading and flashing images. Install them before continuing. -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. +### Download Utility -In the [demonstration environment](#introduction-to-the-demonstration-environment), wget is usually pre-installed. You can check whether wget is installed by querying the wget version in the command line. +In a desktop environment you can download images from the mirror via a browser. For command-line downloads we use `wget`. ```bash wget --version ``` -If wget is not installed, please use the following command to install it: +If `wget` is missing, install it: ```bash sudo apt install wget @@ -60,15 +55,11 @@ sudo apt install wget ![wget-install](/img/image-for-flash/wget-install.png) -:::note -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. -::: +> `sudo` prompts for your password. Ensure you know it; this reminder will not be repeated later. -### File Unzipping Tool +### Archive Utility -In the above [demonstration environment](#introduction-to-the-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. +`.zst` archives can be unpacked with `zstd`, `tar`, or `7z`. This tutorial demonstrates the `zstd` command-line tool. Confirm whether it is installed: ```bash zstd --version @@ -76,13 +67,7 @@ zstd --version ![zstd-version](/img/image-for-flash/zstd-version.png) -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: - -```bash -*** 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: +If no version is shown, install `zstd`: ```bash sudo apt update @@ -91,33 +76,31 @@ sudo apt install zstd ![zstd-install](/img/image-for-flash/zstd-version.png) -## Introduction to Broad's Boot Methods +## Boot Options -Milk-V Meles currently supports two boot methods: [Booting from SD card](#booting-from-sd-card) and [Booting from eMMC](#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. +Milk-V Meles supports two boot paths: [booting from an SD card](#boot-from-sd-card) and [booting from eMMC](#boot-from-emmc). Choose the method that fits your scenario. :::warning -Regardless of which flashing method is used, the original user data will be lost, so be sure to back up your data before flashing! +Flashing erases existing data. Back up important files before you begin. ::: -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. +Before tackling either boot mode, ensure that the SPI NOR flash holds the correct firmware. The next section explains how to program it. -## Flashing SPI Nor Flash Firmware +## Flash the SPI NOR 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. +Milk-V Meles relies on its SPI NOR flash to store the bootloader that brings up the system and exposes the SoC download mode. The SoC cannot boot directly from MicroSD or USB. -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](https://milkv.io/zh/docs/meles/hardware/meles-main-board). The connection with the host should follow the TX to RX, RX to TX, and GND to GND wiring. +If you replace the SPI NOR device or the firmware becomes corrupted, reflash the bootloader via a serial connection. Wiring instructions are available in the official [hardware documentation](https://milkv.io/zh/docs/meles/hardware/meles-main-board); connect TX ↔ RX and GND ↔ GND between the board and host. ### Preparation -First, you need to install yoctools to the local device. In the demonstration environment, you can directly install it through the pip command: +Install Yoctools: ```bash sudo pip install yoctools -U ``` -If the pip command cannot be executed, please install pip first if pip is not installed: +If `pip` is unavailable, install it first: ```bash sudo apt install python3-pip @@ -125,262 +108,178 @@ sudo apt install python3-pip ![pip-install](/img/image-for-flash/pip-install.png) -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. +Verify the installation: ```bash yoc --version -2.1.11 ``` ![yoc-version](/img/image-for-flash/yoc-version.png) -Secondly, you need to download the image burning software: +Download the image writer utility: ```bash 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. +Download the U-Boot binary that matches your board: + +- 8 GB model: `u-boot-with-spl-meles.bin` +- 16 GB model: `u-boot-with-spl-meles-16g.bin` + +Example (8 GB board): ```bash 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 the Bootloader to SPI NOR Flash -### 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: +1. Determine the serial port device (commonly `/dev/ttyUSB0`). +2. List available devices with `cct`: ```bash sudo cct list -u /dev/ttyUSB0 -Wait .............. ``` -![cct-list](/img/image-for-flash/cct-list.png) - -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: - -![timeout](/img/image-for-flash/timeout.png) - -- 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: +The program waits for the board to respond. Connect the USB-to-TTL adapter, wire TX ↔ RX and GND ↔ GND, press and hold the download button, power the board via USB Type-C, then release the button. The storage list should appear: ```bash -sudo cct list -u /dev/ttyUSB0 -Wait ............................ Memory device list: dev = ram0 , size = 1.1MB dev = qspi0 , size = 16.0MB ``` -![cct-list1](/img/image-for-flash/cct-list1.png) - -Then we download the image burning software to SRAM: +3. Load the image writer into SRAM: ```bash 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. - -![cct-download](/img/image-for-flash/cct-download.png) +Wait for the transfer and checksum to complete. -Then the download is complete: - -```bash -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... -``` - -![cct-download1](/img/image-for-flash/cct-download1.png) - -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. - -```bash -$ sudo cct download -u /dev/ttyUSB0 -d qspi0 -f u-boot-with-spl-meles.bin -v checksum -r -t 1200 -``` - -![cct-download2](/img/image-for-flash/cct-download2.png) - -After executing this command, there will also be a percentage progress bar. Please wait for about one minute. - -Then the download is complete: +4. Flash the U-Boot binary to SPI NOR (adjust the file name if you use the 16 GB image): ```bash 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... ``` -![cct-download3](/img/image-for-flash/cct-download3.png) +A progress indicator appears; the operation typically finishes within a minute. After the checksum passes, the SPI NOR flash is updated. -So far, the flashing is complete. Subsequent boot methods are divided into [Booting from SD card](#booting-from-sd-card) and [Booting from eMMC](#booting-from-emmc). Please select and flash according to your needs. +You can now proceed with either boot method. -## Booting from SD card +## Boot 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)](https://github.com/revyos/revyos/blob/main/Installation/card%20list.md) that has been tested. +Prepare a MicroSD card reader and a MicroSD card. Because compatibility varies, refer to the [tested card list](https://github.com/revyos/revyos/blob/main/Installation/card%20list.md). -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](../../issue/) to submit an issue, and try referring to the [Booting from eMMC](#booting-from-emmc) image flashing tutorial to flash the image. +If flashing or booting fails with an unlisted card, submit an [issue](../../issue/) and consider using the eMMC method instead. -### SD Card Image Preparation +### Obtain the SD Card Image -The latest version of the SD card image is 20250323, which can be downloaded via the following command: +Download the SD card image (prefixed with `sdcard-meles-`) from: -```bash -wget https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250323/sdcard-meles-20250323_154525.img.zst -``` +- [RevyOS 20240720 (Kernel 5.10)](https://mirror.iscas.ac.cn/revyos/extra/images/meles/20240720/) +- Latest release (Kernel 6.6): {} -This file is a .zst compressed package, which needs to be decompressed after downloading. You can use the zstd tool to decompress it. +Example for RevyOS 20250323: ```bash +wget https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250323/sdcard-meles-20250323_154525.img.zst unzstd sdcard-meles-20250323_154525.img.zst ``` -After decompression, an image file named `sdcard-meles-20250323_154525.img` will be generated. +The extraction generates `sdcard-meles-20250323_154525.img`. -### Introduction to Burning Methods +### Writing Options -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](#writing-the-image-to-the-microsd-card-using-balenaetcher), and the other is to use the dd command [to burn in the command line](#writing-the-image-using-dd-command). -Here we will introduce the operation steps of the two burning methods, you can choose one of them according to your needs. +Choose one of the following methods to write the image to the SD card: -#### Writing the image to the MicroSD card using BalenaEtcher +#### BalenaEtcher -Get the burning tool BalenaEtcher from the official website [https://etcher.balena.io/](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](#introduction-to-the-demonstration-environment), select [Etcher for Linux x64 (64-bit) (zip)](https://github.com/balena-io/etcher/releases/download/v1.19.25/balenaEtcher-linux-x64-1.19.25.zip) to download, decompress and install. +Download BalenaEtcher from [https://etcher.balena.io/](https://etcher.balena.io/) and install the Linux x64 build. ![BE-version](/img/image-for-flash/BE-version.png) -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. +1. Insert the SD card. +2. Launch BalenaEtcher. +3. Click **Flash from file** and select the image. +4. Select the target device. +5. Click **Flash** and wait for completion. ![BE5](/img/image-for-flash/BE5.png) - -After selecting the image file, select the device to be written in the second column. - ![BE6](/img/image-for-flash/BE6.png) - -After selecting both items, click "Flash" to write the image. - -After waiting for a while, it will show that the burning is complete. - ![BE7](/img/image-for-flash/BE7.png) -#### 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. +#### `dd` -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: +1. Identify the device node (`/dev/sdX` or `/dev/mmcblk0`) using `lsblk`. +2. Unmount any mounted partitions: ```bash -lsblk +sudo umount /dev/sdX1 ``` -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`. +3. Flush pending writes: -![lsblk-meles](/img/image-for-flash/lsblk-meles.png) +```bash +sudo sync +``` -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: +4. Write the image (replace `sdX` with the correct device): ```bash -sudo umount /dev/sdX1 +sudo dd if=sdcard-meles-20250323_154525.img of=/dev/sdX bs=4M status=progress +sudo sync ``` -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. +![dd-meles](/img/image-for-flash/dd-meles.png) -![sync-meles](/img/image-for-flash/sync-meles.png) +Ensure the card is unmounted before removing it. -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=`. +### Boot from SD Card -```bash -sudo dd if=./sdcard-meles-20250323_154525.img of=/dev/sdX bs=4M status=progress -``` +Insert the SD card into the slot shown below and power on the board. -![dd-meles](/img/image-for-flash/dd-meles.png) +![SD slot](/img/image-for-flash/sd-card-slot.png) -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. +## Boot from eMMC -#### Booting the system via SD card +Ensure the eMMC module is installed on the back of the board before flashing. -After writing the image, insert the SD card into the card slot shown in the figure. +### Obtain the eMMC Images -![SDCard slot](/img/image-for-flash/sd-card-slot.png) +Download the following files: -## Booting from eMMC +- [RevyOS 20240720 (Kernel 5.10)](https://mirror.iscas.ac.cn/revyos/extra/images/meles/20240720/) +- Latest release (Kernel 6.6): {} -Before flashing, make sure that the eMMC module has been successfully installed on the back of the development board. +Required files: -### eMMC Image Preparation +- `u-boot-with-spl-meles*.bin` — U-Boot binary +- `boot-meles-*.ext4.zst` — boot partition +- `root-meles-*.ext4.zst` — root partition -The latest version of the eMMC image is 20250323, which can be downloaded via the following command: +Example (20250323): ```bash 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. - -```bash 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. +### Install Fastboot -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. +Check whether `fastboot` is available: ```bash fastboot --version ``` -![fastboot-version](/img/image-for-flash/fastboot-version.png) - -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: - -```bash -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: +If not, install it: ```bash sudo apt install fastboot @@ -388,66 +287,50 @@ sudo apt install fastboot ![fastboot-install](/img/image-for-flash/fastboot-install.png) -#### Writing the image to eMMC - -First, you need to put the board into burning mode. Please perform the following operations in order: +### Flash the eMMC -- 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`. - -![lsusb-meles](/img/image-for-flash/lsusb-meles.png) - -After a normal connection, the following device `ID 2345:7654 T-HEAD USB download gadget` will be displayed under the `lsusb` command. +1. Enter download mode: + - Hold the download button on the board. + - Connect a USB Type-C cable from the power port to the host. + - Release the button. +2. Confirm that `lsusb` lists `ID 2345:7654 T-HEAD USB download gadget`. +3. Flash the images: ```bash fastboot flash ram u-boot-with-spl-meles.bin fastboot reboot -# Pause here for 3-5 seconds to wait for Meles to restart +sleep 3 fastboot flash boot boot-meles-20250323_154525.ext4 fastboot flash root root-meles-20250323_154525.ext4 ``` ![fastboot-meles](/img/image-for-flash/fastboot-meles.png) -After the flashing is completed, it can be started normally. - - -### Potential Issues +After flashing, reboot to start from eMMC. -#### weak Wi-Fi signal / using external antenna by default +## Troubleshooting -On `Milk-V Meles` with the [latest kernel](https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250729/) (6.6.82 by the time writing this), the board is using the external antenna by default, rather than the on board ceramic/chip antenna. +### Weak Wi-Fi Signal on the Latest Kernel -As a result, the Wi-Fi signal is very weak without external antenna connected to the coax/ipex connector.Or not picking up any Wi-Fi signal at all. +When using the [latest RevyOS kernel](https://fast-mirror.isrc.ac.cn/revyos/extra/images/meles/20250729/) (6.6.82 at the time of writing), the board defaults to an external antenna. Without an antenna connected to the IPEX connector, Wi-Fi performance degrades significantly. +Use `gpiod` to switch to the onboard antenna: -You can try using 'sudo' to execute the 'GPIO' command to manually switch to the on-board antenna. - -``` +```bash sudo apt update && sudo apt upgrade -y -sudo apt install -y gpiod # Install the gpiod tool. -sudo gpioset 5 24=1 # Set pin 24 of chip 5 to high level. +sudo apt install -y gpiod +sudo gpioset 5 24=1 ``` :::warning - -You need to re-execute after reboot! - +Reapply the GPIO setting after each reboot. ::: +## User Credentials -### User Login +Default login credentials: -- Login account: `debian` +- Username: `debian` - Password: `debian` -When starting the image for the first time, you can log in with the above user password. - -For security reasons, please be sure to change your password after your first login to avoid any problems. - - - - +Change the password immediately after the first login for security. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx b/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx index f919469..42f6dfd 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx @@ -9,23 +9,21 @@ import { DownloadLink } from "@site/src/components/ImageLinks"; ## Introduction -[RevyOS](https://github.com/revyos) is a Debian based custom distribution developed and maintained by the RevyOS team under RuyiSDK, specifically optimized for the XuanTie chip ecosystem. +[RevyOS](https://github.com/orgs/revyos/repositories) is a Debian-based customised distribution developed and maintained by the RevyOS squad of the RuyiSDK team for the XuanTie chip ecosystem. -RevyOS is part of [RuyiSDK](https://github.com/ruyisdk), an open-source project initiated by PLCT Lab, aimed at providing a convenient and comprehensive development environment for RISC-V developers. It offers the latest hardware information and software support, such as details about supported hardware devices and software components like OS images (e.g., RevyOS), toolchains, and package managers. +RevyOS is part of [RuyiSDK](https://ruyisdk.org/), an open-source project initiated by [PLCT Lab](https://plctlab.org/zh/). The goal of RuyiSDK is to provide a convenient and comprehensive development environment for RISC-V developers. It delivers up-to-date hardware information and software support, including details on supported devices as well as software components such as images (e.g. RevyOS), toolchains, and package managers. -__RevyOS__ provides complete and thorough support for XuanTie chips including XuanTie C906, C910, C920, C908, with default integration of the XuanTie extended instruction sets and the GCC toolchain supporting RVV 1.0. It also features Glibc and Kernel optimized with RVV 1.0 instruction set. +__RevyOS__ offers comprehensive adaptation and optimisation for XuanTie C906, C910, C920, C908 and other processors. It ships with a GCC toolchain that supports the XuanTie extension instruction set and RVV 1.0 by default, together with Glibc and the kernel that are tuned for RVV 1.0. -Currently, __RevyOS__ meets basic user needs in office work, web browsing, and video watching. +At present, __RevyOS__ already satisfies day-to-day needs in office work, web browsing, and video playback. -Based on these customizations and optimizations, __RevyOS__ delivers excellent performance and a great experience on hardware platforms like Lichee Pi 4A, BeagleV-Ahead, and Milk-V Pioneer. +Thanks to these customisations and optimisations, __RevyOS__ delivers excellent performance and user experience on hardware platforms such as Milk-V Meles and Lichee Pi 4A. -## Image Download and Installation +## Image Download -The user version images of __RevyOS__ are currently updated on the [ISCAS (Institute of Software, Chinese Academy of Sciences)](https://mirror.iscas.ac.cn/revyos) / [Felix Finland Source](https://mirrors.felixc.at/revyos/) open-source mirror sites. +The user-edition images of __RevyOS__ are currently updated on the [ISCAS mirror](https://mirror.iscas.ac.cn/revyos/extra/images/). To obtain the latest image, visit the [download directory](https://mirror.iscas.ac.cn/revyos/extra/images/) and select the files that correspond to your device. After downloading, follow the [image flashing instructions](../Installation/intro/) for your board. -If you want to obtain the latest version of __RevyOS__, please select the corresponding device to download the appropriate U-Boot, boot partition, and root partition files. After downloading, please visit [Installation](../Installation/intro/) for the installation guide for your device. - -| Supported Devices | Image Download (Latest Version) | SD Card Support | +| Supported Devices | Image Download (Latest Version) | SD Card Support | | ---------------------------------- | -------------------------------------------------------------------------------- | --------- | | Lichee Pi 4A | {} | Supported | | Milk-V Meles | {} | Supported | @@ -43,9 +41,7 @@ If you want to obtain the latest version of __RevyOS__, please select the corres ~~For more details, see this document: [How to Enable Optimized GCC](../build/debian/enable_optimization_gcc/).~~ :::warning -When the toolchain of RevyOS is upgraded to gcc14, this repository is abandoned. -There will be a replacement for c910v repo later. Please wait for further updates. -（[Issue Track #124](https://github.com/revyos/revyos/issues/124)） +Since the RevyOS toolchain has been upgraded to GCC 14, the `c910v` repository used by the T-Head optimised GCC is deprecated. Please wait for subsequent updates. ([Tracking issue #124](https://github.com/revyos/revyos/issues/124)) ::: ## Changelog @@ -64,6 +60,3 @@ In this documentation, we provide guides for reference on building, adapting, an RevyOS has its own Telegram group: [Invitation Link](https://t.me/+Pi6px22-OsUxM2M1) -## Internship Recruitment - -We are currently recruiting test interns. For more information, visit: [RevyOS Team Test Intern Recruitment](https://github.com/plctlab/weloveinterns/blob/master/open-internships.md#j143-revyos%E5%B0%8F%E9%98%9F%E6%B5%8B%E8%AF%95%E5%AE%9E%E4%B9%A0%E7%94%9F20241111%E5%BC%80%E6%94%BE100%E5%90%8D) (Chinese only) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/issue.md b/i18n/en/docusaurus-plugin-content-docs/current/issue.md index b2c2ede..bbd6223 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/issue.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/issue.md @@ -1,6 +1,6 @@ # Submitting Issues and Known Issues -Thank you for using RevyOS! If you encounter any problems or discover bugs during use, please follow these steps: +Thank you for using RevyOS! If you run into problems, discover bugs, have feature requests, or simply want to make a wish, please refer to the information below. ## Submitting a New Issue @@ -19,20 +19,17 @@ Thank you for using RevyOS! If you encounter any problems or discover bugs durin Before submitting a new issue, we recommend checking our record of known issues: - Visit the Discussions page: [Known Compatibility Issues](https://github.com/orgs/revyos/discussions/83) -- Check if someone has already reported the same or a similar issue. If the issue already exists, you can: -- Add a comment to the corresponding issue or discussion to provide more information. +- Add a comment to the corresponding issue or discussion to provide further information so the testing team can follow up. ## Tips -- Ensure your issue has not been submitted previously. -- Providing detailed and complete information will help us resolve the issue faster. +- Provide complete and detailed information so the testing team can reproduce the issue quickly and help you resolve it sooner. ## Contact Us -If you would like to discuss any issues encountered during use, you can reach us through the following channels: +If you would like to discuss issues encountered during use, contact us via: -- Join the Telegram group: [Invitation Link](https://t.me/+Pi6px22-OsUxM2M1) -- Send an email to: [support@revyos](mailto:chenglongcan@iscas.ac.cn) +- Join the Telegram group: [Invitation Link](https://t.me/+Pi6px22-OsUxM2M1) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/env.mdx b/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/env.mdx index bfff665..f4bed07 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/env.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/env.mdx @@ -8,73 +8,63 @@ import TabItem from '@theme/TabItem'; # Basic Environment Setup -This section describes how to **set up an x86 computer and a LicheePi development board** to prepare for running models on the NPU or CPU of the board. +This guide configures **an x86 computer and a Lichee Pi development board** so that models can run on the board's NPU or CPU. -:::info[Why is an x86 machine required?] +:::info[Why do I still need an x86 machine?] +Before a model can run on the development board, you must use an x86 machine to convert generic models such as ONNX into computation graphs and glue code that are executable on the board's CPU/NPU via the `hhb` tool. The glue code and related application code must then be cross-compiled into binaries for the board. -To run models on the development board, it is first necessary to use the hhb tool on an x86 machine to convert general models such as ONNX into computation graphs and glue code executable by the board's CPU/NPU. The glue code and related application code must then be cross-compiled into binaries that can run on the board. - -Since x86 machines generally offer higher performance and the hhb tool only supports the x86 architecture, an additional x86 computer is required for model conversion. +Because x86 machines generally offer higher performance—and because the `hhb` tool only supports the x86 architecture—an additional x86 computer is required to complete the model conversion workflow. ::: ## Development Board Setup -Lichee Pi 4A is a development board launched by Sipeed based on the TH1520 chip. For basic out-of-the-box configuration, refer to the [official hardware documentation](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/2_unbox.html). The recommended operating system is [RevyOS version 20250729](https://fast-mirror.isrc.ac.cn/revyos/extra/images/lpi4a/20250729/). For instructions on flashing RevyOS, see the [installation guide](../../../Installation/intro). +Lichee Pi 4A is a development board produced by Sipeed that features the TH1520 SoC. For the basic out-of-the-box setup, consult the [official hardware guide](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/2_unbox.html). Flash [RevyOS version 20250729](https://fast-mirror.isrc.ac.cn/revyos/extra/images/lpi4a/20250729/) onto the board. See the [image flashing guide](../../../Installation/intro) for details. ### Installing Basic Tools -RevyOS does not include `pip` and other basic tools by default. Install them as follows: +By default, RevyOS does not include `pip` and several other fundamental tools, so install them first: ```shell-session debian@revyos-lpi4a:~$ sudo apt install python3-pip python3-venv wget curl git # Install required packages -debian@revyos-lpi4a:~$ mkdir npu # Create a Python virtual environment +debian@revyos-lpi4a:~$ mkdir npu # Create a directory for the Python virtual environment debian@revyos-lpi4a:~$ cd npu debian@revyos-lpi4a:~/npu$ python3 -m venv .venv debian@revyos-lpi4a:~/npu$ . .venv/bin/activate # Activate the virtual environment -(.venv) debian@revyos-lpi4a:~/npu$ # Now inside the virtual environment +(.venv) debian@revyos-lpi4a:~/npu$ # Prompt shows the active virtual environment ``` -If the installation and activation are successful, the command prompt should be prefixed with `(.venv)`, indicating the active virtual environment. +After activation, the shell prompt should display `(.venv)` to indicate the current virtual environment. -:::info[Why use a virtual environment?] -Unlike the [original Yuque documentation](https://www.yuque.com/za4k4z/yp3bry/tx9hcuw35s9x24po#Cv3Tw), this guide adds a section on creating a virtual environment. In the original, packages such as `shl-python` are installed system-wide, which may conflict with system Python packages managed by `apt` (e.g., `python3-*`). Using a virtual environment isolates packages installed via `pip` and prevents conflicts with `apt`. For details, see [PEP 668](https://peps.python.org/pep-0668/). +:::info[Why create a virtual environment?] +Unlike the [original Yuque article](https://www.yuque.com/za4k4z/yp3bry/tx9hcuw35s9x24po#Cv3Tw), this document adds a dedicated section for virtual environments. The original guide installs packages such as `shl-python` system-wide, which conflicts with the system Python packages managed by `apt` (e.g. `python3-*`). Using a virtual environment isolates packages installed via `pip` and avoids clashes with `apt`. See [PEP 668](https://peps.python.org/pep-0668/) for details. ::: ### Installing the SHL Library -:::note[About SHL] - -SHL (Structure of Heterogeneous Library) is a high-performance heterogeneous computing library provided by T-Head. Its main function interfaces use the CSI-NN2 API for the C-SKY CPU platform and provide a series of optimized binary libraries. [User Manual](https://www.xrvm.cn/document?temp=standard&slug=shl-user-manual) -::: - -Install the SHL library using `pip` within the virtual environment: - -:::caution[Version Compatibility] -The `shl-python` package is updated frequently, and the latest version may not be compatible with all boards or example code. -**It is important to install a version of `shl-python` that matches your board and the examples you are following.** -For example, for the LPI4A board, version `2.6.17` is known to be compatible with most provided examples. -Check your board documentation or example requirements for the recommended version. -::: - -To install a specific compatible version (e.g., `2.6.17`): - +:::note[What is SHL?] +SHL (Structure of Heterogeneous Library) is a high-performance heterogeneous computing library provided by T-Head. Its main function interfaces adopt the CSI-NN2 API for the XuanTie CPU platform and come with a collection of optimised binary libraries. Refer to the [user manual](https://www.xrvm.cn/document?temp=standard&slug=shl-user-manual) for more information. ::: -To install a specific compatible version (e.g., `2.6.17`): +Install SHL within the virtual environment using `pip`: +```shell-session +(.venv) debian@revyos-lpi4a:~/npu$ pip3 install shl-python -i https://pypi.tuna.tsinghua.edu.cn/simple +... +Successfully installed shl-python-3.2.2 +``` -:::note[Setting a PyPI Mirror] -The default PyPI server is located overseas, which may cause network issues in mainland China. Use the `-i` option to specify a temporary PyPI mirror. For more information, refer to [Tsinghua University PyPI Mirror Usage Guide](https://mirrors.tuna.tsinghua.edu.cn/help/pypi/) +:::note[Configure a PyPI mirror] +The default PyPI infrastructure is hosted overseas, which can lead to connectivity issues in mainland China. The `-i` argument lets you select an alternative mirror. For more instructions, see the [Tsinghua University PyPI mirror guide](https://mirrors.tuna.tsinghua.edu.cn/help/pypi/). ::: -After installation, use the SHL module's `--whereis` command to check the installation path. +After installation, query SHL's location with the `--whereis` option: ```shell-session {2} @@ -90,45 +80,43 @@ After installation, use the SHL module's `--whereis` command to check the instal -Based on the output path (as highlighted above), set the `LD_LIBRARY_PATH` environment variable to specify the dynamic library search path. For example: +Based on the reported path (highlighted above), set the `LD_LIBRARY_PATH` so the dynamic linker can find SHL's libraries: ```shell-session -$ export SHL_PATH=/home/debian/npu/.venv/lib/python3.11/site-packages/shl/install_nn2/th1520/lib # Use the path from above +$ export SHL_PATH=/home/debian/npu/.venv/lib/python3.11/site-packages/shl/install_nn2/th1520/lib # Use the path printed above ``` ```shell-session -$ export SHL_PATH=/home/debian/npu/.venv/lib/python3.11/site-packages/shl/install_nn2/c920/lib # Use the path from above +$ export SHL_PATH=/home/debian/npu/.venv/lib/python3.11/site-packages/shl/install_nn2/c920/lib # Use the path printed above ``` -Add it to the environment variables: - ```shell-session $ export LD_LIBRARY_PATH=$SHL_PATH:$LD_LIBRARY_PATH ``` -To make this setting persistent, add the above `export` command to your `~/.bashrc` or `~/.profile`. +Append the `export` command to `~/.bashrc` or `~/.profile` if you need the setting to persist. ### Installing HHB-onnxruntime -HHB-onnxruntime integrates the SHL backend (execution providers), enabling onnxruntime to utilize SHL's high-performance code optimized for C-SKY CPUs. +HHB-onnxruntime integrates the SHL backend (execution providers), allowing onnxruntime to reuse SHL's high-performance kernels tuned for XuanTie CPUs. ```shell-session @@ -146,13 +134,13 @@ $ pip install numpy-1.25.0-cp311-cp311-linux_riscv64.whl hhb_onnxruntime_c920-2. -:::note[About Github Network Proxy] -If you experience network issues accessing GitHub from mainland China, consider using a network proxy tool to accelerate access. +:::note[About GitHub network proxies] +If accessing GitHub from mainland China is slow or unreliable, consider enabling a network proxy to improve connectivity. ::: ### NPU Driver Configuration -Compared to CPU execution, NPU inference requires the NPU driver module `vha` to be loaded. Use `lsmod` to list loaded drivers: +Compared with CPU execution, NPU inference requires that the `vha` kernel module be loaded. Check the loaded modules with: ```shell-session {2-3} $ lsmod | grep vha @@ -160,35 +148,35 @@ vha 970752 0 img_mem 827392 1 vha ``` -If the `vha` module (highlighted above) is not listed, load it manually: +If `vha` (highlighted above) is absent, load it manually: ```shell-session $ sudo modprobe vha vha_info img_mem ``` -:::info[User-space NPU Driver Configuration] -In addition to the kernel driver, user-space drivers are also required for NPU execution. Check the `/usr/lib` directory for the following libraries: +:::info[NPU user-space driver configuration] +Besides the kernel driver, user-space components are required. Verify that `/usr/lib` already contains the following libraries: - `libimgdnn.so` - `libnnasession.so` - `libimgdnn_execute.so` -These libraries are pre-installed in RevyOS and generally do not require manual installation. +These libraries are preinstalled in RevyOS, so manual installation is normally unnecessary. ::: ### NPU Device Permission Configuration -After loading the NPU driver, the device `/dev/vha0` may require permission adjustment for user access. For convenience, set the device permission to 0666 (read/write for all users): +After the driver is loaded, you might need to adjust the permissions on `/dev/vha0` so regular users can access the device. For convenience, grant read/write access to all users: ```shell-session -$ sudo chmod 0666 /dev/vha0 # Set device permission to 0666 +$ sudo chmod 0666 /dev/vha0 # Set the device permission to 0666 ``` -For security, it is recommended to configure `udev` rules for device management. Consult AI or documentation for `udev` configuration. +For better security, configure `udev` rules to manage the device permissions; you can ask an AI assistant how to write the rules. ## x86 Machine Setup -Unlike the [original Yuque documentation](https://www.yuque.com/za4k4z/yp3bry/tx9hcuw35s9x24po#rVPRY), this guide uses a pre-built Docker image for installation. Please ensure Docker is installed on your computer. +Unlike the [original Yuque tutorial](https://www.yuque.com/za4k4z/yp3bry/tx9hcuw35s9x24po#rVPRY), this guide relies on a pre-built Docker image. Make sure Docker is installed on your x86 machine. ### Obtaining and Running the HHB Image @@ -197,21 +185,21 @@ $ docker pull hhb4tools/hhb:2.6.17 # Pull the HHB image $ docker run --rm -it hhb4tools/hhb:2.6.17 bash # Start a temporary HHB container ``` -:::warning[HHB Image Size] -The HHB image is large (~7GB). Downloading may take some time. Please ensure sufficient disk space. +:::warning[HHB image size] +The HHB image is large (about 7 GB). Downloading it may take time, so please wait patiently and confirm that you have sufficient disk space. ::: -After running the above commands, the container will start and you can operate within it. +After running the commands above, the container starts and you can work inside it. -:::warning[Container Filesystem] -The container filesystem is temporary. All files created inside the container will be deleted upon exit. It is recommended to copy generated files to the host or use a persistent container. +:::warning[Container filesystem] +The container filesystem is ephemeral. All files created inside the container are removed when it exits. Therefore, copy the generated files back to the host after you finish, or run a persistent container if required. -For more information, refer to the [Docker Official Documentation](https://docs.docker.com/get-started/overview/) or consult AI. +For more information about Docker, see the [official documentation](https://docs.docker.com/get-started/overview/) or consult an AI assistant. ::: ### Obtaining Example Code {#example-code} -The example code for this tutorial is available on [Github](https://github.com/zhangwm-pt/hhb-examples). Clone it locally using: +The example code accompanying this tutorial is hosted on [GitHub](https://github.com/zhangwm-pt/hhb-examples). Clone it locally: ```shell-session $ git clone https://github.com/zhangwm-pt/lpi4a-example.git @@ -219,10 +207,11 @@ $ git clone https://github.com/zhangwm-pt/lpi4a-example.git ### Obtaining OpenCV -This tutorial uses OpenCV 4.5, optimized for the C920 RISC-V vector spec 0.7.1. Precompiled binaries are available, and the source code can be downloaded from the [OCC download page](https://occ.t-head.cn/community/download?id=4112956065753141248). +This tutorial uses OpenCV 4.5, which has been tuned for the C920 processor and RISC-V vector specification 0.7.1. Prebuilt binaries are supplied, and the source code can be downloaded from the [OCC download page](https://occ.t-head.cn/community/download?id=4112956065753141248). -The precompiled C++ binaries are hosted on [Github](https://github.com/zhangwm-pt/prebuilt_opencv). To update the submodule in the [example program](#example-code), run: +The precompiled C++ binaries are stored on [GitHub](https://github.com/zhangwm-pt/prebuilt_opencv). To update the submodule in the [example program](#example-code), run: ```shell-session -$ # Assuming you are in the repository root -$ git submodule update --init -- \ No newline at end of file +$ # Assume you are in the repository root +$ git submodule update --init --recursive +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/object-detection/yolov5.mdx b/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/object-detection/yolov5.mdx new file mode 100644 index 0000000..710f668 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/object-detection/yolov5.mdx @@ -0,0 +1,215 @@ +--- +title: YOLOv5 +description: Tutorial for Running the YOLOv5 Model on the RevyOS System +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## YOLOv5 + +This tutorial explains how to run the YOLOv5 model on the RevyOS system using either the CPU or the NPU. + +:::info[Initial Environment Configuration] +Before proceeding with this tutorial, please ensure you have completed the [Environment Configuration](../../env) section. +::: + +## Obtaining Example Code + +The example code accompanying this tutorial is available on [GitHub](https://github.com/zhangwm-pt/lpi4a-example). Clone it to your local machine using the `git` command. + +```shell-session +$ git clone https://github.com/zhangwm-pt/lpi4a-example.git +``` + +The code relevant to this tutorial is located in the `detection/yolov5` directory. + +## Model Acquisition + +The model used in this tutorial originates from the YOLOv5 repository and can be exported via its `export.py` script. +```python +$ git clone https://github.com/ultralytics/yolov5.git +$ cd yolov5 +$ pip3 install ultralytics +$ python3 export.py --weights yolov5n.pt --include onnx --imgsz 384 640 +``` + +:::note[About Github Network Proxy] +If you experience network issues when accessing GitHub from mainland China, consider using a network proxy tool to accelerate access. +::: + +## Model Conversion and Compilation + +After completing the environment configuration, you can use HHB to compile the model into an executable program for the C920. + +This tutorial uses the YOLOv5n detection model. For YOLOv5n, the HHB command truncates the graph at the final convolutional layer, and the subsequent post-processing is delegated to the provided `yolov5n.c` file. + +Navigate to the `detection/yolov5` directory and execute the following command: + + + +```shell-session +$ hhb -D --model-file yolov5n.onnx --data-scale-div 255 \ + --board c920 --input-name "images" --output-name \ + "/model.24/m.0/Conv_output_0;/model.24/m.1/Conv_output_0;/model.24/m.2/Conv_output_0" \ + --input-shape "1 3 384 640" --quantization-scheme float16 +``` + + +```shell-session +$ hhb -D --model-file yolov5n.onnx --data-scale-div 255 \ + --board th1520 --input-name "images" --output-name \ + "/model.24/m.0/Conv_output_0;/model.24/m.1/Conv_output_0;/model.24/m.2/Conv_output_0" \ + --input-shape "1 3 384 640" --calibrate-dataset kite.jpg \ + --quantization-scheme "int8_asym" +``` + + + +:::info[About Parameters] +- `-D`: Directs HHB to stop after generating the executable file +- `--model-file`: Specifies the input model file +- `--data-mean`: Specifies the mean value +- `--data-scale`: Specifies the scaling value +- `--board`: Specifies the target platform as C920 (CPU) or TH1520 (NPU) +- `--input-name`: Names the model input tensor +- `--output-name`: Names the model output tensor +- `--input-shape`: Specifies the model input tensor shape +- `--postprocess`: Configures the post-processing behavior for HHB-generated glue code; `save_and_top5` saves the outputs and prints the top-5 results +- `--quantization-scheme`: Specifies the quantization type + +You can run `hhb --help` to view all available parameters and options. +::: + +:::info[About HHB Generated Files] +After the command finishes, the current directory contains a newly created `hhb_out` subdirectory with files such as: + +- `hhb.bm`: HHB model file containing quantized weight data +- `hhb_runtime`: Executable file for the development board, compiled from the C sources in this directory +- `main.c`: Reference entry point for the HHB-generated example program +- `model.c`: HHB model structure representation file +- `model.params`: Model weight file +- `io.c`: HHB-generated example program providing file I/O helper functions +- `io.h`: HHB-generated example program providing file I/O function declarations +- `process.c`: HHB-generated example program providing image preprocessing functions +- `process.h`: HHB-generated example program providing image preprocessing function declarations +::: + +### GCC Post-processing Compilation + +This tutorial implements the latter portion of the model and NMS in C so that post-processing yields detection results for the output image. +```C +$ riscv64-unknown-linux-gnu-gcc yolov5n.c -o yolov5n_example hhb_out/io.c \ + hhb_out/model.c -Wl,--gc-sections -O2 -g -mabi=lp64d -I hhb_out/ -L \ + /usr/local/lib/python3.8/dist-packages/hhb/install_nn2/th1520/lib/ \ + -lshl -L /usr/local/lib/python3.8/dist-packages/hhb/prebuilt/decode/install/lib/rv \ + -L /usr/local/lib/python3.8/dist-packages/hhb/prebuilt/runtime/riscv_linux \ + -lprebuilt_runtime -ljpeg -lpng -lz -lstdc++ -lm -I \ + /usr/local/lib/python3.8/dist-packages/hhb/install_nn2/th1520/include/ -mabi=lp64d \ + -march=rv64gcv0p7_zfh_xtheadc -Wl,-unresolved-symbols=ignore-in-shared-libs -I \ + /usr/local/lib/python3.8/dist-packages/hhb/install_nn2/th1520/include/shl_public/ \ + -I /usr/local/lib/python3.8/dist-packages/hhb/install_nn2/th1520/include/csinn/ +``` + +In the example code, the SHL library is linked; for example, its installation directory can be `/usr/local/lib/python3.8/dist-packages/shl`. + +:::info[Option Descriptions] +- `-Ihhb_out -I/usr/local/lib/python3.8/dist-packages/shl/install_nn2/c920/include/`: Header search paths that include the SHL headers +- `-L/usr/local/lib/python3.8/dist-packages/shl/install_nn2/c920/lib`: Library search path that points to the precompiled SHL binaries +- `-static`: Enables static linking +- `-o yolov5n_example`: Specifies the name of the generated executable +::: + +After successful compilation, a `yolov5n_example` file will be generated in the example directory. + +## Execution + +After cross-compilation, copy the required files to the development board directory. + +For example, with board IP 10.63.x.x using /demo directory, copy the example program directory using scp: + +```bash +scp -r yolov5n th1520@10.63.x.x:/demo/ +``` + +When executing from the Linux command line on the board's terminal, the terminal output reports the following stages: +1. Preprocessing: Scale and pad the original image to 384 × 640 +2. Model execution and post-processing: Perform model inference and apply NMS +3. Bounding box drawing: Render the detection results on the 384 × 640 image + +:::info[Required Execution Files] +- `kite.jpg`: Input image +- `image_preprocessed.bin`: Preprocessing intermediate result +- `yolov5n_example`: Model execution file compiled on the x86 host with GCC +- `hhb_out/hhb.bm`: Model execution file generated on the x86 host by HHB +- `detect.txt`: Post-processing output file containing 4 detected objects +- `kite_result.jpg`: Output image with detection boxes added +::: + +## Reference Results + +The input image shows a family of three flying a kite. YOLOv5 is expected to detect three people and one kite. +![Input Image](/img/image-for-flash/yolov5.png) +![Detection Image](/img/image-for-flash/yolov5_2.png) + +When the example runs successfully, the terminal prints output similar to the following: + + + +```shell-session +$ .python3 inference.py + ********** preprocess image ********** + ******* run yolov5 and postprocess ******* +Run graph execution time: 401.13336ms, FPS=2.49 +detect num: 4 +id: label score x1 y1 x2 y2 +[0]: 0 0.899609 274.486389 158.510849 359.157715 332.118591 +[1]: 0 0.880201 80.017410 184.470093 190.141861 349.840637 +[2]: 0 0.844358 219.474869 221.711838 283.615723 333.643250 +[3]: 33 0.667759 67.194008 174.118088 203.020660 220.667618 + ********** draw bbox ********** +[274.486389, 158.510849, 359.157715, 332.118591, 0.899609, 0] +[80.01741, 184.470093, 190.141861, 349.840637, 0.880201, 0] +[219.474869, 221.711838, 283.615723, 333.64325, 0.844358, 0] +[67.194008, 174.118088, 203.02066, 220.667618, 0.667759, 33] +``` + + +```shell-session +$ python3 inference.py + ********** preprocess image ********** + ******* run yolov5 and postprocess ******* +INFO: NNA clock:1001624 [kHz] +INFO: Heap :anonymous (0x2) +INFO: Heap :dmabuf (0x2) +INFO: Heap :unified (0x5) +WARNING: Mapping to the on chip ram failed (128 > 0), continuing... +FATAL: Importing 737280 bytes of CPU memory has failed (Invalid argument) +Run graph execution time: 11.96299ms, FPS=83.59 +detect num: 4 +id: label score x1 y1 x2 y2 +[0]: 0 0.895277 273.492188 161.245056 359.559814 330.644257 +[1]: 0 0.887368 79.860062 179.181244 190.755692 354.304474 +[2]: 0 0.815214 222.054565 224.477600 279.828979 333.717285 +[3]: 33 0.563324 67.625580 173.948883 201.687988 219.065765 + ********** draw bbox ********** +[273.492188, 161.245056, 359.559814, 330.644257, 0.895277, 0] +[79.860062, 179.181244, 190.755692, 354.304474, 0.887368, 0] +[222.054565, 224.4776, 279.828979, 333.717285, 0.815214, 0] +[67.62558, 173.948883, 201.687988, 219.065765, 0.563324, 33] +``` + + diff --git a/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/object-detection/yolox.mdx b/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/object-detection/yolox.mdx new file mode 100644 index 0000000..2ee1438 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/object-detection/yolox.mdx @@ -0,0 +1,111 @@ +--- +title: YOLOX +description: Tutorial for Running the YOLOX Model on the RevyOS System +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +## YOLOX + +This tutorial demonstrates how to deploy the YOLOX object detection model on the **LicheePi 4A** and implement efficient inference using **HHB-onnxruntime**. + + +:::info[Initial Environment Configuration] +Before proceeding with this tutorial, please ensure you have completed the [Environment Configuration](../../env) section. +::: + +## Obtaining Example Code + +The example code accompanying this tutorial is available on [GitHub](https://github.com/zhangwm-pt/lpi4a-example). Clone it to your local machine using the `git` command. + +```shell-session +$ git clone https://github.com/zhangwm-pt/lpi4a-example.git +``` +The code relevant to this tutorial is located in the `detection/yolox` directory. + +## Model Acquisition + +The model we use is from [Megvii-BaseDetection/YOLOX](https://github.com/Megvii-BaseDetection/YOLOX). You can download the YOLOX model using the following commands: + +```shell-session +$ git clone https://github.com/Megvii-BaseDetection/YOLOX.git +$ cd YOLOX/demo/ONNXRuntime +$ wget https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.1rc0/yolox_s.onnx +``` + +:::note[About Github Network Proxy] +If you experience network issues when accessing GitHub from mainland China, consider using a network proxy tool to accelerate access. +::: + +## Source Code Modification +Modify the beginning of the file demo/ONNXRuntime/onnx_inference.py by adding lines four and five as shown below: +```python +#!/usr/bin/env python3 +# Copyright (c) Megvii, Inc. and its affiliates. + ++import sys ++sys.path.insert(0, "../../") + +import argparse +import os +``` +The code uses sys.path.insert to specify the search path, thereby eliminating the need to install the YOLOX package from source. + +## Environment Preparation + +The YOLOX example in this tutorial depends on multiple Python packages. Download the pre-compiled Python packages: +```shell-session +$ git clone -b python3.11 https://github.com/zhangwm-pt/prebuilt_whl.git +$ cd prebuilt_whl +``` + +Alternatively, manually download and install the packages using: +``` +$ pip3 install numpy-1.25.0-cp311-cp311-linux_riscv64.whl +$ pip3 install opencv_python-4.5.4+4cd224d-cp311-cp311-linux_riscv64.whl +$ pip3 install kiwisolver-1.4.4-cp311-cp311-linux_riscv64.whl +$ pip3 install Pillow-9.5.0-cp311-cp311-linux_riscv64.whl +$ pip3 install matplotlib-3.7.2.dev0+gb3bd929cf0.d20230630-cp311-cp311-linux_riscv64.whl +$ pip3 install pycocotools-2.0.6-cp311-cp311-linux_riscv64.whl +$ pip3 install loguru-0.7.0-py3-none-any.whl +$ pip3 install MarkupSafe-2.1.3-cp311-cp311-linux_riscv64.whl +$ pip3 install torch-2.0.0a0+gitc263bd4-cp311-cp311-linux_riscv64.whl +$ pip3 install torchvision-0.15.1a0-cp311-cp311-linux_riscv64.whl +$ pip3 install psutil-5.9.5-cp311-abi3-linux_riscv64.whl +$ pip3 install tqdm-4.65.0-py3-none-any.whl +$ pip3 install tabulate-0.9.0-py3-none-any.whl +``` +During installation, pip automatically resolves any additional pure Python dependencies from the official source. + + +## Inference Execution + +Within the example directory, run the `onnx_inference.py` sample: + +```bash +$ python3 onnx_inference.py -m yolox_s.onnx -i ../../assets/dog.jpg -o outdir -s 0.7 --input_shape 640,640 +``` + +:::info[About Parameters] + +- `-m`: Specifies the model file +- `-i`: Specifies the input image path +- `-o`: Specifies the output directory +- `-s`: Sets the detection threshold +- `--input_shape`: Specifies the input image dimensions +::: + +## Reference Results + +In this tutorial, the input is as shown in the following figure. Under a threshold of 0.7, the expected detection results of YOLOX are as follows. + +![Input Image](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/assets/application/yolox_detection_soccer_input.jpg) + +After normal execution of the example, a result image dog.jpg will be generated in the outdir directory. The image will show detected objects with bounding boxes and probability annotations, as shown in the image below: + +![Detection Results](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/assets/application/yolox_detection_soccer_output.jpg) + +The detection identifies two people and one soccer ball. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/bert-on-npu.md b/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/bert-on-npu.md deleted file mode 100644 index 876c848..0000000 --- a/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/bert-on-npu.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: Running BERT Model on LicheePi 4A TH1520 NPU (HHB Quantization & Inference) -sidebar_position: 3 ---- - -# Running BERT Model on LicheePi 4A TH1520 NPU (HHB Quantization & Inference) - -This article details how to deploy and run the BERT model on the TH1520 NPU of Licheepi 4A, including the complete process of quantization and inference using the HHB tool. - -## BERT Model Introduction - -BERT (Bidirectional Encoder Representations from Transformers) is a pre-trained language model widely used in natural language processing. - -This tutorial introduces how to use the **HHB (Heterogeneous Hybrid Binary)** toolchain on the **Licheepi 4A TH1520 development board** to compile and run the **BERT model** for reading comprehension inference tasks. - ------- - -## **1. Environment Preparation** - -### **1.1. Ensure HHB is Installed** - -After setting up the NPU-related environment according to the [documentation](https://github.com/jason-hue/plct/blob/main/%E6%B5%8B%E8%AF%95%E6%96%87%E6%A1%A3/LIcheepi%204A%E9%83%A8%E7%BD%B2%20mobilenetv2%20%E6%A8%A1%E5%9E%8B%E5%AE%8C%E6%88%90%E5%9B%BE%E5%83%8F%E5%88%86%E7%B1%BB%E7%9A%84%E7%A4%BA%E4%BE%8B.md), enter the Docker image of the HHB environment. - -### **1.2. Download the BERT Model and Sample Code** - -First, obtain the model. The model used in this tutorial is from the Google BERT repository, converted to an ONNX version of the BERT model. It can be downloaded to the `/home/example/c920/bert_small` directory using the following command: - -```bash -cd /home/example/c920/bert_small - -wget https://github.com/zhangwm-pt/bert/releases/download/onnx/bert_small_int32_input.onnx -``` - ------- - -## **2. Compile the BERT Model Using HHB** - -To cross-compile the ONNX model into an executable program for NPU, you need to use the hhb command. Note that NPU only supports 8-bit or 16-bit fixed-point operations; this example specifies int8 asymmetric quantization. When compiling, you need to first enter the example directory. - -### **2.1. Enter the BERT Directory** - -```bash -cd /home/example/c920/bert_small -``` - -### **2.2. Run HHB Compilation** - -Note that you must use the toolchain here, otherwise the compiled binary file will not run on LicheePi4A. - -```bash -export PATH=/tools/Xuantie-900-gcc-linux-5.10.4-glibc-x86_64-V2.6.1-light.1/bin/:$PATH -``` - -```bash -hhb --model-file bert_small_int32_input.onnx --input-name "input_ids;input_mask;segment_ids" --input-shape '1 384;1 384;1 384' --output-name "output_start_logits;output_end_logits" --board c920 --quantization-scheme "float16" --postprocess save_and_top5 -D --without-preprocess -``` - -### **2.3. Option Descriptions** - -| Option | Description | -| ----------------------- | ---------------------------------- | -| `-D` | Generate executable file | -| `--model-file` | Specify ONNX BERT model | -| `--input-name` | Model input name | -| `--output-name` | Model output name | -| `--input-shape` | Input data shape | -| `--board` | Specify target platform (TH1520) | -| `--quantization-scheme` | Quantization method (int8/float16) | -| `--postprocess` | Output results and print top5 | - ------- - -## **3. Generated Files** - -After HHB runs, a `hhb_out/` directory is generated in the current directory, containing: - -``` -hhb_out/ -├── hhb.bm # Quantized model file -├── hhb_runtime # Executable inference program -├── main.c # Reference example entry point -├── model.c # Model structure code -├── model.params # Quantized weight data -├── io.c / io.h # File I/O helper code -├── process.c / process.h # Preprocessing functions -``` - ------- - -## **4. Transfer to the Development Board** - -Copy the compiled model and files to the host machine: - -```bash -docker cp 65f872394fa5837ef2c24ade731b152da074ac6091f0766c04ac54092ff32780:/home/example/c920/bert_small C:\Users\knifefire\Downloads\ -``` - -Then upload to the development board, and on the development board: - -```bash -cd ~/bert_small -chmod +x hhb_out/hhb_runtime # Grant execution permission -``` - ------- - -## **5. Run Inference** - -```bash -python3 inference.py -``` - ------- - -## **6. Expected Output** - -BERT processing questions from the SQuAD dataset: - -The reference input in this example comes from the SQuAD dataset, which is a reading comprehension dataset consisting of questions posed on a set of Wikipedia articles, where the answer to each question is a segment of text from the corresponding reading passage or the question. -The input for this example is as follows, where the article content describes a football game, and the question is about who participated in the game. - -```bash -[Context]: Super Bowl 50 was an American football game... -[Question]: Which NFL team represented the AFC at Super Bowl 50? -``` - -**BERT Output Answer** - -Based on the reading comprehension result, the expected output will be Denver Broncos - -``` -[Answer]: Denver Broncos -``` - -**Execution Time** - -``` -Run graph execution time: 1713.15491ms, FPS=0.58 -``` - -##### Reference Output: - -```bash -# python3 inference.py - ********** preprocess test ********** -[Context]: Super Bowl 50 was an American football game to determine the champion of the National Football League (N -FL) for the 2015 season. The American Football Conference (AFC) champion Denver Broncos defeated the National Footba -ll Conference (NFC) champion Carolina Panthers 24–10 to earn their third Super Bowl title. The game was played on Fe -bruary 7, 2016, at Levi's Stadium in the San Francisco Bay Area at Santa Clara, California. As this was the 50th Sup -er Bowl, the league emphasized the "golden anniversary" with various gold-themed initiatives, as well as temporarily - suspending the tradition of naming each Super Bowl game with Roman numerals (under which the game would have been k -nown as "Super Bowl L"), so that the logo could prominently feature the Arabic numerals 50. -[Question]: Which NFL team represented the AFC at Super Bowl 50? - ******* run bert ******* -Run graph execution time: 1713.15491ms, FPS=0.58 - -=== tensor info === -shape: 1 384 -data pointer: 0x183d60 - -=== tensor info === -shape: 1 384 -data pointer: 0x185380 - -=== tensor info === -shape: 1 384 -data pointer: 0x1869a0 - -=== tensor info === -shape: 1 384 -data pointer: 0x2a8610 -The max_value of output: 3.826172 -The min_value of output: -9.968750 -The mean_value of output: -8.412353 -The std_value of output: 5.128320 - ============ top5: =========== - 46: 3.826172 - 57: 3.142578 - 39: 1.303711 - 38: 1.179688 - 27: 0.624512 - -=== tensor info === -shape: 1 384 -data pointer: 0x2a8300 -The max_value of output: 3.617188 -The min_value of output: -9.625000 -The mean_value of output: -7.798176 -The std_value of output: 4.820137 - ============ top5: =========== - 47: 3.617188 - 58: 3.482422 - 32: 2.523438 - 29: 1.541992 - 41: 1.473633 - ********** postprocess ********** -[Answer]: Denver Broncos -``` - -With this, you have successfully run **BERT quantized inference** on the **Licheepi4A development board**! 🚀 - -Reference document: https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/8_application.html \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/mobilenetv2-image-classification.md b/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/mobilenetv2-image-classification.md deleted file mode 100644 index 381564e..0000000 --- a/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/mobilenetv2-image-classification.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Deploying MobileNetV2 Model on LicheePi 4A for Image Classification -sidebar_position: 2 ---- - -# Deploying MobileNetV2 Model on LicheePi 4A for Image Classification - -This article will introduce how to deploy the MobileNetV2 model on Licheepi 4A for image classification tasks. - -## Prerequisites - -- Licheepi 4A hardware device -- RevyOS operating system -- Basic machine learning knowledge - -## Model Introduction - -MobileNetV2 is a lightweight deep learning model designed for mobile and edge devices, offering high efficiency and good performance. - -This tutorial demonstrates how to deploy the mobilenetv2 model on the LicheePi4A platform for image classification. - -The tutorial includes: - -- Using HHB to compile onnx models into binaries usable on LicheePi4A -- Using the C++ version of OpenCV on LicheePi4A for preprocessing the mobilenetv2 model -- Differences between using CPU and NPU on LicheePi4A - -### NPU Environment Configuration - -First, you need to install a Python virtual environment, then use pip3 to install Python packages. -Use the following commands to install the venv package for creating a Python virtual environment (using the root directory as an example): - -```bash -sudo apt install python3.11-venv -python3 -m venv venv -source venv/bin/activate -``` - -#### SHL Library Installation - -Install using pip - -```bash -pip3 install shl-python -``` - -After installation, use --whereis to check the installation location - -```bash -python3 -m shl --whereis th1520 -# If using pure CPU inference, replace with python3 -m shl --whereis c920 -``` - -Based on the printed location, copy the dynamic libraries in the directory to the /usr/lib directory. For example, if it prints: - -```bash -/home/sipeed/ort/lib/python3.11/site-packages/shl/install_nn2/th1520 -``` - -You can use the copy command: - -```bash -sudo cp -r /home/sipeed/ort/lib/python3.11/site-packages/shl/install_nn2/th1520/lib/* /usr/lib/ -``` - -#### HHB-onnxruntime Installation - -HHB-onnxuruntime is ported with the SHL backend (execution providers), allowing onnxruntime to reuse the high-performance optimization code for T-Head CPU in SHL. - -CPU version - -```bash -wget https://github.com/zhangwm-pt/onnxruntime/releases/download/riscv_whl_v2.6.0/hhb_onnxruntime_c920-2.6.0-cp311-cp311-linux_riscv64.whl -pip install hhb_onnxruntime_c920-2.6.0-cp311-cp311-linux_riscv64.whl -``` - -NPU version - -```bash -wget https://github.com/zhangwm-pt/onnxruntime/releases/download/riscv_whl_v2.6.0/hhb_onnxruntime_th1520-2.6.0-cp311-cp311-linux_riscv64.whl -pip install hhb_onnxruntime_th1520-2.6.0-cp311-cp311-linux_riscv64.whl -``` - -#### **x86 Host Configuration** - -After installing Docker, open the terminal in the Docker application and enter: - -```bash -docker pull hhb4tools/hhb:2.4.5 -``` - -After pulling the image, use the following commands to enter the Docker image: - -```bash -docker run -itd --name=your.hhb2.4 -p 22 "hhb4tools/hhb:2.4.5" -docker exec -it your.hhb2.4 /bin/bash -``` - -After entering the Docker image, you can use the following command to confirm the HHB version: - -```bash -hhb --version -``` - -After entering the Docker image, you also need to configure the cross-compilation environment. Note that you must use the toolchain here, otherwise the compiled binary file will not run on LicheePi4A. - -```bash -export PATH=/tools/Xuantie-900-gcc-linux-5.10.4-glibc-x86_64-V2.6.1-light.1/bin/:$PATH -``` - -![image-20250227142739955](https://raw.githubusercontent.com/jason-hue/plct/main/image-20250227142739955.png) - -At this point, the HHB environment setup is initially complete. - -### Deploying MobileNetV2 - -Enter the docker container - -First, get the model for this tutorial, download it to the example directory `/home/example/th1520_npu/onnx_mobilenetv2_c++`: -[mobilenetv2-12.onnx](https://github.com/onnx/models/raw/main/validated/vision/classification/mobilenet/model/mobilenetv2-12.onnx) - -And get the library files needed for the optimized version of OpenCV used in this tutorial, go to [github repository download](https://xuantie.t-head.cn/community/download?id=4112956065753141248) and download to the parent directory `/home/example/th1520_npu/`. - -```bash -cd /home/example/th1520_npu/ -git clone https://github.com/zhangwm-pt/prebuilt_opencv.git -``` - -#### Compilation - -**HHB model compilation:** -To cross-compile the ONNX model into an executable program for NPU, you need to use the hhb command. Note that NPU only supports 8-bit or 16-bit fixed-point operations; this example specifies int8 asymmetric quantization. When compiling, you need to first enter the example directory `/home/example/th1520_npu/onnx_mobilenetv2_c++`: - -```bash -cd /home/example/th1520_npu/onnx_mobilenetv2_c++ -hhb -D --model-file mobilenetv2-12.onnx --data-scale 0.017 --data-mean "124 117 104" --board th1520 --postprocess save_and_top5 --input-name "input" --output-name "output" --input-shape "1 3 224 224" --calibrate-dataset persian_cat.jpg --quantization-scheme "int8_asym" -``` - -Option descriptions: - -- -D: Specify that the HHB process executes until the executable file is generated -- --model-file: Specify the mobilenet model already downloaded in the current directory -- --data-mean: Specify mean values -- --data-scale: Specify scaling value -- --board: Specify the target platform as th1520 -- --input-name: Model input name -- --output-name: Model output name -- --input-shape: Model input size -- --postprocess: Save output results and print top5 results -- --calibrate-dataset: Specify the calibration image needed for quantization -- --quantization-scheme: Specify the quantization method as int8 asymmetric - -After the command is executed, a hhb_out subdirectory will be generated in the current directory, containing hhb_runtime, model.c, and other files: - -- hhb.bm: HHB model file, including quantized weight data and other information -- hhb_runtime: Executable file for the th1520 platform, compiled from C files in the directory -- main.c: Temporary file, reference entry point for the example program -- model.c: Temporary file, model structure file, related to the model structure -- model.params: Temporary file, weight values -- io.c: Temporary file, auxiliary functions for reading and writing files -- io.h: Temporary file, declarations of auxiliary functions for reading and writing files -- process.c: Temporary file, image preprocessing functions -- process.h: Temporary file, declarations of image preprocessing functions - -For more detailed HHB option descriptions, refer to the command line option description in the [HHB User Manual](https://www.yuque.com/za4k4z/oxlbxl/keyg70qggt5n3fpa). - -**g++ example compilation:** - -```bash -riscv64-unknown-linux-gnu-g++ main.cpp -I../prebuilt_opencv/include/opencv4 -L../prebuilt_opencv/lib -lopencv_imgproc -lopencv_imgcodecs -L../prebuilt_opencv/lib/opencv4/3rdparty/ -llibjpeg-turbo -llibwebp -llibpng -llibtiff -llibopenjp2 -lopencv_core -ldl -lpthread -lrt -lzlib -lcsi_cv -latomic -static -o mobilenetv2_example -``` - -After the compilation command is executed correctly, a mobilenetv2_example file will be generated in the example directory. - -#### Execution - -After cross-compilation is complete, you can copy the files needed for program execution to the directory on the development board. - -Transfer the folder from docker to the host machine: - -```bash -docker cp 65f872394fa5837ef2c24ade731b152da074ac6091f0766c04ac54092ff32780:/home/example/th1520_npu/onnx_mobilenetv2_c++ C:\Users\knifefire\Downloads\ -``` - -Then upload it to the development board. - -First, check if the driver is loaded on the development board: - -```shell -lsmod -``` - -If the output includes the three modules `img_mem`, `vha`, and `vha_info`, the NPU driver is successfully loaded. - -Manually load the NPU driver: - -```bash -sudo insmod /lib/modules/5.10.113-th1520/kernel/drivers/nna/img_mem/img_mem.ko - -sudo modprobe vha onchipmem_phys_start=0xffe0000000 onchipmem_size=0x100000 freq_khz=792000 - -sudo insmod /lib/modules/5.10.113-th1520/kernel/drivers/nna/vha/vha_info.ko - -sudo chmod a+rw /dev/vha0 -``` - -Refer to the [YOLOX section](https://github.com/jason-hue/plct/blob/main/%E6%B5%8B%E8%AF%95%E6%96%87%E6%A1%A3/%E5%9C%A8%20LicheePi%204A%20%E4%B8%8A%E9%83%A8%E7%BD%B2%20YOLOX%20%E5%B9%B6%E4%BD%BF%E7%94%A8%20HHB-onnxruntime%20%E8%BF%9B%E8%A1%8C%E6%8E%A8%E7%90%86.md) to install and configure the Python virtual environment - -Run the compiled example in the corresponding directory on the development board: - -```bash -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/th1520/lib -./mobilenetv2_example -``` - -After execution, the terminal will prompt the stages being executed: - -1. Preprocessing -2. Model execution -3. Post-processing - -Files used by mobilenetv2_example: - -- persian_cat.jpg: Input image -- input_img.bin: Intermediate result generated from the input image during the preprocessing stage -- hhb_out/hhb_runtime: File used during model execution, generated by HHB on the x86 host -- hhb_out/hhb.bm: File used during model execution, generated by HHB on the x86 host -- input_img.bin_output0_1_1000.txt: Output file from the model execution stage, including 1000 result values output by the model execution - -#### Reference Results: - -```bash -(venv) sipeed@revyos-lpi4a:~/onnx_mobilenetv2_c++$ ./mobilenetv2_example - ********** preprocess image ********** - ********** run mobilenetv2 ********** -INFO: NNA clock:792000 [kHz] -INFO: Heap :ocm (0x18) -INFO: Heap :anonymous (0x2) -INFO: Heap :dmabuf (0x2) -INFO: Heap :unified (0x5) -FATAL: Importing 150528 bytes of CPU memory has failed (wrong memory alignment) -Run graph execution time: 15.03903ms, FPS=66.49 - -=== tensor info === -shape: 1 3 224 224 -data pointer: 0x2b4aca0 - -=== tensor info === -``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/yolox-deployment.md b/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/yolox-deployment.md deleted file mode 100644 index 55bdd2a..0000000 --- a/i18n/en/docusaurus-plugin-content-docs/current/typical-applications/yolox-deployment.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Deploying YOLOX on LicheePi 4A and Inference Using HHB-onnxruntime -sidebar_position: 5 ---- - -# Deploying YOLOX on LicheePi 4A and Inference Using HHB-onnxruntime - -This article provides a detailed guide on how to deploy the YOLOX object detection model on LicheePi 4A and perform efficient inference using HHB-onnxruntime. - -## YOLOX Introduction - -YOLOX is an efficient object detection algorithm that offers excellent speed performance while maintaining high accuracy, making it very suitable for deployment on edge devices. - -## 1. Environment Preparation - -### 1.1 Hardware Preparation - -- LicheePi 4A (LPi4A) development board -- MicroSD card (for storing the system) -- Power adapter -- USB serial debug tool (optional) - -### 1.2 Software Preparation - -- LicheePi 4A official Linux system -- Python 3.11 -- pip and necessary dependencies -- ONNX runtime (onnxruntime) -- HHB tools (can be used for model conversion) -- YOLOX model and its ONNX version - -```sh -# Update system -sudo apt update && sudo apt upgrade -y -``` - -Install some software for later use in the example - -```bash -sudo apt install wget git vim -``` - -Install SHL library - -```bash -wget https://github.com/T-head-Semi/csi-nn2/releases/download/v2.4-beta.1/c920.tar.gz - -tar xf c920.tar.gz - -cp c920/lib/* /usr/lib/riscv64-linux-gnu/ -rf -``` - -**Python Environment Configuration** -The LPi4A system comes with Python 3.11 pre-installed. You can confirm this with the following command - -```bash -python3 --version -``` - -The following examples all use Python 3.11. If you're using a different version, you'll need to modify the commands accordingly when installing dependencies. -Most Python dependencies can be installed using pip. You can install pip with the following command - -```bash -apt install python3-pip -``` - -Before installing other Python packages, first install the venv package to create a Python virtual environment - -```bash -apt install python3.11-venv -``` - -Create and activate a Python virtual environment - -```bash -cd /root -python3 -m venv ort -source /root/ort/bin/activate -``` - -At this point, the basic Python environment has been set up. Similar to other architectures, you can directly install pure Python packages via pip install. - -##### Install OpenCV - -```shell -sudo apt install python3 python3-pip -sudo apt install python3-opencv -sudo apt install libqt5gui5-gles -``` - -## 2. Obtain and Convert the YOLOX Model - -Execute the following steps on LPi4A: - -```sh -# Clone the YOLOX repository -git clone https://github.com/Megvii-BaseDetection/YOLOX.git - -cd YOLOX/demo/ONNXRuntime - -wget https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.1rc0/yolox_s.onnx -``` - -**Modify the Source Code** - -This tutorial will use HHB-onnxruntime to execute the model. In the onnxruntime example directory of the source code, modify the file demo/ONNXRuntime/onnx_inference.py by adding two lines at the beginning - -```bash -#!/usr/bin/env python3 -# Copyright (c) Megvii, Inc. and its affiliates. - -+import sys -+sys.path.insert(0, "../../") - -import argparse -import os -``` - -The code uses sys.path.insert to specify the search path, thus avoiding the need to install the YOLOX package from the source code. - -**Install Dependency Packages** - -The Python ecosystem for the RISC-V architecture is still lacking. In the future, when it's more complete, the dependencies in YOLOX can be installed directly through the [requirements.txt](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/requirements.txt) file. -The YOLOX example in this tutorial depends on many Python packages. Download the pre-compiled Python packages - -```bash -git clone -b python3.11 https://github.com/zhangwm-pt/prebuilt_whl.git -cd prebuilt_whl -``` - -You can process them manually in the following order. - -```bash -pip install numpy-1.25.0-cp311-cp311-linux_riscv64.whl - -pip install opencv_python-4.5.4+4cd224d-cp311-cp311-linux_riscv64.whl - -pip install kiwisolver-1.4.4-cp311-cp311-linux_riscv64.whl - -pip install Pillow-9.5.0-cp311-cp311-linux_riscv64.whl - -pip install matplotlib-3.7.2.dev0+gb3bd929cf0.d20230630-cp311-cp311-linux_riscv64.whl - -pip install pycocotools-2.0.6-cp311-cp311-linux_riscv64.whl - -pip3 install loguru-0.7.0-py3-none-any.whl - -pip3 install torch-2.0.0a0+gitc263bd4-cp311-cp311-linux_riscv64.whl - -pip3 install MarkupSafe-2.1.3-cp311-cp311-linux_riscv64.whl - -pip3 install torchvision-0.15.1a0-cp311-cp311-linux_riscv64.whl - -pip3 install psutil-5.9.5-cp311-abi3-linux_riscv64.whl - -pip3 install tqdm-4.65.0-py3-none-any.whl - -pip3 install tabulate-0.9.0-py3-none-any.whl -``` - -During the installation process, other pure Python dependency packages will be involved, which pip will automatically download from the official source. - -**Install HHB-onnxruntime** - -HHB-onnxruntime has ported the SHL backend (execution providers), allowing onnxruntime to reuse the high-performance optimization code for T-Head CPU in SHL. - -```bash -wget https://github.com/zhangwm-pt/onnxruntime/releases/download/riscv_whl/onnxruntime-1.14.1-cp311-cp311-linux_riscv64.whl -pip install onnxruntime-1.14.1-cp311-cp311-linux_riscv64.whl -``` - -**Execution** - -Execute the onnx_inference.py example in the example directory - -```bash -export PYTHONPATH=$PYTHONPATH:/root/YOLOX - -python3 onnx_inference.py -m yolox_s.onnx -i soccer.png -o outdir -s 0.3 --input_shape 640,640 -``` - -Parameter description: - -- -m: Specify the model -- -i: Specify the image -- -o: Specify the output directory -- -s: Specify the detection threshold -- --input_shape: Specify the image size used for detection - -**Reference Results** - -The input image in this tutorial, shown below, is a picture of players kicking a soccer ball. The expected detection result is two people and one soccer ball. - -> Image source: from the internet - -![yolox_detection_soccer_input.jpg](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/assets/application/yolox_detection_soccer_input.jpg) - -After the example is executed normally, a result image soccer.png will be generated in the outdir directory. The image will draw a box around the detected targets and label them with probabilities, as shown in the following image: - -![yolox_detection_soccer_output.jpg](https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/assets/application/yolox_detection_soccer_output.jpg) - -Reference document: - -https://wiki.sipeed.com/hardware/zh/lichee/th1520/lpi4a/8_application.html \ No newline at end of file diff --git a/static/img/image-for-flash/yolov5.png b/static/img/image-for-flash/yolov5.png new file mode 100644 index 0000000..1360eb6 Binary files /dev/null and b/static/img/image-for-flash/yolov5.png differ diff --git a/static/img/image-for-flash/yolov5_2.png b/static/img/image-for-flash/yolov5_2.png new file mode 100644 index 0000000..0d5c30e Binary files /dev/null and b/static/img/image-for-flash/yolov5_2.png differ