1# hdc 2 3hdc（OpenHarmony Device Connector）是为开发人员提供的用于调试的命令行工具，通过该工具可以在windows/linux/mac系统上与设备进行交互。 4 5hdc分为三部分： 6 7**client**：运行在电脑端的进程，开发者在执行hdc命令时启动该进程，命令结束后进程退出。 8 9**server**：运行在电脑端的后台服务进程，用来管理client进程和设备端的daemon进程之间的数据交互，以及设备发现等。 10 11**daemon**：作为守护进程运行在设备端，用来响应电脑端server发来的请求。 12 13关系如下图所示： 14 15 16> **说明：** 17> 18> hdc client在启动时，默认会判断server是否正在运行，如果没有运行则会启动一个新的hdc程序作为server，运行在后台。 19> 20> hdc server运行时，默认会监听PC的8710端口，开发者可通过设置系统环境变量OHOS_HDC_SERVER_PORT自定义监听的端口号。 21 22## 环境准备 23 24下载并安装[DevEco Studio](https://developer.huawei.com/consumer/cn/deveco-studio/)，hdc应用程序可以在DevEco Studio安装位置下：DevEco Studio/sdk/default/openharmony/toolchains目录中查看。 25 26### （可选）命令行直接执行hdc程序 27 28开发者可通过命令行进入SDK的toolchains目录，在目录中执行hdc相关命令进行调试。 29为了方便在命令行中直接执行hdc程序，开发者也可以将hdc程序文件路径添加到操作系统命令搜索路径的环境变量中。 30例如，Windows系统可以添加到系统环境变量Path中。 31 32### （可选）hdc server配置 33 34通过配置对应的系统环境变量，可以修改hdc server的监听端口，日志打印级别或特性开关等，详细介绍请查看[可选配置项](#可选配置项)章节。 35 36> **说明：** 37> 38> 环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件。 39 40## hdc命令列表 41 42### 全局参数 43 44全局参数是指运行部分hdc命令时，可以跟随在hdc后面的参数，例如： 45选择指定的设备执行命令，使用-t参数： 46 47 ```shell 48 hdc -t connect-key shell echo "Hello world" 49 ``` 50 51| 参数 | 说明 | 52| -------- | -------- | 53| -t | 连接指定的目标设备，连接一台设备时为可选参数，连接多台设备时为必选参数。 | 54| -l | 可选参数，指定运行时日志等级，范围为数字0-6，默认为3（LOG_INFO）。 | 55| -s | 可选参数，指定客户端连接服务端时，服务进程的网络监听参数，格式为ip:port。 | 56| -p | 可选参数，绕过对服务进程的查询步骤，用于快速执行客户端命令。 | 57| -m | 可选参数，使用前台启动模式启动服务进程。 | 58 59### 命令列表 60| 命令 | 说明 | 61| -------- | -------- | 62| list targets | 查询已连接的所有目标设备。 | 63| wait | 等待设备正常连接。 | 64| tmode usb | 该命令已经废弃，不会实际操作设备连接通道，需要在设备设置界面通过USB调试开关进行设置。 | 65| tmode port | 打开设备网络连接通道。 | 66| tmode port close | 关闭设备网络连接通道。 | 67| tconn | 指定连接设备：通过“IP地址：端口号”来指定连接的设备。 | 68| shell | 在设备侧执行单次命令。 | 69| install | 安装指定的应用文件。 | 70| uninstall | 卸载指定的应用包。 | 71| file send | 从本地发送文件至远端设备。 | 72| file recv | 从远端设备发送文件至本地。 | 73| fport ls | 列出全部转发端口转发任务。 | 74| fport | 设置正向端口转发任务：监听“主机端口”，接收请求并进行转发， 转发到“设备端口”。 | 75| rport | 设置反向端口转发任务：监听“设备端口”，接收请求并进行转发，转发到“主机端口”。 | 76| fport rm | 删除指定的端口转发任务。 | 77| start | 启动hdc服务进程。 | 78| kill | 终止hdc服务进程。 | 79| hilog | 打印设备端的日志信息。 | 80| jpid | 显示设备上所有开启了JDWP调试协议的应用的PID。 | 81| track-jpid | 实时显示设备上开启了JDWP调试协议的应用的PID和应用名。 | 82| target boot| 重启目标设备。 | 83| <!--DelRow--> target mount | 以读写模式挂载系统分区（非root的设备不可用）。 | 84| <!--DelRow--> smode | 授予设备端hdc后台服务进程root权限， 使用-r参数取消授权（非root的设备不可用）。 | 85| keygen | 生成一个新的秘钥对。 | 86| version | 打印hdc版本信息，也可使用hdc -v打印版本信息。 | 87| checkserver | 获取客户进程与服务进程版本信息。 | 88 89> **说明：** 90> 91> 全局参数在使用时需要放在命令之前。 92 93## 基本使用方法 94 95在使用hdc前，请在设备上开启usb调试功能，用usb线连接设备和PC。 96 97### 查询连接的设备 98 99 ```shell 100 hdc list targets 101 ``` 102 103### 执行shell命令 104 105 ```shell 106 hdc shell echo "Hello world" 107 ``` 108 109### 获取帮助 110 111| 命令 | 说明 | 112| -------- | -------- | 113| -h [verbose] | 显示hdc相关的帮助信息。可选参数：verbose，显示详细的帮助信息。 | 114| help | 显示hdc相关的帮助信息。 | 115 116显示hdc相关的帮助信息，命令格式如下： 117 118 ```shell 119 hdc -h [verbose] 120 hdc help 121 ``` 122 123**返回值：** 124| 返回值 | 说明 | 125| -------- | -------- | 126| OpenHarmony device connector(HDC) ...<br/>---------------------------------global commands:----------------------------------<br/>-h/help [verbose] - Print hdc help, 'verbose' for more other cmds<br/>..._（此处省略详细帮助信息）_ | hdc命令使用帮助信息。| 127 128**使用方法：** 129 130```shell 131hdc -h 132hdc help 133 134// 显示详细帮助信息 135hdc -h verbose 136``` 137 138### 使用注意事项 139 140- 使用hdc时如出现异常，可尝试通过hdc kill -r命令杀掉异常进程并重启hdc服务。 141 142- 如出现hdc list targets获取不到设备信息的情况，参见[设备无法识别](#设备无法识别)章节。 143 144## 设备连接管理 145 146### 查询设备列表 147 148通过命令list targets，查询已连接的所有目标设备。 149添加-v参数，则会打印设备详细信息。 150命令格式如下： 151 152```shell 153hdc list targets [-v] 154``` 155 156**返回值：** 157| 返回值 | 说明 | 158| -------- | -------- | 159| 设备标识符列表 | 已连接的设备标识符列表，-t参数使用的connect-key即为此信息。 | 160| [Empty] | 没有查询到设备信息。 | 161 162**使用方法：** 163 164```shell 165hdc list targets 166hdc list targets -v 167``` 168 169### 连接指定的目标设备 170 171连接单台设备时，执行命令无需指定设备标识符； 172连接了多台设备时，每次执行命令时需要使用-t参数指定目标设备的标识符，命令格式如下： 173 174 ```shell 175 hdc -t [connect-key] [command] 176 ``` 177 178 **参数：** 179 | 参数名 | 说明 | 180 | -------- | -------- | 181 | connect-key| 设备标识符，即为hdc list targets返回的信息。 | 182 | command | hdc支持的命令。 | 183 184 > **说明：** 185 > 186 > connect-key为每个设备唯一的标识符。如果通过usb连接，标识符为序列号；如果通过网络连接设备，标识符为“IP地址:端口号”。 187 188 **返回值：** 189 | 返回值 | 说明 | 190 | -------- | -------- | 191 | 命令执行返回内容 | 请参考对应命令的返回值。 | 192 | [Fail]Not match target founded, check connect-key please | 没有找到与connect-key匹配的设备。 | 193 | [Fail]Device not founded or connected | 设备未找到或尚未连接。 | 194 | [Fail]ExecuteCommand need connect-key? please confirm a device by help info | 多设备连接时需要指定一个设备。 | 195 | Unknown operation command... | 不支持的命令。 | 196 197 > **说明：** 198 > 199 > 返回的错误提示信息后续会调整优化，请勿用于自动化脚本或程序的结果判断。 200 201 **使用方法：** 202 203 该方法需要与具体的操作命令搭配使用，下面以shell命令举例： 204 205 ```shell 206 hdc list targets // 查询已连接的所有目标设备的connect-key 207 hdc -t [connect-key] shell // -t 后面添加的connect-key需要替换为指定的设备标识符 208 ``` 209 210### 等待设备正常连接 211 212命令格式如下： 213 214 ```shell 215 hdc wait // 等待设备正常连接 216 hdc -t connect-key wait // 等待指定的设备正常连接，connect-key需要替换为指定的设备标识符 217 ``` 218 219 **返回值：** 220 | 返回值 | 说明 | 221 | -------- | -------- | 222 | 无 | hdc wait命令执行后，识别到正常连接的设备后结束。 | 223 224 **使用方法：** 225 226 ```shell 227 hdc wait 228 hdc -t connect-key wait 229 ``` 230 231### 常见连接场景 232 233#### USB连接场景 234 235- 环境确认 236 237| 确认项 | 正常 | 异常处理 | 238| -------- | -------- | -------- | 239| USB调试选项 | 开启。 | 设备的USB调试模式如无法自动开启，请尝试重启设备。 | 240| USB数据连接线 | 使用USB数据连接线连接到调试PC的USB接口。 | 如使用低带宽、无数据通信功能的USB连接线可能导致无法识别HDC设备，建议更换官方USB数据连接线。 | 241| USB接口 | 主板直出USB接口（台式机为后面板的USB接口，笔记本为机身的USB接口）。 | 如使用转接头/拓展坞/台式机前面板USB接口，存在带宽低和USB同步异常等问题，会导致频繁断连，推荐使用直连方式连接PC和设备。 | 242| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容。 | 参见[环境准备章节](#环境准备)。 | 243| 驱动 | 连接HDC设备后，设备管理器通用串行总线设备存在设备"HDC Device"或"HDC Interface"。 | 参见[设备无法识别章节](#设备无法识别)。 | 244 245- 连接步骤 246 2471. PC通过USB连接设备。 248 2492. 查看已连接设备，执行以下命令： 250 251 ```shell 252 hdc list targets 253 ``` 254 255 返回值中存在对应设备的标识符，即为usb连接成功。 256 2573. 可以查询到设备后，即可运行设备相关命令和设备进行交互。如果希望不带设备标识符进行USB命令操作，需要确认设备不在tcp连接模式（hdc list targets查询的设备不包含IP:port形式的连接信息），直接连接即可，例如： 258 259 ```shell 260 hdc shell 261 ``` 262 263#### TCP连接场景 264 265 > **注意：** 266 > 267 > TCP调试功能尚未稳定，请谨慎用于生产环境。 268 269- 环境确认 270 271| 确认项 | 正常 | 异常处理 | 272| -------- | -------- | -------- | 273| 网络连接 | PC、手机设备处于同一网络。 | 连接同一WiFi或手机开启热点。 | 274| 网络状态 | telnet IP:port正常，网速稳定。 | 请选择稳定的网络连接方式。 | 275| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容。 | 参见[环境准备章节](#环境准备)。 | 276 277- 连接步骤 278 2791. 在设备设置界面打开无线调试开关。 280 2812. 记录设备界面显示的监听端口号，记为PORT，用于后面的tcp连接。 282 2833. 通过tcp连接设备（需要事先知道设备IP和打开的PORT），执行以下命令： 284 285 ```shell 286 hdc tconn IP:PORT 287 ``` 288 IP地址可在设备侧的设置里面查看到，端口号为上一步设备无线调试界面显示的端口号。 289 2904. 查看已连接设备，执行以下命令： 291 292 ```shell 293 hdc list targets 294 ``` 295 296 返回值为IP:PORT形式即为连接成功。 297 2985. 如果需要关闭TCP连接模式，可以在设备中关闭无线调试开关。 299 300#### 远程连接场景 301 302远程连接场景是指客户端通过网络远程连接服务端，客户端和服务端在不同的PC运行，服务端连接设备。 303远程连接如图所示: 304 305 306 307hdc client（客户端）在PC1中运行，hdc server（服务端）在PC2中运行，PC2中的hdc server连接设备。 308 309- 连接命令 310 311 | 命令 | 说明 | 312 | -------- | -------- | 313 | -s | 指定当前服务进程的网络监听参数。 | 314 315 远程连接使用-s参数来指定服务端的网络参数，包括地址和端口号，该设置只在当前命令执行期间有效，命令格式如下： 316 317 ```shell 318 hdc -s [ip]:[port] [command] 319 ``` 320 321 **参数：** 322 | 参数 | 说明 | 323 | -------- | -------- | 324 | ip | 指定监听的IP地址，支持IPv4和IPv6。 | 325 | port | 指定监听的端口，范围：1~65535。 | 326 | command | hdc支持的命令。 | 327 328 **返回值：** 329 | 返回值 | 说明 | 330 | -------- | -------- | 331 | Connect server failed | 与服务进程建立连接失败。 | 332 | -s content port incorrect. | 端口号超出可设置范围（1~65535）。 | 333 334 **使用方法：** 335 336 ```shell 337 # 在已有服务进程，且服务进程的网络监听参数为127.0.0.1:8710的环境中，执行查询设备命令 338 hdc -s 127.0.0.1:8710 list targets 339 ``` 340 341 > **说明：** 342 > 343 > 当命令行中明确使用 -s 参数指定服务端口时，系统将忽略OHOS_HDC_SERVER_PORT环境变量中定义的端口设置。 344 345- 连接步骤 346 347 1. 服务端配置 348 349 服务端通过USB连接到对应的HDC设备后执行以下命令： 350 351 ```shell 352 hdc kill // 关闭本地hdc服务 353 hdc -s IP:8710 -m // 启动网络转发的hdc服务 354 // 其中IP为服务端自身的IP，windows可通过ipconfig查询，unix系统可通过ifconfig查询 355 // 8710为默认端口号，也可设置为其他端口号如：18710 356 // 启动后服务端将打印日志 357 ``` 358 359 2. 客户端连接 360 361 客户端连接需要确保可以连通服务端IP地址，满足前述条件后执行以下命令： 362 363 ```shell 364 hdc -s IP:8710 [command] // 其中IP为服务端IP，8710为第一步服务端启动时设置的端口号， 365 // 如果端口号有变化，这里也需要变更。 366 // command可以为任意hdc可用命令，例如list targets 367 ``` 368 369### usb调试和无线调试切换 370 371用于连接模式切换的命令如下表所示： 372 373当前推荐通过设备端的usb调试开关和无线调试开关来控制连接通道的开启和关闭。 374 375| 命令 | 说明 | 376| -------- | -------- | 377| tmode usb | 该命令已经废弃，不会实际操作设备连接通道，需要在设备设置界面通过USB调试开关进行设置。 | 378| tmode port [port-number] | 打开设备网络连接通道：设备端daemon进程会重启，已建立的USB连接会中断，需要重新连接。 | 379| tmode port close | 关闭设备网络连接通道：设备端daemon进程会重启，已建立的USB连接会中断，需要重新连接。 | 380| tconn [IP]:[port] [-remove] | 连接指定的设备，通过“IP地址：端口号”来指定连接的设备，使用-remove参数断开连接。 | 381 3821. 打开设备网络连接通道，命令格式如下： 383 384 ```shell 385 hdc tmode port [port-number] 386 ``` 387 388 **参数：** 389 | 参数 | 参数说明 | 390 | -------- | -------- | 391 | port-number | 监听连接的网络端口号，范围:1~65535。 | 392 393 **返回值：** 394 | 返回值 | 说明 | 395 | -------- | -------- | 396 | Set device run mode successful. | 打开成功。 | 397 | [Fail]ExecuteCommand need connect-key | 打开失败，设备列表无设备，无法打开设备无线调试通道。 | 398 | [Fail]Incorrect port range | 端口号超出可设置范围（1~65535）。 | 399 400 **使用方法：** 401 402 ```shell 403 hdc tmode port 1234 404 ``` 405 406 > **注意：** 407 > 408 > 切换前，请确保条件满足：远端设备与近端PC处于同一网络，且PC可ping通远端设备IP。 409 > 410 > 如不满足以上条件请勿使用该命令进行切换。 411 412 > **说明：** 413 > 414 > 执行完毕后，远端daemon进程将会退出并重启，USB连接将会断开，需要重新连接。 415 4162. 关闭设备网络连接通道，命令格式如下： 417 418 ```shell 419 hdc tmode port close 420 ``` 421 422 **返回值：** 423 | 返回值 | 说明 | 424 | -------- | -------- | 425 | [Fail]ExecuteCommand need connect-key | 设备列表无设备，无法执行命令。 | 426 427 **使用方法：** 428 429 ```shell 430 hdc tmode port close 431 ``` 432 > **说明：** 433 > 执行完毕后，远端daemon进程将会退出并重启，USB连接将会断开，需要重新连接。 434 4353. 通过TCP连接指定的设备，命令格式如下： 436 437 ```shell 438 hdc tconn [IP]:[port] [-remove] 439 ``` 440 441 **参数：** 442 | 参数 | 参数说明 | 443 | -------- | -------- | 444 | [IP]:[port] | 设备的IP地址与端口号。 | 445 | -remove | 可选参数，断开指定设备的连接。 | 446 447 **返回值：** 448 | 返回值 | 说明 | 449 | -------- | -------- | 450 | Connect OK | 连接成功。 | 451 | [Info]Target is connected, repeat opration | 设备当前已连接。 | 452 | [Fail]Connect failed | 连接失败。 | 453 454 **使用方法：** 455 456 ```shell 457 hdc tconn 192.168.0.1:8888 458 hdc tconn 192.168.0.1:8888 -remove // 断开指定网络设备连接 459 ``` 460 461## 执行交互命令 462 463命令格式如下： 464 465 ```shell 466 hdc shell [-b bundlename] [command] 467 ``` 468 469 **参数：** 470 | 参数 | 说明 | 471 | -------- | -------- | 472 | [-b _bundlename_] | 指定可调试应用包名，在可调试应用数据目录内，以非交互式模式执行命令。<br>此参数当前仅支持以非交互式模式执行命令，不支持缺省command参数执行命令进入交互式shell会话，<br>未配置此参数默认执行路径为系统根目录。 | 473 | [command] | 需要在设备侧执行的单次命令，不同类型或版本的系统支持的command命令有所差异，可以通过hdc shell ls /system/bin查阅支持的命令列表。当前许多命令都是由[toybox](../tools/toybox.md)提供，可通过 hdc shell toybox --help 获取命令帮助。<br>缺省该参数，hdc将会启动一个交互式的shell会话，开发者可以在命令提示符下输入命令，比如 ls、cd、pwd 等。 | 474 475 **返回值：** 476 | 返回值 | 说明 | 477 | -------- | -------- | 478 | 交互命令返回内容 | 返回内容详情请参见其他交互命令返回内容。 | 479 | /bin/sh: XXX : inaccessible or not found | 不支持的交互命令。 | 480 | [Fail]具体失败信息 | 执行失败，参见[hdc错误码章节](#hdc错误码)。 | 481 482 **使用方法：** 483 484 ```shell 485 # 进入交互式模式执行命令 486 hdc shell 487 488 # 以非交互式模式执行命令 489 hdc shell ps -ef 490 491 # 查询全部可用命令 492 hdc shell help -a 493 494 # 在指定包名的应用数据目录内以非交互式模式执行命令，支持touch、rm、ls、stat、cat、mkdir命令。 495 hdc shell -b com.example.myapplication ls data/storage/el2/base/ 496 ``` 497 498 > **说明：** 499 > 500 > 使用参数[-b _bundlename_]指定包名，应满足条件：指定包名的已安装应用为“使用调试证书签名的应用”， 如何申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。 501 502## 应用管理 503 504| 命令 | 说明 | 505| -------- | -------- | 506| install _src_ | 安装指定的应用文件。 | 507| uninstall _packageName_ | 卸载指定的应用包package包名。 | 508 5091. 安装APP package，命令格式如下： 510 511 ```shell 512 hdc install [-r|-s] src 513 ``` 514 515 **参数：** 516 | 参数名 | 说明 | 517 | -------- | -------- | 518 | src| 应用安装包的文件名。 | 519 | -r | 替换已存在应用（.hap）。 | 520 | -s | 安装一个共享包（.hsp）。 | 521 522 **返回值：** 523 | 返回值 | 说明 | 524 | -------- | -------- | 525 | AppMod finish | 成功情况下返回安装信息和AppMod finish。 | 526 | 具体安装失败原因 | 失败情况下返回具体安装失败信息。 | 527 528 **使用方法：** 529 530 以安装example.hap包为例： 531 532 ```shell 533 hdc install E:\example.hap 534 ``` 535 5362. 卸载应用，命令格式如下： 537 538 ```shell 539 hdc uninstall [-k|-s] packageName 540 ``` 541 542 **参数：** 543 | 参数名 | 说明 | 544 | -------- | -------- | 545 | packageName | 应用安装包。 | 546 | -k | 保留/data和/cache目录。 | 547 | -s | 卸载共享包。 | 548 549 **返回值：** 550 | 返回值 | 说明 | 551 | -------- | -------- | 552 | AppMod finish | 成功情况下返回卸载信息和AppMod finish。 | 553 | 具体卸载失败原因 | 失败情况下返回具体卸载失败信息。 | 554 555 **使用方法：** 556 557 以卸载com.example.hello包为例： 558 559 ```shell 560 hdc uninstall com.example.hello 561 ``` 562 563## 文件传输 564 565| 命令 | 说明 | 566| -------- | -------- | 567| file send _localpath remotepath_ | 从本地发送文件至远端设备。 | 568| file recv _remotepath localpath_ | 从远端设备发送文件至本地。 | 569 5701. 从本地发送文件至远端设备，命令格式如下： 571 572 ```shell 573 hdc file send [-a|-sync|-z|-m|-b bundlename] localpath remotepath 574 ``` 575 576 **参数：** 577 | 参数名 | 说明 | 578 | -------- | -------- | 579 | _localpath_ | 本地待发送的文件路径。 | 580 | _remotepath_ | 远程待接收的文件路径。 | 581 | -a | 保留文件时间戳。 | 582 | -sync | 只传输文件mtime有更新的文件。 | 583 | -z | 通过LZ4格式压缩传输，此功能未开放，请勿使用。 | 584 | -m | 文件传输时同步文件DAC权限，uid，gid，MAC权限。 | 585 | -b | 传输指定的可调试应用进程应用数据目录下的文件。 | 586 | _bundlename_ | 可调试应用进程的包名。 | 587 588 **返回值：** 589 590 文件发送成功，返回传输成功的结果信息。文件发送失败，返回传输失败的具体信息。 591 592 **使用方法：** 593 594 ```shell 595 hdc file send E:\example.txt /data/local/tmp/example.txt 596 hdc file send -b com.example.myapplication a.txt data/storage/el2/base/b.txt 597 ``` 598 599 > **说明：** 600 > 601 > 使用方法中，`hdc file send -b com.example.myapplication a.txt data/storage/el2/base/b.txt`指定了-b参数，将传输本地当前目录下的文件a.txt到包名为com.example.myapplication应用数据目录，传输到相对路径data/storage/el2/base/下，并重命名为b.txt。 602 > 603 > 使用参数[-b _bundlename_]指定包名，应满足条件：指定包名的已安装应用为“使用调试证书签名的应用”， 如何申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。 604 6052. 从远端设备发送文件至本地，命令格式如下： 606 607 ```shell 608 hdc file recv [-a|-sync|-z|-m|-b bundlename] remotepath localpath 609 ``` 610 611 **参数：** 612 | 参数名 | 说明 | 613 | -------- | -------- | 614 | _localpath_ | 本地待接收的文件路径。 | 615 | _remotepath_ | 远程待发送的文件路径。 | 616 | -a | 保留文件时间戳。 | 617 | -sync | 只传输文件mtime有更新的文件。 | 618 | -z | 通过LZ4格式压缩传输，此功能未开放，请勿使用。 | 619 | -m | 文件传输时同步文件DAC权限，uid，gid，MAC权限。 | 620 | -b | 传输指定的可调试应用进程应用数据目录下的文件。 | 621 | _bundlename_ | 可调试应用进程的包名。 | 622 623 **返回值：** 624 625 文件接收成功，返回传输成功的结果信息。文件接收失败，返回传输失败的具体信息。 626 627 **使用方法：** 628 629 ```shell 630 hdc file recv /data/local/tmp/a.txt ./a.txt 631 hdc file recv -b com.example.myapplication data/storage/el2/base/b.txt a.txt 632 ``` 633 634 > **说明：** 635 > 636 > 使用方法中，`hdc file recv -b com.example.myapplication data/storage/el2/base/b.txt a.txt`指定了-b参数，将传输名为com.example.myapplication可调试应用进程的应用数据相对路径data/storage/el2/base/下的文件b.txt到本地当前目录下，并重命名为a.txt。 637 > 638 > 使用参数[-b _bundlename_]指定包名，应满足条件：指定包名的已安装应用为“使用调试证书签名的应用”， 如何申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。 639 640## 端口转发 641 642| 命令 | 说明 | 643| -------- | -------- | 644| fport ls | 列出全部转发端口转发任务。 | 645| fport _localnode remotenode_ | 设置正向端口转发任务：监听“主机端口”，接收请求并进行转发， 转发到“设备端口”。 | 646| rport _remotenode localnode_ | 设置反向端口转发任务：监听“设备端口”，接收请求并进行转发，转发到“主机端口”。 | 647| fport rm _taskstr_ | 删除指定的端口转发任务。 | 648 649PC端支持的端口转发类型：tcp。 650 651设备端支持的端口转发类型：tcp，dev，localabstract，localfilesystem，jdwp，ark。 652 6531. 列出全部转发端口转发任务，命令格式如下： 654 655 ```shell 656 hdc fport ls 657 ``` 658 659 **返回值：** 660 | 返回值 | 说明 | 661 | -------- | -------- | 662 | tcp:1234 tcp:1080 [Forward] | 正向端口转发任务。 | 663 | tcp:2080 tcp:2345 [Reverse] | 反向端口转发任务。 | 664 | [empty] | 无端口转发任务。 | 665 666 **使用方法：** 667 668 ```shell 669 hdc fport ls 670 ``` 671 6722. 设置正向端口转发任务，执行后将设置指定的“主机端口”转发数据到“设备端口”转发任务，命令格式如下： 673 674 ```shell 675 hdc fport localnode remotenode 676 ``` 677 678 **返回值：** 679 | 返回值 | 说明 | 680 | -------- | -------- | 681 | Forwardport result:OK | 端口转发任务设置正常。 | 682 | [Fail]Incorrect forward command | 端口转发任务设置失败，端口转发参数错误。 | 683 | [Fail]TCP Port listen failed at XXXX | 端口转发任务设置失败，本地转发端口被占用。 | 684 685 **使用方法：** 686 687 ```shell 688 hdc fport tcp:1234 tcp:1080 689 ``` 690 6913. 设置反向端口转发任务，执行后将设置指定的“设备端口”转发数据到“主机端口”转发任务，命令格式如下： 692 693 ```shell 694 hdc rport remotenode localnode 695 ``` 696 697 **返回值：** 698 | 返回值 | 说明 | 699 | -------- | -------- | 700 | Forwardport result:OK | 端口转发任务设置正常。 | 701 | [Fail]Incorrect forward command | 端口转发任务设置失败，端口转发参数错误。 | 702 | [Fail]TCP Port listen failed at XXXX | 端口转发任务设置失败，本地转发端口被占用。 | 703 704 **使用方法：** 705 706 ```shell 707 hdc rport tcp:1234 tcp:1080 708 ``` 7094. 删除端口转发任务，执行后将指定的转发任务删除，命令格式如下： 710 711 ```shell 712 hdc fport rm taskstr 713 ``` 714 715 **参数：** 716 | 参数 | 说明 | 717 | -------- | -------- | 718 | _taskstr_ | 端口转发任务，形如 tcp:XXXX tcp:XXXX。 | 719 720 **返回值：** 721 | 返回值 | 说明 | 722 | -------- | -------- | 723 | Remove forward ruler success, ruler:tcp:XXXX tcp:XXXX | 端口转发任务删除正常。 | 724 | [Fail]Remove forward ruler failed, ruler is not exist tcp:XXXX tcp:XXXX | 端口转发任务删除失败，不存在指定的转发任务。 | 725 726 **使用方法：** 727 728 ```shell 729 hdc fport rm tcp:1234 tcp:1080 730 ``` 731 732## 服务进程管理 733 734| 命令 | 说明 | 735| -------- | -------- | 736| start [-r] | 启动hdc服务进程，使用-r参数触发服务进程重新启动。 | 737| kill [-r] | 终止hdc服务进程，使用-r参数触发服务进程重新启动。 | 738| -p | 绕过对服务进程的查询步骤，用于快速执行客户端命令。 | 739| -m | 使用前台启动模式启动服务进程。 | 740 741 7421. 启动hdc服务进程，命令格式如下： 743 744 ```shell 745 hdc start [-r] 746 ``` 747 748 **返回值：** 749 | 返回值 | 说明 | 750 | -------- | -------- | 751 | 无返回值 | 服务进程启动成功。 | 752 753 **使用方法：** 754 755 ```shell 756 hdc start 757 hdc start -r // 服务进程启动状态下，触发服务进程重新启动 758 ``` 759 760 > **说明：** 761 > 762 > 当启动hdc服务进程且系统未检测到运行的服务进程时，日志等级的设置优先级如下：若同时指定了-l参数和配置了OHOS_HDC_LOG_LEVEL环境变量，则使用环境变量配置的日志等级；如果仅指定了-l参数，则采用该参数配置的日志等级；若两者均未指定，则服务进程将以默认的LOG_INFO等级启动。 763 7642. 终止hdc服务进程，命令格式如下： 765 766 ```shell 767 hdc kill [-r] 768 ``` 769 770 **返回值：** 771 | 返回值 | 说明 | 772 | -------- | -------- | 773 | Kill server finish | 服务进程终止成功。 | 774 | [Fail]具体失败信息 | 服务进程终止失败。 | 775 776 **使用方法：** 777 778 ```shell 779 hdc kill 780 hdc kill -r // 重启并终止服务进程 781 ``` 782 7833. 绕过对服务进程的查询步骤，用于快速执行客户端命令，命令格式如下： 784 785 ```shell 786 hdc -p [command] 787 ``` 788 789 **参数：** 790 | 参数 | 说明 | 791 | -------- | -------- | 792 | command | hdc支持的命令。 | 793 794 **返回值：** 795 | 返回值 | 说明 | 796 | -------- | -------- | 797 | Connect server failed | 与服务进程建立连接失败。 | 798 799 **使用方法：** 800 801 ```shell 802 # 启动后台服务进程 803 hdc start 804 # 跳过进程查询，直接执行命令 805 hdc -p list targets 806 ``` 807 808 > **说明：** 809 > 810 > 在未指定 -p 参数的情况下直接执行 command 命令时，客户端将首先检查本地是否已有运行的服务进程。若系统未检测到运行的服务进程，客户端将自动启动服务进程，并建立连接以传递命令；若系统检测到运行的服务进程，客户端将直接与该后台服务建立连接并下发相应的命令。 811 8124. 使用前台启动模式启动服务进程，命令格式如下： 813 814 ```shell 815 hdc -m 816 ``` 817 818 **返回值：** 819 | 返回值 | 说明 | 820 | -------- | -------- | 821 | Initial failed | 服务进程初始化失败。 | 822 | [I][_1970-01-01 00:00:00.000_][_abcd_][_session.cpp:25_] _Program running. Ver: X.X.Xa Pid:12345_ | 正常打印对应等级的日志，显示服务端活动状态。 | 823 824 **使用方法：** 825 826 ```shell 827 # 指定当前服务进程的网络监听参数并启动服务进程 828 hdc -s 127.0.0.1:8710 -m 829 ``` 830 831 > **说明：** 832 > 833 > 1. 使用前台启动参数时，可通过附加 -s 参数来指定服务进程的网络监听参数。如果既没有使用 -s 指定网络监听参数，也没有配置环境变量OHOS_HDC_SERVER_PORT配置监听端口，系统将采用默认网络监听参数:127.0.0.1:8710。 834 > 2. 在服务进程前台启动模式下，系统默认的日志输出等级设置为 LOG_DEBUG。如需变更日志等级，可通过结合使用 -l 参数来进行相应的调整。 835 > 3. 在运行环境中，仅允许单一的服务进程实例存在。若运行环境中已存在一个活跃的后台服务进程，那么尝试在前台启动新的服务进程实例将不会成功。 836 837## 设备操作 838 839| 命令 | 说明 | 840| -------- | -------- | 841| hilog [-h] | 打印设备端的日志信息，可通过hdc hilog -h查阅支持的参数列表。 | 842| jpid | 显示设备上所有开启了JDWP调试协议的应用的PID。 | 843| track-jpid [-a\|-p] | 实时显示设备上开启了JDWP调试协议的应用的PID和应用名，不加参数只显示debug的应用的进程，使用-a参数显示debug和release应用的进程，使用-p参数不显示debug和release的标签。 | 844| target boot [-bootloader\|-recovery] | 重启目标设备，使用-bootloader参数重启后进入fastboot模式，使用-recovery参数重启后进入recovery模式。 | 845| target boot [MODE] | 重启目标设备，加参数重启后进入相应的模式，其中MODE为/bin/begetctl命令中reboot支持的参数。 | 846| <!--DelRow--> target mount | 以读写模式挂载系统分区（设备root后支持此命令）。 | 847| <!--DelRow--> smode [-r] | 授予设备端hdc后台服务进程root权限， 使用-r参数取消授权（设备root后支持此命令）。 | 848 8491. 打印设备端的日志信息，命令格式如下： 850 851 ```shell 852 hdc hilog [-h] 853 ``` 854 855 **参数：** 856 | 参数 | 说明 | 857 | -------- | -------- | 858 | [-h] | hilog支持的参数，可通过hdc hilog -h查阅支持的参数列表。 | 859 860 **返回值：** 861 | 返回值 | 说明 | 862 | -------- | -------- | 863 | 返回具体信息 | 抓取的日志信息。 | 864 865 **使用方法：** 866 867 ```shell 868 hdc hilog 869 ``` 870 8712. 显示设备上所有开启了JDWP调试协议的进程的PID，命令格式如下： 872 873 ```shell 874 hdc jpid 875 ``` 876 877 **返回值：** 878 | 返回值 | 说明 | 879 | -------- | -------- | 880 | 进程号列表 | 开启了JDWP调试协议的应用的PID。 | 881 | [empty] | 无开启了JDWP调试协议的进程。 | 882 883 **使用方法：** 884 885 ```shell 886 hdc jpid 887 ``` 888 8893. 实时显示设备上开启了JDWP调试协议的进程的PID和应用名，命令格式如下： 890 891 ```shell 892 track-jpid [-a|-p] 893 ``` 894 895 **参数：** 896 | 参数 | 说明 | 897 | -------- | -------- | 898 | 不加参数 | 只显示debug的应用的进程号和包名/进程名。 | 899 | -a | 显示debug和release应用的进程号和包名/进程名。 | 900 | -p | 显示debug和release应用的进程号和包名/进程名，但不显示debug和release的标签。 | 901 902 **返回值：** 903 | 返回值 | 说明 | 904 | -------- | -------- | 905 | 进程号和包名/进程名列表 | - | 906 | [empty] | 不加参数时表示无开启了JDWP调试协议的debug应用的进程，使用-a或-p参数时表示无开启了JDWP调试协议的进程。 | 907 908 **使用方法：** 909 910 ```shell 911 hdc track-jpid 912 ``` 913 9144. 重启目标设备，命令格式如下： 915 916 ```shell 917 target boot [-bootloader|-recovery] 918 target boot [MODE] 919 ``` 920 921 **参数：** 922 | 参数名 | 说明 | 923 | -------- | -------- | 924 | 不加参数| 重启设备。 | 925 | -bootloader| 重启后进入fastboot模式。 | 926 | -recovery | 重启后进入recovery模式。 | 927 | MODE | 重启后进入MODE模式，MODE为/bin/begetctl命令中reboot支持的参数。<br> 可通过hdc shell "/bin/begetctl -h \| grep reboot"查看。 | 928 929 **使用方法：** 930 931 ```shell 932 hdc target boot -bootloader // 重启后进入fastboot模式 933 hdc target boot -recovery // 重启后进入recovery模式 934 hdc target boot shutdown // 关机 935 ``` 936 937<!--Del--> 9385. 以读写模式挂载系统分区，命令格式如下： 939 940 ```shell 941 hdc target mount 942 ``` 943 944 **返回值：** 945 | 返回值 | 说明 | 946 | -------- | -------- | 947 | Mount finish | 挂载成功 | 948 | [Fail]Mount failed | 挂载失败 | 949 950 **使用方法：** 951 952 ```shell 953 hdc target mount 954 ``` 955 956 > **说明：** 957 > 958 > 设备root后才支持此命令，对系统分区的修改存在一定的风险，请谨慎使用。 959 9606. 授予设备端hdc后台服务进程root权限，命令格式如下： 961 962 ```shell 963 hdc smode [-r] 964 ``` 965 966 **返回值：** 967 | 返回值 | 说明 | 968 | -------- | -------- | 969 | 无返回值 | 授予权限成功 | 970 | [Fail]具体失败信息 | 授予权限失败 | 971 972 **使用方法：** 973 974 ```shell 975 hdc smode 976 hdc smode -r // 取消root权限 977 ``` 978 979 > **说明：** 980 > 981 > 设备root后才支持此命令。 982 983<!--DelEnd--> 984 985## 安全相关命令 986 987| 命令 | 说明 | 988| -------- | -------- | 989| keygen FILE | 生成一个新的秘钥对，并将私钥和公钥分别保存到FILE和FILE.pub，其中文件名FILE可自定义。 | 990 9911. 生成一个新的秘钥对，命令格式如下： 992 993 ```shell 994 hdc keygen FILE 995 ``` 996 997 **参数：** 998 | 参数 | 说明 | 999 | -------- | -------- | 1000 | FILE | FILE为自定义的文件名。 | 1001 1002 **使用方法：** 1003 1004 ```shell 1005 hdc keygen key // 在当前目录下生成key和key.pub文件 1006 ``` 1007 1008## 查询版本号 1009 1010| 命令 | 说明 | 1011| -------- | -------- | 1012| -v/version | 打印hdc版本信息。 | 1013| checkserver | 获取客户端与服务进程版本。 | 1014 10151. 显示hdc的版本信息，命令格式如下： 1016 1017 ```shell 1018 hdc -v/version 1019 ``` 1020 1021 **返回值：** 1022 | 返回值 | 说明 | 1023 | -------- | -------- | 1024 | Ver: X.X.Xa | hdc（SDK）的版本信息。 | 1025 1026 **使用方法：** 1027 1028 ```shell 1029 hdc -v 或 hdc version 1030 ``` 1031 10322. 获取客户端与服务进程版本，命令格式如下： 1033 1034 ```shell 1035 hdc checkserver 1036 ``` 1037 1038 **返回值：** 1039 | 返回值 | 说明 | 1040 | -------- | -------- | 1041 | Client version: Ver: X.X.Xa, Server version: Ver: X.X.Xa | client（客户端），server（服务进程）版本号。 | 1042 1043 **使用方法：** 1044 1045 ```shell 1046 hdc checkserver 1047 ``` 1048 1049## hdc调试日志 1050 1051### server端日志 1052 1053#### 指定运行时日志等级 1054 1055hdc运行时日志等级，默认为LOG_INFO，命令格式如下： 1056 1057 ```shell 1058 hdc -l [level] [command] 1059 ``` 1060 1061 **参数：** 1062 | 参数 | 说明 | 1063 | -------- | -------- | 1064 | [level] | 指定运行时日志等级。<br/>0：LOG_OFF<br/>1：LOG_FATAL<br/>2：LOG_WARN<br/>3：LOG_INFO<br/>4：LOG_DEBUG<br/>5：LOG_ALL <br/>6：LOG_LIBUSB | 1065 | command | hdc支持的命令。 | 1066 1067 > **说明：** 1068 > 1069 > 1. 当配置运行时日志级别为6（LOG_LIBUSB）时，将激活libusb相关的增量日志输出，增量日志级别的详细程度高、数据量大，有助于精确诊断服务进程中与USB相关的异常情况。USB相关操作主要由服务进程执行，因此，只有服务进程具备打印增量日志的功能。相应地，客户端侧的日志几乎不包含增量日志信息。 1070 > 2. 指定运行时日志等级仅适用于当前进程（包括客户端与服务进程），无法更改已存在的进程日志等级。 1071 1072 **返回值：** 1073 | 返回值 | 说明 | 1074 | -------- | -------- | 1075 | 命令执行返回内容 | 请参考对应命令的返回值。 | 1076 | 日志信息 | 对应指定的运行时等级日志打印。 | 1077 1078 **使用方法：** 1079 1080 客户端打印LOG_DEBUG级别日志，以执行shell ls为例，命令示例如下: 1081 1082 ```shell 1083 hdc -l 5 shell ls 1084 ``` 1085 1086 服务进程前台模式启动指定LOG_LIBUSB级别日志，命令示例如下: 1087 1088 ```shell 1089 hdc kill && hdc -l 6 -m 1090 ``` 1091 1092 > **说明：** 1093 > `-m`参数指定以前台模式启动服务进程，可以直接观察前台日志输出，按下Ctrl+C退出进程。 1094 1095 服务进程后台启动模式指定LOG_LIBUSB级别日志，命令示例如下: 1096 1097 ```shell 1098 hdc kill && hdc -l 6 start 1099 ``` 1100 1101 > **说明：** 1102 > 以后台模式启动，可以在hdc.log中观察日志输出，日志路径可以查看**日志获取**章节的描述。 1103 1104#### 日志获取 1105 1106执行以下命令开启日志获取： 1107 1108```shell 1109hdc kill 1110hdc -l5 start 1111``` 1112 1113收集到的完整日志存放路径： 1114 1115| 平台 | 路径 | 备注 | 1116| -------- | -------- | -------- | 1117| Windows | %temp% | 实际路径参考：`C:\Users\用户名\AppData\Local\Temp` <br/>（实际使用请替换用户名变量）。 | 1118| Linux | /tmp | - | 1119| MacOS | $TMPDIR | - | 1120 1121日志相关环境变量： 1122 1123| 环境变量名称 | 默认值 | 说明 | 1124|--------------------|-----|--------------------------------| 1125| OHOS_HDC_LOG_LEVEL | 5 | 用于配置服务进程日志记录级别，日志级别详情参考：<br>[server端日志](#server端日志)指定运行时日志等级章节。 | 1126 1127环境变量配置方法： 1128 1129以下通过配置OHOS_HDC_LOG_LEVEL环境变量为例，配置环境变量值为：5，介绍环境变量配置方法。 1130 1131| 操作系统 | 配置方法 | 1132|---|---| 1133| Windows | 在**此电脑 > 属性 > 高级系统设置 > 高级 > 环境变量**中，添加环境变量名称为OHOS_HDC_LOG_LEVEL，变量值为5。配置完毕后点击确认。环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件，以生效新配置的环境变量。 | 1134| Linux | 在~/.bash_profile文件末尾追加内容export OHOS_HDC_LOG_LEVEL=5并保存后，执行`source ~/.bash_profile`生效当前环境变量。 | 1135| MacOS | 在~/.zshrc文件末尾追加内容export OHOS_HDC_LOG_LEVEL=5并保存后，执行`source ~/.zshrc`生效当前环境变量。环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件，以生效新配置的环境变量。 | 1136 1137### 设备端日志 1138 1139开启hilog日志工具，获取对应日志，命令如下： 1140 1141```shell 1142hdc shell hilog -w start // 开启hilog日志落盘 1143hdc shell ls /data/log/hilog // 查看已落盘hilog日志 1144hdc file recv /data/log/hilog // 获取hilog已落盘日志（包含内核日志） 1145``` 1146 1147## 可选配置项 1148 1149### OHOS_HDC_SERVER_PORT 1150 1151默认值：8710。 1152 1153用于设置hdc server运行时监听的端口号，该端口用于hdc client与hdc server之间的数据通讯。 1154 1155hdc server启动时，默认会监听电脑的8710端口，hdc client使用tcp协议通过此端口连接server。如果电脑的8710端口已经被使用或者希望使用其他端口，可以通过添加环境变量OHOS_HDC_SERVER_PORT到系统环境变量中来修改server启动时监听的端口号。可以设置的端口范围为1~65535。 1156 1157例如，添加变量名为：OHOS_HDC_SERVER_PORT，变量值可设置为任意未被占用的端口，如18710。 1158 1159### OHOS_HDC_LOG_LEVEL 1160 1161默认值：3。 1162 1163用于设置服务进程日志记录级别，日志级别详情参考：[server端日志](#server端日志)指定运行时日志等级章节。 1164 1165### OHOS_HDC_HEARTBEAT 1166 1167默认：心跳功能开启。 1168 1169用于设置hdc server和hdc daemon的心跳功能开关。 1170 1171hdc server和hdc daemon启动后，默认会互相发送心跳数据包，收到心跳数据包后会记录在hdc的日志中，方便后期查看设备的连接情况。 1172 1173当hdc server对应的电脑中配置环境变量OHOS_HDC_HEARTBEAT为“1”后，hdc server会关闭心跳特性；当设备连接这台电脑后，hdc server会给hdc daemon发送心跳特性关闭的信息，双方不再互相发送心跳数据包。 1174 1175设置为"1"表示关闭心跳功能；设置为其它数字表示开启心跳功能。 1176 1177## 常见问题 1178 1179### 设备无法识别 1180 1181**现象描述** 1182 1183命令行执行`hdc list targets`命令后，返回结果为`[empty]`。 1184 1185**可能原因&解决方法** 1186 1187可通过以下方式排查。 1188 1189- 情况一：查看设备管理是否显示HDC设备。 1190 1191 Windows环境： 1192 1193 在`设备管理器`>`通用串行总线设备`中是否显示`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 1194 1195 Linux环境： 1196 1197 在命令行执行`lsusb`,在返回的内容中查看是否有`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 1198 1199 MacOS环境： 1200 1201 使用`系统信息`或`系统概述`来查看USB设备，步骤如下： 1202 1203 1. 按住键盘上的Option键，点按菜单。 1204 1205 2. 选取`系统信息`或`系统概述`。 1206 1207 3. 在随后出现的窗口中，选择左边的`USB`。 1208 1209 4. 在随后显示的设备树查看是否有`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 1210 1211 **可采取的解决方法** 1212 1213 以上环境如没有显示HDC设备，则说明无法识别设备，可以根据实际场景尝试以下方法： 1214 1215 - 使用其他USB物理接口。 1216 - 更换USB数据连接线。 1217 - 使用其他计算机调试。 1218 - 设备开启USB调试模式。 1219 - 设备出现弹窗点击允许调试。 1220 - 如可通过TCP模式连接，可执行`hdc tmode usb`命令恢复USB连接。 1221 - 设备恢复出厂设置。 1222 1223- 情况二：存在USB设备，但是驱动损坏，显示"HDC Device"⚠警告图标。 1224 1225 现象描述：该问题常见于Windows环境，现象为`设备管理器`>`通用串行总线设备`中，`HDC Device`显示为黄标警告，且描述信息为该设备无法正常工作。可尝试重新安装驱动解决，如重新安装驱动无法解决，可以尝试更换USB连接数据线/拓展坞/USB接口。 1226 1227 **重新安装驱动的方法** 1228 1229 1. 打开`设备管理器`，右键点击存在警告图标的`HDC Device`； 1230 1231 2. 出现的菜单中点击`更新驱动程序`； 1232 1233 3. 出现的提示窗口（第1/3个）中，选取`浏览我的电脑以查找驱动程序`； 1234 1235 4. 出现的提示窗口（第2/3个）中，选取`让我从计算机上的可用驱动程序列表中选取`； 1236 1237 5. 出现的提示窗口（第3/3个）中，取消勾选`显示兼容硬件`，选择厂商：`WinUSB设备`，选择型号：`WinUSB设备`，选择完成后点击`下一步`按钮。 1238 1239- 情况三：连接设备时出现`[Fail]Failed to communicate with daemon`。 1240 1241 现象描述：命令行执行hdc相关命令，执行失败返回`[Fail]Failed to communicate with daemon`。 1242 1243 可能存在以下原因，可参考排查： 1244 1245 - hdc或SDK版本与设备不匹配: 如果设备更新到最新版本，可更新hdc或SDK工具至最新版本。 1246 - 端口被占用： 1247 1248 常见于hdc和hdc_std使用同一端口，同时运行时OHOS_HDC_SERVER_PORT设置的端口互相冲突（未设置则使用默认端口8710，仍然会冲突），注意只运行其中一个。其他软件占用hdc默认端口也会导致该问题发生。 1249 1250- 情况四：连接设备时出现`Connect server failed`。 1251 1252 出现该现象，可能有如下原因： 1253 1254 - **端口抢占** 1255 1256 解决方法如下： 1257 1. 排查自带hdc的软件进程。 1258 1259 包括自带hdc的软件（DevEco Studio、DevEco Testing），如存在请关闭这些软件后再执行hdc相关命令。 1260 1261 2. 查询HDC端口情况。 1262 1263 以设置的OHOS_HDC_SERVER_PORT为8710端口为例，在不同平台查询命令如下： 1264 1265 Unix： 1266 1267 ```shell 1268 netstat -an |grep 8710 1269 ``` 1270 1271 Windows: 1272 1273 ```shell 1274 netstat -an |findstr 8710 1275 ``` 1276 1277 如存在抢占的软件，可以关闭该软件进程或者更换OHOS_HDC_SERVER_PORT环境变量为其他端口号。 1278 1279 3. 排查未关闭的其他版本hdc server。 1280 1281 Windows： 1282 1283 使用`任务管理器`>`详细信息`查询hdc.exe进程,右键打开文件所在位置，核对位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc.exe进程(hdc kill或者任务管理器直接结束进程)并重新执行hdc命令。（关闭hdc server后执行hdc命令会重新启动hdc server） 1284 1285 Unix： 1286 1287 使用`ps -ef |grep hdc`查询hdc后台server进程，核对进程启动位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc进程(hdc kill或者kill -9 hdc进程的PID)并重新执行hdc命令。（关闭hdc server后执行hdc命令会重新启动hdc server） 1288 1289 - **注册表异常** 1290 1291 解决方法：清理注册表，步骤如下： 1292 1293 1. 同时按下`Win`+`R`键，启动运行工具，输入栏输入`regedit`打开注册表。 1294 2. 注册表地址栏输入以下内容并按下`回车`，即可进入USB类设备驱动程序的注册表。 1295 1296 ```shell 1297 计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{88bae032-5a81-49f0-bc3d-a4ff138216d6} 1298 ``` 1299 1300 3. 找到`UpperFilters`键，右键`修改`编辑，**备份**并清空其中数值数据内容（如清空后无法解决问题可依照备份恢复）。 1301 4. 刷新设备管理器/插拔USB接口/重启计算机。 1302 1303<!--Del--> 1304 1305**linux系统非root权限运行hdc无法找到设备** 1306 1307linux环境可以选择开启非root用户USB设备操作权限，方法如下： 1308 1309- （临时权限）设置USB设备操作权限最大化: 1310 1311 ```shell 1312 sudo chmod -R 777 /dev/bus/usb/ 1313 ``` 1314 1315- （永久权限）永久修改USB设备权限: 1316 1317 1. 使用lsusb找出USB设备的vendorID和productID。 1318 1319 2. 创建一个新的udev规则。 1320 1321 编辑udev加载规则，用设备的“idVendor”和“idProduct”来替换默认值。 1322 1323 MODE="0666"来表示USB设备的权限GROUP；GROUP代表用户组，要确保此时登录的系统用户在该用户组中： 1324 1325 ```shell 1326 sudo vim /etc/udev/rules.d/90-myusb.rules 1327 SUBSYSTEMS=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303", GROUP="users", MODE="0666" 1328 ``` 1329 1330 3. 重启电脑或重新加载udev规则： 1331 1332 ```shell 1333 sudo udevadm control --reload 1334 ``` 1335 1336> **注意：** 1337> **开启非root用户USB设备操作权限**可以解决Linux环境在非root权限下使用hdc无法找到设备的情况，但权限最大化**可能存在潜在安全问题**，请开发者根据使用场景自行评估是否开启。 1338 1339<!--DelEnd--> 1340 1341### hdc无法运行 1342 1343**现象描述** 1344 1345使用命令行执行hdc.exe/hdc 二进制文件无法运行。 1346 1347**可能原因&解决方法** 1348 1349- 运行环境异常 1350 1351 Linux运行环境：建议使用Ubuntu18.04及以上64版本，如出现libc++.so引用错误，请使用ldd/readelf等命令检查库引用。 1352 1353 MacOS运行环境：建议使用MacOS 11及以上版本。 1354 1355 Windows运行环境：建议使用Windows10/Windows11 64位版本，如低版本缺失WinUSB库/驱动，请使用Zadig工具更新。对于符合设备，需要使用Zadig工具安装libusb-win32驱动。详情请见：[Zadig链接](https://github.com/pbatard/libwdi/releases)。 1356 1357- 运行方式不当：请使用命令行依照正确命令运行hdc工具，而非鼠标双击文件。 1358 1359### 其他问题排查常用步骤 1360 13611. 命令行执行`hdc list targets`查看返回值。 13622. 查看`设备管理`是否有`HDC Device`。 13633. 执行`hdc kill`关闭server后，执行`hdc -l5 start`收集日志（hdc.log位于执行端TEMP目录下，不同平台目录位置存在差异，可参考[server端日志](#server端日志)）。 13644. 通过hdc.log日志定位相关问题。 1365 1366## hdc错误码 1367 1368### E003001 （命令行）指定的包名非法 1369 1370**错误信息** 1371 1372Invalid bundle name: _bundlename_ 1373 1374**错误描述** 1375 1376命令`hdc shell [-b bundlename] [command]`指定的 _bundlename_ 不是已安装的可调试应用包名，或应用目录不存在。 1377 1378**可能原因** 1379 1380* 场景一：指定的应用未安装到设备上。 1381 1382* 场景二：指定包名的应用，不是可调试应用。 1383 1384* 场景三：指定包名的应用没有启动。 1385 1386**处理步骤** 1387 1388* 场景一：确认命令指定包名的应用已安装到设备上。 1389 1390 a.可执行`hdc shell "bm dump -a | grep bundlename"`查询对应包名的应用是否已安装到设备上，预期返回信息为 _bundlename_； 1391 1392 以应用名`com.example.myapplication`为例，查询命令如下： 1393 1394 ```shell 1395 hdc shell "bm dump -a | grep com.example.myapplication" 1396 ``` 1397 1398 如应用已安装到设备上，预期返回信息： 1399 1400 ```shell 1401 com.example.myapplication 1402 ``` 1403 1404 b.如应用为可调试应用，但未安装到设备上，可执行`hdc install [app_path]`安装应用； 1405 1406 c.如应用不是可调试应用，而是release类型的应用，将不支持指定 _bundlename_ 执行命令相关功能。 1407 1408* 场景二：确认命令指定的应用是否为可调试应用，可执行`hdc shell "bm dump -n bundlename | grep appProvisionType"`查询，预期返回信息为`"appProvisionType": "debug"`。 1409 1410 以包名`com.example.myapplication`为例，可执行如下命令查询： 1411 1412 ```shell 1413 hdc shell "bm dump -n com.example.myapplication | grep appProvisionType" 1414 ``` 1415 1416 如包名对应的应用是可调试应用，预期返回信息： 1417 1418 ```shell 1419 "appProvisionType": "debug", 1420 ``` 1421 1422 构建可调试应用需要使用调试证书进行签名，申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。 1423 1424* 场景三：确定命令指定的应用已启动。 1425 1426 a.启动应用后，系统会挂载相应的资源目录，可执行`hdc shell "mount |grep bundlename"`查询应用启动后的资源目录挂载情况。 1427 1428 以应用名`com.example.myapplication`为例，可执行如下命令查询是否已挂载资源目录： 1429 1430 ```shell 1431 hdc shell "mount |grep com.example.myapplication" 1432 ``` 1433 1434 如已挂载相应的资源目录，预期返回挂载信息（返回内容以实际挂载情况为准，此处不作展示）。 1435 1436 如未挂载相应的资源目录，预期无返回信息。 1437 1438 b.如未挂载相应的资源目录，可以通过手动点击应用或通过`aa`相关命令启动应用。 1439 1440 以应用名`com.example.myapplication`模块名`EntryAbility`为例，启动命令为： 1441 1442 ```shell 1443 hdc shell aa start -b com.example.myapplication -a EntryAbility 1444 ``` 1445 1446 更多详细用法请参考[aa命令介绍](../tools/aa-tool.md)。 1447 1448### E003002 命令行指定的参数不支持交互模式 1449 1450**错误信息** 1451 1452Unsupport interactive shell command option 1453 1454**错误描述** 1455 1456命令`hdc shell [-b bundlename] [command]`不支持“交互模式”命令行。 1457 1458**可能原因** 1459 1460命令`hdc shell [-b bundlename] [command]`指定的 _command_ 参数为空值。 1461 1462**处理步骤** 1463 1464确认命令的 _command_ 参数不为空值，详细使用方法参考[执行交互命令介绍](#执行交互命令)。 1465 1466### E003003 不支持的命令行参数 1467 1468**错误信息** 1469 1470Unsupported shell option: _option_ 1471 1472**错误描述** 1473 1474命令`hdc shell [-b bundlename] [command]`存在不支持的命令行参数 _option_ 。 1475 1476**可能原因** 1477 1478命令`hdc shell [-b bundlename] [command]`指定了如`-f`、`-B`等不支持的命令行参数（参数区分大小写）。 1479 1480**处理步骤** 1481 1482请使用当前版本支持的命令行参数，如`-b`参数。 1483 1484### E003004 存在设备不支持的命令行参数 1485 1486**错误信息** 1487 1488Device does not supported this shell command 1489 1490**错误描述** 1491 1492命令`hdc shell [-b bundlename] [command]`存在设备不支持的命令行参数。 1493 1494**可能原因** 1495 1496设备系统版本较低，不支持对应新增的命令行参数功能。 1497 1498**处理步骤** 1499 1500升级设备系统版本到最新。 1501 1502### E003005 （命令行）缺少参数 1503 1504**错误信息** 1505 1506The parameter is missing, correct your input by referring below: _Usage_ 1507 1508**错误描述** 1509 1510`hdc shell [-b bundlename] [command]`命令指定选项时，缺少必要的参数。 1511 1512**可能原因** 1513 1514命令指定-b选项时，缺少 _bundlename_、 _command_ 参数，参数详细释义参考[执行交互命令介绍](#执行交互命令)。 1515 1516**处理步骤** 1517 1518确认命令的 _bundlename_ 、 _command_ 参数均不为空。 1519 1520### E005101 （文件传输）指定的包名非法 1521 1522**错误信息** 1523 1524Invalid bundle name: _bundlename_ 1525 1526**错误描述** 1527 1528命令`hdc file send/recv [-b bundlename] [localpath] [remotepath]`指定的 _bundlename_ 不是已安装的可调试应用包名，或应用目录不存在。 1529 1530**可能原因** 1531 1532同错误码[E003001](#e003001-命令行指定的包名非法) 1533 1534**处理步骤** 1535 1536同错误码[E003001](#e003001-命令行指定的包名非法) 1537 1538### E005102 非法的远程路径 1539 1540**错误信息** 1541 1542Remote path: _remotepath_ is invalid, it is out of the application directory. 1543 1544**错误描述** 1545 1546命令`hdc file send [-b bundlename] [localpath] [remotepath]`指定的 _remotepath_ 表示的路径不存在或者已超出应用数据目录。 1547 1548命令`hdc file recv [-b bundlename] [remotepath] [localpath]`指定的 _remotepath_ 表示的路径不存在或者已超出应用数据目录。 1549 1550**可能原因** 1551 1552* 场景一：路径不存在。 1553 1554* 场景二：参数 _remotepath_ 包含`..`跳转符号，处理跳转后，实际目录超出了应用数据根目录。 1555 1556**处理步骤** 1557 1558检查参数 _remotepath_ 指定的应用数据目录相对路径是否真实存在。 1559 1560### E005003 （文件传输）缺少参数 1561 1562**错误信息** 1563 1564The parameter is missing, correct your input by referring below: _Usage_ 1565 1566**错误描述** 1567 1568命令`hdc file send [-b bundlename] [localpath] [remotepath]`缺少必要的参数。 1569 1570命令`hdc file recv [-b bundlename] [remotepath] [localpath]`缺少必要的参数。 1571 1572**可能原因** 1573 1574命令指定-b选项时，缺少 _bundlename_、 _localpath_、 _remotepath_ 参数，参数详细释义参考[文件传输命令介绍](#文件传输)。 1575 1576**处理步骤** 1577 1578确认命令的 _bundlename_、_localpath_、_remotepath_ 参数均不为空。 1579 1580### E005004 SDK或者设备系统版本不支持-b选项 1581 1582**错误信息** 1583 1584SDK/Device ROM doesn't support -b option. 1585 1586**错误描述** 1587 1588hdc file send/recv 命令带-b选项时，SDK中的hdc或设备系统版本不支持该选项。 1589 1590**可能原因** 1591 1592* 场景一：执行命令`hdc file send [-b bundlename] [localpath] [remotepath]`时，设备系统版本不支持-b选项。 1593 1594* 场景二：执行命令`hdc file recv [-b bundlename] [remotepath] [localpath]`时，SDK中的hdc不支持-b选项。 1595 1596**处理步骤** 1597 1598* 场景一：升级到最新系统版本。 1599 1600* 场景二：升级到最新SDK版本。 1601
