【鸿蒙开发】OpenHarmony调测工具hdc使用教程(设备开发者)

00. 目录

文章目录

- 00. 目录
- 01. OpenHarmony概述
- 02. hdc简介
- 03. hdc获取
- 04. option相关的命令
- 05. 查询设备列表的命令
- 06. 服务进程相关命令
- 07. 网络相关的命令
- 08. 文件相关的命令
- 09. 应用相关的命令
- 10. 调试相关的命令
- 11. 常见问题
- 12. 附录

01. OpenHarmony概述

OpenHarmony是由开放原子开源基金会（OpenAtom Foundation）孵化及运营的开源项目，目标是面向全场景、全连接、全智能时代，基于开源的方式，搭建一个智能终端设备操作系统的框架和平台，促进万物互联产业的繁荣发展。

OpenHarmony整体遵从分层设计，从下向上依次为：内核层、系统服务层、框架层和应用层。系统功能按照“系统 > 子系统 > 组件”逐级展开，在多设备部署场景下，支持根据实际需求裁剪某些非必要的组件。OpenHarmony技术架构如下所示：
在这里插入图片描述

内核层

内核子系统：采用多内核（Linux内核或者LiteOS）设计，支持针对不同资源受限设备选用适合的OS内核。内核抽象层（KAL，Kernel Abstract Layer）通过屏蔽多内核差异，对上层提供基础的内核能力，包括进程/线程管理、内存管理、文件系统、网络管理和外设管理等。
驱动子系统：驱动框架（HDF）是系统硬件生态开放的基础，提供统一外设访问能力和驱动开发、管理框架。

系统服务层

系统服务层是OpenHarmony的核心能力集合，通过框架层对应用程序提供服务。该层包含以下几个部分：

系统基本能力子系统集：为分布式应用在多设备上的运行、调度、迁移等操作提供了基础能力，由分布式软总线、分布式数据管理、分布式任务调度、公共基础库、多模输入、图形、安全、AI等子系统组成。
基础软件服务子系统集：提供公共的、通用的软件服务，由事件通知、电话、多媒体、DFX（Design For X）等子系统组成。
增强软件服务子系统集：提供针对不同设备的、差异化的能力增强型软件服务，由智慧屏专有业务、穿戴专有业务、IoT专有业务等子系统组成。
硬件服务子系统集：提供硬件服务，由位置服务、用户IAM、穿戴专有硬件服务、IoT专有硬件服务等子系统组成。

根据不同设备形态的部署环境，基础软件服务子系统集、增强软件服务子系统集、硬件服务子系统集内部可以按子系统粒度裁剪，每个子系统内部又可以按功能粒度裁剪。

框架层

框架层为应用开发提供了C/C++/JS等多语言的用户程序框架和Ability框架，适用于JS语言的ArkUI框架，以及各种软硬件服务对外开放的多语言框架API。根据系统的组件化裁剪程度，设备支持的API也会有所不同。

应用层

应用层包括系统应用和第三方非系统应用。应用由一个或多个FA（Feature Ability）或PA（Particle Ability）组成。其中，FA有UI界面，提供与用户交互的能力；而PA无UI界面，提供后台运行任务的能力以及统一的数据访问抽象。基于FA/PA开发的应用，能够实现特定的业务功能，支持跨设备调度与分发，为用户提供一致、高效的应用体验。

技术特性

硬件互助，资源共享

主要通过下列模块达成

分布式软总线

分布式软总线是多设备终端的统一基座，为设备间的无缝互联提供了统一的分布式通信能力，能够快速发现并连接设备，高效地传输任务和数据。
分布式数据管理

分布式数据管理基于分布式软总线，实现了应用程序数据和用户数据的分布式管理。用户数据不再与单一物理设备绑定，业务逻辑与数据存储分离，应用跨设备运行时数据无缝衔接，为打造一致、流畅的用户体验创造了基础条件
分布式任务调度

分布式任务调度基于分布式软总线、分布式数据管理、分布式Profile等技术特性，构建统一的分布式服务管理（发现、同步、注册、调用）机制，支持对跨设备的应用进行远程启动、远程调用、绑定/解绑、以及迁移等操作，能够根据不同设备的能力、位置、业务运行状态、资源使用情况并结合用户的习惯和意图，选择最合适的设备运行分布式任务
设备虚拟化

分布式设备虚拟化平台可以实现不同设备的资源融合、设备管理、数据处理，将周边设备作为手机能力的延伸，共同形成一个超级虚拟终端。

一次开发，多端部署

OpenHarmony提供用户程序框架、Ability框架以及UI框架，能够保证开发的应用在多终端运行时保证一致性。一次开发、多端部署。

多终端软件平台API具备一致性，确保用户程序的运行兼容性。

支持在开发过程中预览终端的能力适配情况（CPU/内存/外设/软件资源等）。
支持根据用户程序与软件平台的兼容性来调度用户呈现。

统一OS，弹性部署

OpenHarmony通过组件化和组件弹性化等设计方法，做到硬件资源的可大可小，在多种终端设备间，按需弹性部署，全面覆盖了ARM、RISC-V、x86等各种CPU，从百KiB到GiB级别的RAM。

02. hdc简介

hdc（OpenHarmony Device Connector）是 OpenHarmony 为开发人员提供的用于调试的命令行工具，通过该工具可以在Windows/Linux/MacOS等系统上与开发机或者模拟器进行交互。

03. hdc获取

hdc 工具获取方式：

通过OpenHarmony sdk获取，hdc在sdk的toolchains目录下。

使用举例：

下面以windows侧使用方式举例：

获取windows的sdk，将hdc.exe放到磁盘某个位置即可使用。

注意事项

使用hdc，如果出现异常，可以尝试通过hdc kill命令杀掉hdc服务，或者通过hdc start -r命令重启服务进程进行解决。
如果出现hdc list targets获取不到设备信息，通过任务管理器查看是否有hdc进程存在，如果进程存在，可以通过杀掉该进程进行解决。

04. option相关的命令

option涉及以下命令：

-h/help -v/version 用于显示hdc相关的帮助、版本信息。

命令说明

返回值	返回值说明
返回对应信息	帮助或者版本信息

示例

# 查看帮助信息
D:\tools>hdc -h

D:\tools>hdc help

# 查看版本信息
D:\tools>hdc -v
Ver: 1.1.1l

D:\tools>hdc version
Ver: 1.1.1l

-l 0-5 用于指定运行时日志等级,默认为LOG_INFO。

命令说明

参数	参数说明
0	LOG_OFF
1	LOG_FATAL
2	LOG_WARN
3	LOG_INFO
4	LOG_DEBUG
5	LOG_ALL

示例

D:\tools>hdc -l5 start
[D][2025-03-08 19:14:13.154][1228][channel.cpp:341] Mallocchannel:564292774
[D][2025-03-08 19:14:13.155][1228][base.cpp:761] File "HDCServer" locked. proc already exit!!!

[D][2025-03-08 19:14:13.156][1228][channel.cpp:424] Begin to free channel, channelid:564292774
[D][2025-03-08 19:14:13.156][1228][main.cpp:346] !!!!!!!!!Main finish main

D:\tools>

-t key 用于连接指定设备标识为key的设备。

命令说明

参数	参数说明
key	为 IP地址:port 格式，或者USB序列号
返回值	返回值说明
①error: device ‘***’ not found ②Nothing to do…	①设备不存在 ②附加的命令不存在

示例

该option需要与具体的操作命令搭配使用，下面以shell命令举例：

hdc list targets （获取设备信息）

hdc -t key shell （-t后面添加的_key_ 需要替换为上面查询的设备信息）

D:\tools>hdc list targets
2f011130375330303010b6204718ab00

D:\tools>hdc -t 2f011130375330303010b6204718ab00 shell
#

说明

一台开发机可支持多个设备连接，每个设备有其唯一的设备标识，如果通过网络与设备连接,其标识为IP地址:port格式，如果通过USB连接则标识为设备sn号。该命令需要跟随具体操作命令。

checkserver 用于获取client-server版本。

命令说明

返回值	返回值说明
Client version: server version:	client-server版本号

示例

D:\tools>hdc checkserver

05. 查询设备列表的命令

查询设备列表涉及以下命令：

list targets[-v]

显示所有已经连接的目标设备列表

表5 命令说明

参数	参数说明
-v	添加-v选项，则会打印设备详细信息
返回值	返回值说明
①返回设备信息 ②[Empty]	①已经连接的设备列表信息 ②没有查询到设备信息

示例

D:\tools>hdc list targets
2f011130375330303010b6204718ab00

D:\tools>hdc list targets -v
2f011130375330303010b6204718ab00                USB     Connected       localhost
COM1            UART    Ready
COM3            UART    Ready
COM4            UART    Ready

D:\tools>

06. 服务进程相关命令

服务进程涉及以下命令：

target mount 以读写模式挂载系统分区。

表6 命令说明

参数参数说明
无无
返回值 返回值说明
①Mount finish
②返回具体信息 ①成功情况下返回的信息
②失败情况下的具体信息

示例

D:\tools>hdc target mount
Mount finish

target boot 设备重启。

示例

D:\tools>hdc target boot

smode [-r] 授予后台服务进程root权限，使用-r参数取消授权。

示例

D:\tools>hdc smode

D:\tools>
D:\tools>hdc smode -r

kill [-r] 终止服务进程。

命令说明

参数	参数说明
-r	触发服务重启
返回值	返回值说明
①Kill server finish ②返回具体信息	①成功情况下返回的信息 ②失败情况下的具体信息

示例

D:\tools>hdc kill
Kill server finish

D:\tools>

start [-r] 启动服务进程。

命令说明

参数	参数说明
-r	如果服务进程已经启动，-r选项会触发服务进程重新启动
返回值	返回值说明
无	无

示例

D:\tools>hdc start

D:\tools>

07. 网络相关的命令

网络部分涉及以下命令：

tconn host[:port][-remove] 通过【ip地址：端口号】来指定连接的设备

命令说明

参数	参数说明
host[:port]	为IP地址:port格式
-remove	表示断开与指定设备的连接
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

示例

D:\tools>hdc tconn 192.168.0.100:8710

tmode usb 执行后设备端对应daemon进程重启，并首先选用USB连接方式。

命令说明

参数	参数说明
无	无
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

示例

hdc tmode usb

tmode port port-number 执行后设备端对应daemon进程重启，并优先使用网络方式连接设备，如果连接设备失败，再选择USB连接。

命令说明

参数	参数说明
port-number	listen连接的网络端口号
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

示例

hdc tmode port 8710

说明

执行完毕后，远端daemon将会退出并重启，默认启用TCP连接，如果不加上listen端口则listen随机端口。

fport localnode remotenode 端口转发，指定主机端口转发数据到设备侧端口。

示例

hdc fport tcp:1234 tcp:1080

rport remotenode localnode 端口转发，指定设备侧端口转发数据到主机端口。

示例

hdc rport tcp:2080 tcp:2345

fport ls 列出全部转发端口转发任务。

命令说明

参数	参数说明
无	无
返回值	返回值说明
‘tcp:1234 tcp:1080’ [Forward]	正向端口转发任务
‘tcp:2080 tcp:2345’ [Reverse]	反向端口转发任务

示例

hdc fport ls

fport rm 删除指定端口转发任务。

示例

hdc fport rm tcp:1234 tcp:1080

08. 文件相关的命令

文件部分涉及以下命令：

file send local remote 发送文件至远端设备。

命令说明

参数	参数说明
local	本地待发送文件路径
remote	远程待接收文件路径
返回值	返回值说明
①返回具体信息 ②返回传输结果	①失败情况下的具体信息 ②成功传输的结果信息

示例

D:\tools>hdc file send D:\tools/SN.txt /data/local/tmp/SN.txt
FileTransfer finish, Size:22, File count = 1, time:31ms rate:0.71kB/s

D:\tools>

file recv [-a] remote local 从远端设备接收文件至本地。

命令说明

参数	参数说明
-a	文件保留时间戳模式
local	本地待接收文件路径
remote	远程待发送文件路径
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

示例

D:\tools>hdc file recv /data/local/tmp/SN.txt ./a.txt
FileTransfer finish, Size:22 time:3ms rate:7.33kB/s

09. 应用相关的命令

应用部分涉及以下命令：

install [-r/-d/-g] package 安装OpenHarmony APP package。

命令说明

参数	参数说明
package	OpenHarmony应用安装包文件名
-r	替换已存在应用
-d	允许降级安装
-g	应用动态授权
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

示例

hdc install hwadmin.hap

uninstall [-k] package 卸载OpenHarmony应用。

命令说明

参数	参数说明
package	OpenHarmony应用安装包
-k	保留/data/cache
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

示例

hdc uninstall package

10. 调试相关的命令

调试涉及以下命令：

hilog 支持抓取log信息。

命令说明

参数	参数说明
无	无
返回值	返回值说明
返回具体信息	抓取的日志信息

抓取hilog日志：

hdc hilog

清理hilog缓存日志：

hdc shell "hilog -r"

shell [command] 远程执行命令或进入交互命令环境。

命令说明

参数	参数说明
command	需要执行的单次命令
返回值	返回值说明
返回具体信息	shell后面执行命令的结果信息

示例

hdc shell

jpid 获取可调试进程列表。

示例

D:\tools>hdc jpid
1037
1061
1105
1117
1260
1653

11. 常见问题

11.1 hdc连接不到设备

现象描述 执行 "hdc list targets"命令后结果为：[Empty]
解决方法
1. 设备没有被识别：在设备管理器中查看是否有hdc设备，在通用串行总线设备中会有“HDC Device”信息。如果没有，hdc无法连接。此时需要断开并重联PC和OpenHarmony设备之间的USB连接，或者烧写最新的镜像。
2. hdc工作异常：可以执行"hdc kill"或者"hdc start -r"杀掉hdc服务或者重启hdc服务，然后再执行hdc list targets查看是否已经可以获取设备信息。
3. hdc与设备不匹配：如果设备烧写的是最新镜像，hdc也需要使用最新版本。

11.2 hdc运行不了

现象描述 点击hdc.exe文件无法运行。
解决方法
1. 运行环境异常： linux版本建议ubuntu 18.04以上 64位，其他相近版本也可；libc++.so引用错误请使用ldd/readelf等命令检查库引用 windows版本建议windows10 64位，如果低版本windows winusb库缺失，请使用zadig更新库。对于复合设备，需要使用zadig工具安装libusb-win32驱动。
2. 如何运行hdc.exe： hdc.exe不需要安装，直接放到磁盘上就能使用，也可以添加到环境变量中。通过打开cmd执行hdc命令直接使用。

11.3 hdc client如何远程访问hdc server

使用场景

本地client指定远程server上的设备，执行hdc命令。
连接步骤
1. 关闭本地sever：
```
hdc kill
```
2. -s [ip:]port -m
  
  启动远程server：
```
hdc -s severIP:8710 -m
```
3. -s [ip:]port command
  
  指定server执行指令：
```
hdc -s severIP:8710 list targets
```