hdc - OpenHarmony Device Connector

• hdc - OpenHarmony Device Connector
  • Introduction
  • Architecture
  • Directory Structure
    • PC-Side Compilation Instructions
    • PC-Side Acquisition Instructions
    • Linux-Side USB Device Permission Instructions
    • Command Help
  • Troubleshooting Guide
  • FAQ

Introduction

hdc (OpenHarmony Device Connector) is a command-line tool provided for developers to connect and debug devices. The PC-side development machine uses the hdc command-line tool, which needs to support deployment on systems like Windows/Linux/Mac to connect and debug OpenHarmony devices (or emulators). The PC-side hdc tool requires corresponding versions for these development machine operating system platforms, while the device-side hdc daemon must be released with the device image, including support for emulators. Below are the commonly used commands and usage examples for hdc.

Architecture

hdc mainly consists of three parts:

1. hdc client: Runs on the development machine as a client. Users can execute corresponding hdc commands in the development machine's command terminal (Windows cmd/Linux shell). It operates on the development machine, and other terminal debugging IDEs also include the hdc client.

2. hdc server: Runs as a background process on the development machine. The server manages communication between the client and the device-side daemon, including connection reuse, data packet transmission and reception, as well as direct processing of certain local commands.

3. hdc daemon: Deployed on the OpenHarmony device side as a daemon process that runs on demand. It is responsible for handling requests from the client side.

Directory Structure

/developtools
├── hdc               # hdc代码目录
│   └── src
│       ├── common    # 设备端和host端公用的代码目录
│       ├── daemon    # 设备端的代码目录
│       ├── host      # host端的代码目录
│       └── test      # 测试用例的代码目录

PC Compilation Instructions

Steps to compile the hdc PC executable:

1. Compilation Command: To compile the SDK, refer to the SDK compilation instructions in the repository at https://gitee.com/openharmony/build/blob/master/README_zh.md. Execute the specified SDK compilation command to compile the entire SDK, which will include the compilation and packaging of hdc.

2. Compilation: Run the adjusted SDK compilation command on the target development machine. Upon successful compilation, hdc will be output to the SDK platform-related directory. Note: In a Ubuntu environment, only Windows/Linux versions of the tool can be compiled; the macOS version requires compilation on a macOS development machine.

PC Acquisition Instructions

1. Download the SDK (Recommended)

通过访问本社区网站下载[dailybuilds](http://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist) 或正式发布的sdk压缩包，从中根据自己平台到相应的目录toolchain下解压提取。

2. Self-Compilation

For compilation instructions, please refer to the dedicated section above. Prebuilt binaries are no longer provided in the prebuilt directory of this repository.

3. Supported Environments

• Linux: Recommended Ubuntu 18.04 or later (64-bit). Other similar distributions are also acceptable. For libc++.so reference errors, use commands like ldd or readelf to inspect library dependencies.
• Windows: Recommended Windows 10 (64-bit). For older versions missing the winusb library, update it using Zadig. For composite devices, install the libusb-win32 driver via Zadig.

USB Device Permissions on Linux

On Linux, running hdc without root privileges may result in devices not being detected due to USB permission issues. Solutions are as follows:

1. Grant USB Access to Non-root Users
   This method is simple but may pose security risks. Evaluate based on your use case.

   sudo chmod -R 777 /dev/bus/usb/
   

2. Permanently Modify USB Permissions

   1. Use lsusb to identify the device's vendorID and productID.
   2. Create a new udev rule:

   Edit the UDEV rule, replacing default values with the device's idVendor and idProduct. MODE="0666" sets USB permissions.
   GROUP specifies the user group—ensure the logged-in user is part of this group. Use usermod -a -G username groupname to add the user.

   sudo vim /etc/udev/rules.d/90-myusb.rules
   SUBSYSTEMS=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303", GROUP="users", MODE="0666"
   

   Reboot or reload udev rules:

   sudo udevadm control --reload
   

3. Run as Root
   Test with root privileges:

   sudo hdc list targets
   

Command Help

Common hdc commands are listed below. Use hdc -h or hdc --help for details:

Table 1 Common hdc Commands

Option	Description
-t <em>key</em>	Specifies the target device ID (query with hdc list targets). Example: hdc -t *****(device ID) shell
-s <em>socket</em>	Specifies the service's listening socket configuration. Example: hdc -s ip:port
-h/help -v/version	Displays help or version information.
-l 0-5	Sets the runtime log level. Example: hdc -l5 start
checkserver	Retrieves the client-server version. Example: hdc checkserver
list targets[-v]	Lists connected target devices (-v for details). Example: hdc list targets
target mount	Mounts /vendor, /data, etc., in read-write mode. For root or /system partitions, use hdc shell mount -o rw,remount /. Example: hdc target mount
target boot	Reboots the device. Example: hdc target boot
smode [-r]	Grants root privileges to the background service (-r revokes). Example: hdc smode
kill [-r]	Terminates the hdc service (-r restarts it). Example: hdc kill
start [-r]	Starts the hdc service (-r restarts it). Example: hdc start
tconn <em>host</em>[:<em>port</em>][-remove]	Connects via TCP (IP:port). Requires tmode tcp or setting persist.hdc.mode=tcp and persist.hdc.port. Example: hdc tconn 192.168.0.100:10178
tmode usb	Restarts the daemon in USB mode.
tmode port <em>port-number</em>	Restarts the daemon, prioritizing network connections (fallback to USB).
file send <em>local remote</em>	Sends a file from host to device. Example: hdc file send E:\a.txt /data/local/tmp/a.txt

file recv [-a] remote local

将设备端文件拉取至本地主机

示例： hdc file recv /data/local/tmp/a.txt ./a.txt

fport localnode remotenode

建立端口转发：将主机端口数据转发至设备端口

示例： hdc fport tcp:1234 tcp:1080

rport remotenode localnode

建立反向端口转发：将设备端口数据转发至主机端口

示例： hdc rport tcp:1234 tcp:1080

fport ls

显示所有端口转发任务

fport rm

删除指定端口转发任务

示例： hdc fport rm tcp:1234 tcp:1080

install [-r/-s/-g] package

安装OpenHarmony应用包

示例： hdc install E:\***.hap

uninstall [-k/-s] package

卸载OpenHarmony应用

hilog

查看或捕获hilog调试信息

示例： hdc hilog

shell [command]

远程执行命令或进入交互式命令行环境

示例： hdc shell

jpid

获取JDWP调试进程列表

以下为常用hdc命令参考示例：

• 查看设备连接状态

  hdc list targets
  

• 推送文件至设备

  hdc file send  E:\a.txt  /data/local/tmp/a.txt
  

• 从设备拉取文件

  hdc file recv  /data/local/tmp/a.txt   ./a.txt
  

• 安装应用

  hdc install E:\***.hap
  

• 查看系统日志

  hdc hilog
  

• 进入交互式命令行

  hdc shell
  

• 建立TCP网络连接

  hdc tconn 192.168.0.100:10178
  

问题排查指南

使用过程中若遇异常，请按以下步骤自助排查：

• 第一步：检查PC端hdc与设备端hdcd版本是否一致（通过-v参数查看版本号）:
  • 若版本不一致，请更新至相同版本后重试；
  • 若版本一致，继续执行第二步排查；
• 第二步：检查PC端设备管理器中的设备状态是否正常（包括设备识别、驱动加载及ID显示）:
  • 若设备管理器无设备或状态异常，请通过设备串口确认USB枚举是否正常；
  • 若设备管理器显示正常： 1）执行list targets命令是否正常返回； 2）尝试执行hdc kill后重新测试；

重要提示：请确保客户端与设备端工具版本严格一致（可通过hdc -v和hdcd -v查询版本号）！

常见问题解答

• 1. list targets未显示设备：

  请参照《问题排查指南》章节逐步检查：
  1）确认设备物理连接正常；
  2）检查主机设备管理器是否识别设备；
  3）核对两端工具版本号；
  4）验证设备端hdcd服务是否正常运行；
  若问题仍未解决，可尝试以下恢复方案：
  1）执行hdc kill重启PC端服务；
  2）重启设备端；
  

• 2. Windows环境正常但Linux环境无设备：

  同问题1的排查步骤，另请注意在root权限下执行命令；
  若服务进程无法启动，请先执行sudo rm /tmp/*.pid清理临时文件，再使用sudo权限运行list targets查看设备列表
  

• 3. Windows版工具执行报错：

  1）从dailybuild或正式版SDK压缩包重新获取工具；
  2）校验文件大小、版本号及哈希值； 
  3）本工具需在命令行终端运行，不支持双击执行，且无额外组件依赖；
  

• 4. 推送文件至system分区报错[Fail]Error opening file: read-only file system：

  执行推送前请先运行以下命令：
  hdc smode
  hdc shell mount -o rw,remount /