ohos-dev-distributed-device-image-flashing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flash OpenHarmony Device with Daily Build

使用 daily build 刷写 OpenHarmony 设备

Download daily build and flash via hdc updater mode. Scripts are generic — not hardcoded to any specific repo or device.

下载 daily build，并通过 hdc updater 模式进行刷写。脚本均为通用脚本，未针对任何特定仓库或设备进行硬编码。

Scripts

脚本

Script	Purpose
`download_daily.py`	Query DCP API, download + extract device image
`flash_device.py`	Parse `parameter.txt` for partitions, flash via hdc updater mode

Use the actual installed skill directory when running the helper scripts.

脚本	用途
`download_daily.py`	查询 DCP API，下载并解压设备镜像
`flash_device.py`	解析 `parameter.txt` 中的分区信息，通过 hdc updater 模式刷写

运行辅助脚本时，请使用实际安装的 skill 目录。

Required Workflow

必需工作流

Follow these steps in order. Do not skip connectivity checks.

请按以下顺序执行操作。不要跳过连接检查。

Step 1: Verify Device Connectivity

第 1 步：验证设备连接

Before any download or flash operation, confirm the device is reachable.

Direct USB:

bash

hdc list targets

在执行任何下载或刷写操作之前，确认设备可以正常访问。

直接通过 USB 连接：

bash

hdc list targets

Must show at least one device serial. If empty, check USB cable and hdc server.

必须至少显示一个设备序列号。如果输出为空，请检查 USB 线缆和 hdc server。


**Via SSH tunnel:**
```bash
ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "echo connected && hdc list targets"


**通过 SSH 隧道连接：**
```bash
ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "echo connected && hdc list targets"

Both SSH and hdc must succeed. If SSH fails, confirm port and that SSH service is running.

SSH 和 hdc 必须均执行成功。如果 SSH 失败，请确认端口以及 SSH service 是否正在运行。


Record the current firmware version for post-flash comparison:
```bash
hdc shell param get const.product.software.version


记录当前 firmware 版本，以便刷写后进行对比：
```bash
hdc shell param get const.product.software.version

Step 2: Download Image

第 2 步：下载镜像

bash

SKILL_DIR=<installed-skill-dir>
python3 "$SKILL_DIR/download_daily.py" --component dayu200

After download completes, the script verifies archive integrity. Check the output for errors before proceeding.

bash

SKILL_DIR=<installed-skill-dir>
python3 "$SKILL_DIR/download_daily.py" --component dayu200

下载完成后，脚本会验证归档文件的完整性。继续操作前，请检查输出中是否存在错误。

Step 3: Flash Device

第 3 步：刷写设备

Pre-flash checklist:

Device is reachable (Step 1 passed)
Image downloaded and extracted (Step 2 passed,
```
system.img
```
exists in output dir)
User has explicitly approved the destructive flash operation

Only pass

--yes

after the user has explicitly approved destructive device flashing. Otherwise let

flash_device.py

prompt for

FLASH

bash

python3 "$SKILL_DIR/flash_device.py" --img-dir daily_build --yes

WARNING: Do not interrupt the flash process. If hdc disconnects or power is lost during dd writes, the device may become unbootable. See Recovery section below.

刷写前检查清单：

设备可以正常访问（第 1 步已通过）
镜像已下载并解压（第 2 步已通过，输出目录中存在
```
system.img
```
）
用户已明确批准执行具有破坏性的刷写操作

只有在用户明确批准破坏性设备刷写操作后，才能传入

--yes

。否则让

flash_device.py

提示用户输入

FLASH

。

bash

python3 "$SKILL_DIR/flash_device.py" --img-dir daily_build --yes

警告：刷写过程中不得中断操作。 如果在 dd 写入期间 hdc 断开连接或设备断电，设备可能变得无法启动。请参阅下方“设备恢复”部分。

Step 4: Verify Success

第 4 步：验证刷写是否成功

Wait ~60 seconds after reboot, then:

bash

hdc shell param get const.product.software.version

Compare with the version recorded in Step 1. If the version changed to the expected build, flash succeeded.

If the device does not appear in

hdc list targets

after 120 seconds, see Recovery below.

重启后等待约 60 秒，然后执行：

bash

hdc shell param get const.product.software.version

将结果与第 1 步记录的版本进行对比。如果版本已变更为预期的 build，则说明刷写成功。

如果 120 秒后设备仍未出现在

hdc list targets

中，请参阅下方“设备恢复”部分。

Step 5: Push Custom Libraries (Optional)

第 5 步：推送自定义库（可选）

After flashing the base image, push locally-compiled libraries:

bash

hdc shell mount -o rw,remount /
for lib in lib1.z.so lib2.z.so; do
    hdc file send $lib /system/lib/$lib
done
hdc shell reboot

For SSH tunnel scenarios, upload via scp first, then send to device:

bash

ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "hdc shell mount -o rw,remount /"
for lib in lib1.z.so lib2.z.so; do
    scp -P $SSH_PORT $lib $SSH_USER@$SSH_HOST:push_tmp/$lib
    ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "hdc file send push_tmp/$lib /system/lib/$lib"
done
ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "hdc shell reboot"

刷写基础镜像后，推送本地编译的库：

bash

hdc shell mount -o rw,remount /
for lib in lib1.z.so lib2.z.so; do
    hdc file send $lib /system/lib/$lib
done
hdc shell reboot

对于 SSH 隧道场景，请先通过 scp 上传，然后再发送到设备：

bash

ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "hdc shell mount -o rw,remount /"
for lib in lib1.z.so lib2.z.so; do
    scp -P $SSH_PORT $lib $SSH_USER@$SSH_HOST:push_tmp/$lib
    ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "hdc file send push_tmp/$lib /system/lib/$lib"
done
ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "hdc shell reboot"

SSH Tunnel Usage

SSH 隧道用法

The scripts run on the target machine that has USB to the board. Upload via SSH then execute remotely.

bash

SKILL_DIR=<installed-skill-dir>
SSH_PORT=<ssh-port>
SSH_USER=<ssh-user>
SSH_HOST=<ssh-host>

脚本应运行在通过 USB 连接开发板的目标机器上。通过 SSH 上传脚本，然后在远程执行。

bash

SKILL_DIR=<installed-skill-dir>
SSH_PORT=<ssh-port>
SSH_USER=<ssh-user>
SSH_HOST=<ssh-host>

Upload scripts

scp -P $SSH_PORT "$SKILL_DIR/download_daily.py" $SSH_USER@$SSH_HOST:download_daily.py scp -P $SSH_PORT "$SKILL_DIR/flash_device.py" $SSH_USER@$SSH_HOST:flash_device.py

Download on remote

ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "python download_daily.py --component dayu200"

Flash from remote

ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "python flash_device.py --yes"


**WARNING: SSH disconnect during flash is dangerous.** If the SSH session drops while `dd` is writing a partition, the device may be left in a partially-written state. Mitigations:
- Use `nohup` or `tmux`/`screen` on the remote machine to keep the process alive if SSH drops.
- Ensure the remote machine has a stable power supply.
- If SSH drops mid-flash, do NOT power cycle the device. Reconnect SSH and check if the process is still running (`ps aux | grep flash_device`).

ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "python flash_device.py --yes"


**警告：刷写期间断开 SSH 连接非常危险。** 如果 SSH 会话在 dd 写入分区期间中断，设备可能处于部分写入状态。缓解措施：
- 在远程机器上使用 `nohup` 或 `tmux`/`screen`，确保 SSH 断开后进程仍能继续运行。
- 确保远程机器供电稳定。
- 如果刷写过程中 SSH 断开，请勿立即给设备断电。重新连接 SSH，并检查进程是否仍在运行（`ps aux | grep flash_device`）。

Device Recovery

设备恢复

If a flash fails (power loss, hdc disconnect, corrupted image), the device may not boot normally.

如果刷写失败（断电、hdc 断开连接、镜像损坏），设备可能无法正常启动。

DAYU200 / RK3568 Recovery

DAYU200 / RK3568 恢复方法

Try updater mode: Hold the device's Vol+/recovery button while powering on. The device should enter updater/recovery mode. Then retry flashing.
If hdc is unreachable in updater mode: Use the RKDevTool (Windows) or upgrade_tool (Linux) from Rockchip to flash via USB in maskrom/loader mode:
- Power off the device
- Hold the maskrom button while connecting USB
- Use RKDevTool to write the full image
If maskrom is not accessible: The hardware recovery button location varies by board revision. Consult the DAYU200 hardware documentation.

尝试 updater 模式：按住设备的 Vol+/recovery 键并开机。设备应进入 updater/recovery 模式。然后重试刷写。
如果 updater 模式下无法访问 hdc：使用 Rockchip 提供的 RKDevTool（Windows）或 upgrade_tool（Linux），通过 USB 以 maskrom/loader 模式刷写：
- 关闭设备电源
- 按住 maskrom 键并连接 USB
- 使用 RKDevTool 写入完整镜像
如果无法进入 maskrom 模式：硬件恢复按钮的位置因板卡版本而异。请查阅 DAYU200 硬件文档。

General Checklist

通用检查清单

Symptom	Recovery
Device reboots to updater loop	Re-flash all partitions from updater mode
hdc list targets shows nothing	Try maskrom mode or check USB cable
Boot hangs on logo	system.img may be corrupt — re-download and flash
Services crash after custom .so push	IDL interface mismatch — do a full flash instead of partial push

症状	恢复方法
设备反复重启进入 updater 模式	在 updater 模式下重新刷写全部分区
`hdc list targets` 未显示任何内容	尝试 maskrom 模式或检查 USB 线缆
启动时停留在 Logo	`system.img` 可能已损坏，请重新下载并刷写
推送自定义 .so 后 service 崩溃	IDL 接口不匹配，应执行完整刷写，而不是部分推送

Key Design Decisions

关键设计决策

Partition table from parameter.txt:

flash_device.py

parses

CMDLINE:mtdparts=...

from the image's

parameter.txt

to discover partitions. The built-in RK3568 fallback partition list is used only when

--allow-fallback-partitions

is explicitly passed after verifying the image layout.

SSH port fallback: Scripts default to port 2222. If connection fails, prompt the user for the correct port rather than failing silently.

DCP API: Response path is

data.builds.dataList[].component

. Auto-searches last 7 days if today's build is missing.

Archive safety:

download_daily.py

rejects archive entries that would extract outside the output directory. After download, the archive is verified by opening it before extraction.

Destructive action confirmation:

flash_device.py

requires interactive

FLASH

confirmation unless

--yes

is passed by an already-approved workflow.

Command failure handling:

flash_device.py

stops immediately when an

hdc

command exits non-zero.

Userdata write path:

userdata.img

is flashed last. The helper unmounts

/data

, uploads the image to updater ramdisk temporary storage, writes it with

dd

, runs

sync

on the userdata block device, and removes the temporary file. Do not write

userdata.img

with a direct

hdc file send

/dev/block/by-name/userdata

基于 parameter.txt 获取分区表：

flash_device.py

会从镜像的

parameter.txt

中解析

CMDLINE:mtdparts=...

，以发现分区。只有在验证镜像布局后显式传入

--allow-fallback-partitions

，才会使用内置的 RK3568 后备分区列表。

SSH 端口后备机制： 脚本默认使用 2222 端口。如果连接失败，应提示用户提供正确端口，而不是静默失败。

DCP API： 响应路径为

data.builds.dataList[].component

。如果不存在当天的 build，会自动搜索最近 7 天的记录。

归档安全：

download_daily.py

会拒绝解压到输出目录之外的归档条目。下载后，会先通过打开归档文件进行验证，然后再执行解压。

破坏性操作确认： 除非已通过获得批准的工作流传入

--yes

，否则

flash_device.py

要求用户交互式输入

FLASH

进行确认。

命令失败处理： 当任意

hdc

命令以非零状态退出时，

flash_device.py

会立即停止执行。

Userdata 写入路径：

userdata.img

最后刷写。辅助脚本会卸载

/data

，将镜像上传到 updater ramdisk 临时存储，使用 dd 写入，在 userdata 块设备上运行

sync

，然后删除临时文件。请勿使用直接

hdc file send

的方式将

userdata.img

写入

/dev/block/by-name/userdata

。

Why Updater Mode

为什么使用 updater 模式

Normal mode mounts system/vendor read-only — dd silently fails. Updater mode keeps partitions unmounted. Userdata is flashed last because it's used as temp storage during the process.

普通模式会将 system/vendor 挂载为只读，导致 dd 静默失败。Updater 模式会保持分区处于未挂载状态。Userdata 最后刷写，是因为刷写过程中需要将其用作临时存储。

Common Mistakes

常见错误

Mistake	Fix
DCP 返回空	日期格式 `YYYYMMDDHHMMSS` ；脚本自动搜索 7 天
dd 无输出	必须 updater 模式
userdata 失败	先 umount /data
推包后 mmi_service 不启动	IDL 接口变了需全量刷机，不能只推部分 .so
SSH 连不上	先启动目标机器的 SSH 或端口转发服务，确认端口
SSH 断开导致烧录中断	用 nohup/tmux 运行脚本；不要立即断电
下载的镜像包损坏	删除 tar.gz 重新下载；检查网络连通性

错误	解决方法
DCP 返回空	日期格式 `YYYYMMDDHHMMSS` ；脚本自动搜索 7 天
dd 无输出	必须使用 updater 模式
userdata 失败	先执行 umount /data
推包后 mmi_service 不启动	IDL 接口已变更，需要完整刷写，不能只推送部分 .so
SSH 无法连接	先启动目标机器的 SSH 或端口转发服务，并确认端口
SSH 断开导致刷写中断	使用 nohup/tmux 运行脚本；不要立即断电
下载的镜像包损坏	删除 tar.gz 并重新下载；检查网络连通性