泰山派RK3566开发板OpenHarmony 4.0 Release SDK编译与烧录全流程指南
泰山派RK3566开发板OpenHarmony 4.0 Release SDK编译与烧录全流程指南
最近有不少朋友拿到了泰山派（TSPi）RK3566开发板，想在上面跑OpenHarmony 4.0系统，但面对庞大的源码和复杂的编译环境，感觉无从下手。别担心，今天我就带你走一遍完整的流程，从拉取源码、搭建Docker环境、编译SDK，到最终把系统烧录到板子上。整个过程我亲自跑过好几遍，把遇到的坑和需要注意的细节都整理出来了，保证你跟着做就能成功。
1. 源码获取与补丁应用
编译的第一步，当然是拿到源代码。OpenHarmony 4.0 Release是一个稳定的版本，咱们就从这里开始。
1.1 获取源码
首先，在你的Linux电脑上（推荐Ubuntu 20.04），找个合适的位置，打开终端，执行下面的命令来拉取代码。
mkdir -p OpenHarmony-v4.0-Release && cd OpenHarmony-v4.0-Release repo init -u https://gitee.com/openharmony/manifest -b refs/tags/OpenHarmony-v4.0-Release --no-repo-verify repo sync -c repo forall -c 'git lfs pull'简单解释一下这几条命令：
mkdir -p ... && cd ...：创建并进入一个名为OpenHarmony-v4.0-Release的目录，用来存放所有源码。repo init ...：初始化repo仓库，指定使用OpenHarmony 4.0 Release这个稳定分支的清单。repo sync -c：同步代码到本地，-c参数表示只同步当前分支。repo forall -c 'git lfs pull'：拉取大文件（比如一些预编译的工具链），这个步骤很重要，不然后面编译可能缺东西。
注意：一定要拉取这个特定标签（Tag）的代码，这是发布时完全一致的源码。如果拉取其他分支或主干的代码，后续打补丁时很容易出现不兼容的问题，编译失败就麻烦了。
这个过程会下载十几个G的数据，网速快的话也得等一阵子，可以去泡杯茶。
1.2 下载并应用补丁
OpenHarmony官方源码是通用的，要让它适配咱们的泰山派RK3566开发板，需要打上一个“补丁”。这个补丁包含了板子特定的配置和驱动。
步骤01：下载补丁补丁文件需要在泰山派的官方资料下载中心获取。你可以访问他们的Wiki站点，在下载中心找到名为OpenHarmony-v4.0-Release-xxxx.tar.gz的文件（xxxx是版本号），把它下载到你的电脑上。
步骤02：解压并应用补丁假设你把补丁下载到了/home/test/目录，而你的OpenHarmony源码目录是/home/test/OpenHarmony-v4.0-Release。那么依次执行以下命令：
# 解压下载的补丁包 tar zxvf OpenHarmony-v4.0-Release-xxxx.tar.gz # 将补丁文件复制到OpenHarmony源码根目录，覆盖原有文件 cp -arfP OpenHarmony-v4.0-Release-xxx/* /home/test/OpenHarmony-v4.0-Release/提示：
cp命令的-arfP参数是为了确保所有文件（包括隐藏文件、链接文件）都被正确复制并保留属性。请务必将命令中的路径/home/test/OpenHarmony-v4.0-Release/替换成你自己电脑上源码的实际路径。
补丁应用成功后，源码目录里就包含了专门为泰山派RK3566适配的板级支持包（BSP）了。
2. 搭建Docker编译环境
OpenHarmony的编译依赖很多特定的工具和库，为了避免把你本地系统搞乱，也为了环境统一，官方推荐使用Docker容器进行编译。这就像是一个打包好的、干净的“编译车间”。
2.1 安装Docker
如果你的Ubuntu系统还没装Docker，先安装它：
sudo apt install docker.io安装完成后，可以运行docker --version检查一下是否安装成功。
2.2 拉取OpenHarmony Docker镜像
接下来，我们需要拉取官方准备好的编译环境镜像。在终端执行：
sudo docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0如果上面的镜像拉取失败或速度慢，可以尝试备用镜像：
sudo docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard:3.2这两个镜像功能类似，任选一个能成功拉取的即可。这又会下载一个比较大的镜像文件，耐心等待。
3. 在Docker容器中编译SDK
环境准备好了，现在进入最核心的编译环节。咱们在Docker容器里操作。
3.1 创建并进入Docker容器
我们需要创建一个容器，并把我们本地的源码目录“映射”到容器内部，这样容器里就能访问和修改我们的源码了。
假设你的源码绝对路径是/work/OpenHarmony-v4.0-Release（请根据实际情况修改），那么创建容器的命令如下（如果你用的是1.0.0镜像）：
sudo docker run -it -v /work/OpenHarmony-v4.0-Release:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0如果你拉取的是3.2镜像，则用这个命令：
sudo docker run -it -v /work/OpenHarmony-v4.0-Release:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard:3.2命令解释：
-it：以交互模式运行容器并分配一个伪终端。-v /本地路径:/容器内路径：这是关键！它把本地的源码目录挂载到容器内的/home/openharmony目录。你在容器里对这个目录的操作，会直接反映到本地的源码上。- 最后一段是镜像名称。
执行成功后，终端提示符会变化，说明你已经进入了Docker容器内部。
3.2 安装编译工具
在容器内，首先切换到源码目录，然后下载编译所需的一系列预编译工具（比如交叉编译器）：
# 切换到容器内映射的源码目录 cd /home/openharmony # 执行下载脚本 ./build/prebuilts_download.sh这个脚本会下载不少东西，需要等一会儿。
接下来，安装OpenHarmony的编译构建工具hb：
# 确保在 /home/openharmony 目录下 cd /home/openharmony # 安装hb工具 pip3 install build/hb如果上面这条命令安装失败（有时候路径问题），可以尝试备用命令，效果是一样的：
python3 -m pip install --user build/lite安装成功后，可以运行hb -h看看帮助信息，确认安装好了。
3.3 选择编译目标
现在要告诉编译系统，我们要编译的是哪个产品。在容器终端里执行：
# 设置当前目录为OpenHarmony根目录 hb set -root . # 然后会弹出一个交互式选择界面执行hb set -root .后，会出现一个选择界面。咱们用键盘上下键移动光标：
- 首先选择
standard（标准系统），按回车。 - 接着在子菜单中，找到并选择
tspi_rk3566（这就是我们的泰山派开发板），按回车。
这样就完成了产品配置。这个配置信息会保存下来，下次编译就不需要再选了。
3.4 开始编译
激动人心的时刻到了，开始编译整个系统。如果你是第一次编译，或者修改了核心代码，建议使用-f参数进行全量编译：
hb build -f如果你只是修改了应用层代码，可以不用-f参数进行增量编译，速度会快很多：
hb build重要提示：第一次全量编译非常耗时！根据电脑配置（CPU核心数、内存、硬盘速度），可能需要2到6个小时。期间电脑风扇可能会狂转，这是正常的。可以去干点别的，耐心等待。
编译成功后，最关键的输出文件——系统镜像，会生成在以下目录：/home/openharmony/out/tspi_rk3566/packages/phone/images
因为我们的源码目录是挂载的，所以你可以在宿主机的源码目录下找到完全相同的路径，即：你的源码路径/out/tspi_rk3566/packages/phone/images。里面有一堆.img文件，这就是我们要烧录的固件。
3.5 如何重新进入容器
编译中途如果退出了容器，想再次进入，不需要重新docker run。可以按以下步骤操作：
# 在宿主机终端查看所有容器列表，找到刚才容器的ID docker container ls --all # 启动那个处于Exited状态的容器 docker container start [你的容器ID] # 附着到该容器的终端 docker container attach [你的容器ID]4. 固件烧录到开发板
编译出的镜像文件，需要通过USB线烧写到泰山派开发板的存储芯片中。
4.1 硬件连接与准备
- 找到泰山派开发板上的USB OTG口（通常有标识，或参考板子丝印）。
- 使用一条USB-A to USB-C的数据线，将开发板的OTG口与电脑的USB口连接。
注意：务必连接电脑主板原生的USB口（比如机箱后面的），避免使用扩展坞或机箱前置面板接口，供电可能不足会导致烧录失败。
- 开发板无需连接电源适配器，本次烧录通过USB线供电。
4.2 使用RKDevTool烧录软件
烧录工具我们使用瑞芯微官方提供的RKDevTool。
- 启动工具：在Windows电脑上，解压RKDevTool工具包，双击运行
RKDevTool.exe。 - 进入烧录模式：让开发板进入“Loader”烧录模式。
- 先按住开发板上的REC（恢复）按键不松开。
- 然后，短按一下RST（复位）按键。
- 此时，再松开REC按键。这时，RKDevTool软件下方日志区域应该会显示“发现一个LOADER设备”。
- 加载配置文件：
- 在RKDevTool界面右侧，右键点击任意一个镜像名称（如
Loader）后面的空白处。 - 在弹出的菜单中，选择“导入配置”。
- 找到我们编译输出的目录
out/tspi_rk3566/packages/phone/images，选择里面的config.cfg文件。导入后，所有镜像路径会自动填充好。
- 在RKDevTool界面右侧，右键点击任意一个镜像名称（如
- 检查镜像文件：导入配置后，工具界面会列出所有需要烧录的镜像文件。请确保每一行都正确指向了
images目录下对应的文件。对应关系如下：
| 序号 | RKDevTool中的名称 | 对应的镜像文件名 |
|---|---|---|
| 1 | Loader | MiniLoaderAll.bin |
| 2 | Parameter | parameter.txt |
| 3 | Uboot | uboot.img |
| 4 | resource | resource.img |
| 5 | Boot_linux | boot_linux.img |
| 6 | ramdisk | ramdisk.img |
| 7 | System | system.img |
| 8 | Vendor | vendor.img |
| 9 | updater | updater.img |
| 10 | userdata | userdata.img |
- 执行烧录：确认设备显示“发现一个LOADER设备”，并且所有镜像文件路径正确后，直接点击软件上的“执行”按钮。
- 等待完成：烧录过程会有进度条显示，直到所有项目后面都显示“完成”，并且日志显示“重启设备”，就大功告成了。此时开发板会自动重启，并运行刚刚烧录的OpenHarmony 4.0系统。
5. 功能列表与引脚说明（附）
烧录成功后，你的泰山派就已经运行OpenHarmony 4.0了。这个系统镜像默认支持了板载的大部分硬件功能：
| 硬件接口 | 是否支持 | 说明 |
|---|---|---|
| 调试UART | ✅ | 参数1500000,n,8,1 |
| MIPI显示屏 | ✅ | |
| 触摸屏 | ✅ | |
| HDMI液晶屏 | ✅ | |
| 摄像头 | ✅ | |
| WiFi | ✅ | |
| 蓝牙 | ✅ | |
| 扬声器 | ✅ | |
| 麦克风 | ✅ | |
| RGB三色灯 | ✅ | |
| USB 2.0 | ✅ | |
| USB 3.0 | ✅ | |
| 以太网口 | ✅ | |
| TF卡 | ✅ |
此外，板载的40Pin排针引脚功能定义如下，方便你进行外设扩展：
| 复用功能 | GPIO | 引脚编号 | 引脚编号 | GPIO | 复用功能 |
|---|---|---|---|---|---|
| 3.3V | 3.3V | 1 | 2 | 5V | 5V |
| I2C2_SDA_M0 | GPIO0_B6 | 3 | 4 | 5V | 5V |
| I2C2_SCL_M0 | GPIO0_B5 | 5 | 6 | GND | GND |
| GPIO | GPIO1_A4 | 7 | 8 | GPIO3_B7 | UART3_TX_M1 |
| GND | GND | 9 | 10 | GPIO3_C0 | UART3_RX_M1 |
| GPIO | GPIO3_A1 | 11 | 12 | GPIO3_C4 | PWM14_M0 |
| GPIO | GPIO3_A2 | 13 | 14 | GND | GND |
| GPIO | GPIO3_A3 | 15 | 16 | GPIO3_A4 | GPIO |
| 3.3V | 3.3V | 17 | 18 | GPIO3_A5 | GPIO |
| SPI3_MOSI_M1 | GPIO4_C3 | 19 | 20 | GND | GND |
| SPI3_MISO_M1 | GPIO4_C5 | 21 | 22 | GPIO3_A6 | GPIO |
| SPI3_CLK_M1 | GPIO4_C2 | 23 | 24 | GPIO4_C6 | SPI3_CS0_M1 |
| GND | GND | 25 | 26 | GPIO3_A7 | |
| I2C3_SDA_M1 | GPIO3_B6 | 27 | 28 | GPIO3_B5 | I2C3_SCL_M1 |
| GPIO | GPIO3_B0 | 29 | 30 | GND | GND |
| GPIO | GPIO3_C2 | 31 | 32 | GPIO3_C5 | PWM15_IR_M0 |
| PWM8_M0 | GPIO3_B1 | 33 | 34 | GND | GND |
| PWM8_M0 | GPIO3_B2 | 35 | 36 | GPIO3_C3 | GPIO |
| GPIO | GPIO0_B7 | 37 | 38 | GPIO3_B3 | GPIO |
| GND | GND | 39 | 40 | GPIO3_B4 | GPIO |
6. 常见问题与进阶配置（FAQ）
6.1 关键目录说明
打完补丁后，源码中以下几个目录是和泰山派密切相关的，如果你需要做深度定制，可能会用到：
| 目录路径 | 作用 | 备注 |
|---|---|---|
| /vendor/lcsc/tspi_rk3566 | 存放泰山派相关的配置和代码 | |
| /device/board/lcsc/tspi_rk3566 | 存放泰山派的板级配置和代码目录 | |
| /device/soc/rockchip/rk3566 | 存放瑞芯微RK3566芯片的公共代码 | |
| /kernel/linux/config/linux-5.10/tspi_rk3566 | 存放泰山派的内核配置 | |
| /kernel/linux/patches/linux-5.10/tspi_rk3566_patch | 存放泰山派的HDF驱动和Linux内核代码修改 |
6.2 如何切换MIPI或HDMI显示
泰山派开发板上的MIPI和HDMI显示接口复用了部分硬件资源（VOP），因此不能同时使用。默认配置可能是一种，如果你想切换，需要修改内核的设备树补丁文件。
切换到MIPI显示：编辑文件/kernel/linux/patches/linux-5.10/tspi_rk3566_patch/kernel.patch，找到显示相关的部分，修改成如下样子：
+//【开/关】mipi 显示屏配置，用户可以基于此复制自己的屏，注意EDP与MIPI屏互斥，因为共用了VOP如果需要同显自行修改 +#include "tspi-rk3566-dsi-v10.dtsi" + +//【开/关】HDMI 显示屏配置，里面内容几乎可以不用动，如果不需要hdmi显示直接注释掉即可 +//#include "tspi-rk3566-hdmi-v10.dtsi"关键：dsi（MIPI）行前保留+号启用；hdmi行前加上+//将其注释掉。
切换到HDMI显示：同样编辑上述文件，修改为：
+//【开/关】mipi 显示屏配置，用户可以基于此复制自己的屏，注意EDP与MIPI屏互斥，因为共用了VOP如果需要同显自行修改 +//#include "tspi-rk3566-dsi-v10.dtsi" + +//【开/关】HDMI 显示屏配置，里面内容几乎可以不用动，如果不需要hdmi显示直接注释掉即可 +#include "tspi-rk3566-hdmi-v10.dtsi"关键：dsi（MIPI）行前改为+//注释掉；hdmi行前保留+号启用。
修改保存后，需要重新执行一次全量编译（hb build -f），生成新的镜像并烧录，修改才能生效。
好了，整个从源码到烧录的流程就结束了。第一次操作可能会觉得步骤多，但跟着走一遍，理解了每个环节的作用，后面就轻车熟路了。如果在哪个环节卡住了，多检查一下命令和路径，大部分问题都是粗心导致的。祝你玩转泰山派，享受OpenHarmony开发的乐趣！