1# hdc 2 3hdc（OpenHarmony Device Connector）是为开发人员提供的用于调试的命令行工具，通过该工具可以在windows/linux/mac系统上与真实设备进行交互。 4 5## 环境准备 6 7hdc工具通过OpenHarmony SDK获取，存放于SDK的toolchains目录下，首次使用按照如下提示配置环境变量。 8 9### 配置环境变量HDC_SERVER_PORT 10 11**Windows环境变量设置方法** 12 13在**此电脑 > 属性 > 高级系统设置 > 高级 > 环境变量**中，添加HDC端口变量名为：HDC_SERVER_PORT，变量值可设置为任意未被占用的端口，如7035。 14 15 16 17环境变量配置完成后，关闭并重启DevEco Studio。 18 19**macOS环境变量设置方法** 20 211. 打开终端工具，执行以下命令，根据输出结果分别执行不同命令。 22 23 ```shell 24 echo $SHELL 25 ``` 26 27 - 如输出结果为/bin/bash，则执行以下命令，打开.bash_profile文件。 28 29 ```shell 30 vi ~/.bash_profile 31 ``` 32 33 - 如输出结果为/bin/zsh，则执行以下命令，打开.zshrc文件。 34 35 ```shell 36 vi ~/.zshrc 37 ``` 38 392. 单击字母“i”，进入**Insert**模式。 403. 输入以下内容，在PATH路径下添加HDC_SERVER_PORT端口信息。 41 42 ```shell 43 HDC_SERVER_PORT=7035 44 launchctl setenv HDC_SERVER_PORT $HDC_SERVER_PORT 45 export HDC_SERVER_PORT 46 ``` 47 484. 编辑完成后，单击**Esc**键，退出编辑模式，然后输入“:wq”，单击**Enter**键保存。 495. 执行以下命令，使配置的环境变量生效。 50 51 - 如果步骤1时打开的是.bash_profile文件，请执行如下命令： 52 53 ```shell 54 source ~/.bash_profile 55 ``` 56 57 - 如果步骤1时打开的是.zshrc文件，请执行如下命令： 58 59 ```shell 60 source ~/.zshrc 61 ``` 62 636. 环境变量配置完成后，关闭并重启DevEco Studio。 64 65### （可选）配置全局环境变量 66 67> **说明：** 68> 如未配置全局环境变量，开发者可通过命令行进入SDK的toolchains目录，在目录中执行hdc相关命令进行调试。 69 70**Windows环境变量设置方法** 71 72在**此电脑 > 属性 > 高级系统设置 > 高级 > 环境变量 > 系统变量**中，将SDK的toolchains完整路径添加到Path变量值中，具体路径信息以SDK**实际配置路径**为准。 73 74以下图示内容以本地SDK的toolchains完整路径_/User/username/sdk/openharmony/10/toolchains_为例： 75 76 77 78 79 80**Linux/macOS环境变量设置方法** 81 821. 打开终端工具，执行以下命令，根据输出结果分别执行不同命令。 83 84 ```shell 85 echo $SHELL 86 ``` 87 88 - 如输出结果为/bin/bash，则执行以下命令，打开.bash_profile文件。 89 90 ```shell 91 vi ~/.bash_profile 92 ``` 93 94 - 如输出结果为/bin/zsh，则执行以下命令，打开.zshrc文件。 95 96 ```shell 97 vi ~/.zshrc 98 ``` 99 1002. 单击字母“i”，进入**Insert**模式。 101 1023. 输入以下内容，在PATH路径下**增加**SDK路径信息，具体路径信息以SDK**实际配置路径**为准。 103 104 以下内容以本地SDK的toolchains完整路径_/User/username/sdk/openharmony/10/toolchains_为例： 105 106 ```shell 107 HDC_SDK_PATH=/User/username/sdk/openharmony/10/toolchains 108 launchctl setenv HDC_SDK_PATH $HDC_SDK_PATH # 仅MacOS需要在此执行，Linux无须执行 109 export PATH=$PATH:$HDC_SDK_PATH 110 ``` 111 1124. 编辑完成后，单击**Esc**键，退出编辑模式，然后输入“:wq”，单击**Enter**键保存。 113 1145. 执行以下命令，使配置的环境变量生效。 115 116 - 如果步骤1时打开的是.bash_profile文件，请执行如下命令： 117 118 ```shell 119 source ~/.bash_profile 120 ``` 121 122 - 如果步骤1时打开的是.zshrc文件，请执行如下命令： 123 124 ```shell 125 source ~/.zshrc 126 ``` 127 128**（Linux可选）开启非root用户USB设备操作权限** 129 130- （临时权限）设置USB设备操作权限最大化 131 132 ```shell 133 sudo chmod -R 777 /dev/bus/usb/ 134 ``` 135 136- （永久权限）永久修改USB设备权限 137 138 1. 使用lsusb找出USB设备的vendorID和productID。 139 140 2. 创建一个新的udev规则。 141 142 编辑udev加载规则，用设备的“idVendor”和“idProduct”来替换默认值。 143 144 MODE="0666"来表示USB设备的权限GROUP；GROUP代表用户组，要确保此时登录的系统用户在该用户组中： 145 146 ```shell 147 sudo vim /etc/udev/rules.d/90-myusb.rules 148 SUBSYSTEMS=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303", GROUP="users", MODE="0666" 149 ``` 150 151 3. 重启电脑或重新加载udev规则： 152 153 ```shell 154 sudo udevadm control --reload 155 ``` 156 157> **注意：** 158> **开启非root用户USB设备操作权限**可以解决Linux环境在非root权限下使用hdc无法找到设备的情况，但权限最大化**可能存在潜在安全问题**，请开发者根据使用场景自行评估是否开启。 159 160## 注意事项 161 162- 使用hdc时如出现异常，可尝试通过hdc kill -r命令杀掉异常进程并重启hdc服务。 163 164- 如出现hdc list targets获取不到设备信息的情况，可通过任务管理器查看是否有hdc进程存在。若进程存在，则通过hdc kill -r命令杀掉该进程并重启hdc服务。 165 166> **说明：** 167> 168> - 命令行中被[]修饰的参数表示可选参数。 169> - 命令行中的参数若是斜体，表示在使用时该参数需替换为具体的信息，例如：file send _local remote_命令中的local和remote，使用时需替换为本地待发送和远端待接收的文件路径。 170 171## 开发指导 172 173### 全局option相关命令 174 175| Option | 说明 | 176| -------- | -------- | 177| -t [key] [command] | 指定连接唯一标识的目标设备。标识可通过命令hdc list targets查询。 | 178| help/-h | 打印hdc帮助信息。 | 179| version/-v | 打印hdc版本信息。 | 180| -l [level] | 指定运行时日志等级，默认为LOG_INFO。 | 181| checkserver | 获取client-server版本。 | 182 1831. 显示hdc相关的帮助信息，命令格式如下： 184 185 ```shell 186 hdc -h 187 ``` 188 189 **返回值：** 190 | 返回值 | 说明 | 191 | -------- | -------- | 192 | OpenHarmony device connector(HDC) ...<br/>---------------------------------global commands:----------------------------------<br/>-h/help [verbose] - Print hdc help, 'verbose' for more other cmds<br/>..._（此处省略详细帮助信息）_ | hdc命令使用帮助信息 | 193 194 **使用方法：** 195 196 ```shell 197 hdc -h 198 ``` 199 2002. 显示hdc的版本信息，命令格式如下： 201 202 ```shell 203 hdc -v 204 ``` 205 206 **返回值：** 207 | 返回值 | 说明 | 208 | -------- | -------- | 209 | Ver: X.X.Xa | hdc（SDK）的版本信息 | 210 211 **使用方法：** 212 213 ```shell 214 hdc -v 215 ``` 216 2173. 连接设备时，若仅有一台，无需指定设备标识；若有多台，一次仅能连接一台，每次连接时需要指定连接设备的标识，命令格式如下： 218 219 ```shell 220 hdc-t [key] [command] 221 ``` 222 223 **参数：** 224 | 参数名 | 说明 | 225 | -------- | -------- | 226 | key | IP地址或USB序列号。 | 227 | command | hdc支持的命令。 | 228 229 **返回值：** 230 | 返回值 | 说明 | 231 | -------- | -------- | 232 | 命令执行返回内容 | 请参考对应命令的返回值 | 233 | [Fail]Not match target founded, check connect-key please | 连接的设备不存在 | 234 | [Fail]ExecuteCommand need connect-key? | 连接的设备不存在 | 235 | Unknown operation command... | 不支持的命令 | 236 237 **使用方法**： 238 239 该方法需要与具体的操作命令搭配使用，下面以shell命令举例： 240 241 ```shell 242 hdc list targets // 获取设备信息 243 hdc -t [key] shell // -t后面添加的key需要替换为查询到的某一个设备信息，此处COMMAND命令为shell即进入调试命令行 244 ``` 245 246 > **说明：** 247 > 一台用于开发的电脑可连接多个设备，每个设备有唯一的标识。如果通过网络连接设备，标识为IP地址；如果通过usb连接，标识为USB序列号。该命令需要跟随具体的操作命令。 248 2494. 指定运行时日志等级，默认为LOG_INFO，命令格式如下： 250 251 ```shell 252 hdc -l [level] [command] 253 ``` 254 255 **参数：** 256 | 参数 | 说明 | 257 | -------- | -------- | 258 | [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 | 259 | command | hdc支持的命令 | 260 261 **返回值：** 262 | 返回值 | 说明 | 263 | -------- | -------- | 264 | 命令执行返回内容 | 请参考对应命令的返回值 | 265 | LOG日志信息 | 对应指定的运行时等级日志打印 | 266 267 **使用方法：** 268 269 ```shell 270 hdc -l 5 shell ls 271 ``` 272 2735. 获取client-server版本，命令格式如下： 274 275 ```shell 276 hdc checkserver 277 ``` 278 279 **返回值：** 280 | 返回值 | 说明 | 281 | -------- | -------- | 282 | Client version: Ver: X.X.Xa, server version: Ver: X.X.Xa | client-server版本号 | 283 284 **使用方法：** 285 286 ```shell 287 hdc checkserver 288 ``` 289 290### 查询设备列表相关命令 291 292| 命令 | 说明 | 293| -------- | -------- | 294| list targets [-v] | 查询已连接的所有目标设备，添加-v选项，则会打印设备详细信息。 | 295 296显示所有已连接的设备列表，命令格式如下： 297 298```shell 299hdc list targets[-v] 300``` 301 302**返回值：** 303| 返回值 | 说明 | 304| -------- | -------- | 305| 设备信息 | 已连接的设备列表信息 | 306| [Empty] | 没有查询到设备信息 | 307 308**使用方法：** 309 310```shell 311hdc list targets 312hdc list targets -v 313``` 314 315### 服务进程相关命令 316 317| 命令 | 说明 | 318| -------- | -------- | 319| target mount | 读写模式挂载系统分区。（user不可用） | 320| target boot | 重启目标设备，查看目标列表可用list targets命令。 | 321| smode [-r] | 授予设备端hdc后台服务进程root权限， 使用-r参数取消授权。（user不可用） | 322| kill [-r] | 终止hdc服务进程，使用-r参数触发服务进程重新启动。 | 323| start [-r] | 启动hdc服务进程，使用-r参数触发服务进程重新启动。 | 324 3251. 以读写模式挂载系统分区，命令格式如下： 326 327 ```shell 328 hdc target mount 329 ``` 330 331 **返回值：** 332 | 返回值 | 说明 | 333 | -------- | -------- | 334 | Mount finish | 挂载成功 | 335 | [Fail]具体失败信息 | 挂载失败 | 336 337 **使用方法：** 338 339 ```shell 340 hdc target mount 341 ``` 342 3432. 授予设备端hdc后台服务进程root权限，命令格式如下： 344 345 ```shell 346 hdc smode [-r] 347 ``` 348 349 **返回值：** 350 | 返回值 | 说明 | 351 | -------- | -------- | 352 | 无返回值 | 授予权限成功 | 353 | [Fail]具体失败信息 | 授予权限失败 | 354 355 **使用方法：** 356 357 ```shell 358 hdc smode 359 hdc smode -r // 取消root权限 360 ``` 361 3623. 终止hdc服务进程，命令格式如下： 363 364 ```shell 365 hdc kill [-r] 366 ``` 367 368 **返回值：** 369 | 返回值 | 说明 | 370 | -------- | -------- | 371 | Kill server finish | 服务进程终止成功 | 372 | [Fail]具体失败信息 | 服务进程终止失败 | 373 374 **使用方法：** 375 376 ```shell 377 hdc kill 378 hdc kill -r // 重启并终止服务进程 379 ``` 380 3814. 启动hdc服务进程，命令格式如下： 382 383 ```shell 384 hdc start [-r] 385 ``` 386 387 **返回值：** 388 | 返回值 | 说明 | 389 | -------- | -------- | 390 | 无返回值 | 服务进程启动成功 | 391 | [Fail]具体失败信息 | 服务进程启动失败 | 392 393 **使用方法：** 394 395 ```shell 396 hdc start 397 hdc start -r // 服务进程启动状态下，触发服务进程重新启动 398 ``` 399 400### 网络相关命令 401 402| 命令 | 说明 | 403| -------- | -------- | 404| fport ls | 列出全部转发端口转发任务。 | 405| fport _local remote_ | 设置正向端口转发任务：监听“主机端口”，接收请求并进行转发， 转发到“设备端口”。 | 406| fport rm _local__remote_ | 删除正向端口转发任务：取消指定的“主机端口”转发。 | 407| rport _remote local_ | 设置反向端口转发任务：监听“设备端口”，接收请求并进行转发，转发到“主机端口”。 | 408| rport rm _remote local_ | 删除反向端口转发任务：取消指定的“设备端口”转发。 | 409| tmode usb | 已连接设备切换为USB连接方式：设备端daemon进程重启，并首先选用USB连接方式。 | 410| tmode port [port-number] | 已连接设备切换为网络连接方式：设备端daemon进程重启，并优先使用网络方式连接设备，如果连接设备失败，再选择USB连接。 | 411| tconn_ host_[:port] [-remove] | 指定连接设备：通过“IP地址：端口号”来指定连接的设备，使用-remove参数断开连接。 | 412 4131. 列出全部转发端口转发任务，命令格式如下： 414 415 ```shell 416 hdc fport ls 417 ``` 418 419 **返回值：** 420 | 返回值 | 说明 | 421 | -------- | -------- | 422 | 'tcp:1234 tcp:1080' [Forward] | 正向端口转发任务。 | 423 | 'tcp:2080 tcp:2345' [Reverse] | 反向端口转发任务。 | 424 | [empty] | 无端口转发任务。 | 425 426 **使用方法：** 427 428 ```shell 429 hdc fport ls 430 ``` 431 4322. 设置正向端口转发任务，执行后将设置指定的“主机端口”转发数据到“设备端口”转发任务，命令格式如下： 433 434 ```shell 435 hdc fport local remote 436 ``` 437 438 **返回值：** 439 | 返回值 | 说明 | 440 | -------- | -------- | 441 | Forwardport result:OK | 端口转发任务设置正常。 | 442 | [Fail]Incorrect forward command | 端口转发任务设置失败，端口转发参数错误。 | 443 | [Fail]TCP Port listen failed at XXXX | 端口转发任务设置失败，本地转发端口被占用。 | 444 445 **使用方法：** 446 447 ```shell 448 hdc fport tcp:1234 tcp:1080 449 ``` 450 4513. 删除正向端口转发任务，执行后将指定的“主机端口”转发数据到“设备端口”转发任务删除，命令格式如下： 452 453 ```shell 454 hdc fport rm localremote 455 ``` 456 457 **返回值：** 458 | 返回值 | 说明 | 459 | -------- | -------- | 460 | Remove forward ruler success, ruler:tcp:XXXX tcp:XXXX | 端口转发任务删除正常。 | 461 | [Fail]Remove forward ruler failed, ruler is not exist tcp:XXXX tcp:XXXX | 端口转发任务删除失败，不存在指定的转发任务。 | 462 463 **使用方法：** 464 465 ```shell 466 hdc fport rm tcp:1234 tcp:1080 467 ``` 468 4694. 设置反向端口转发任务，执行后将设置指定的“设备端口”转发数据到“主机端口”转发任务，命令格式如下： 470 471 ```shell 472 hdc rport remote local 473 ``` 474 475 **返回值：** 476 | 返回值 | 说明 | 477 | -------- | -------- | 478 | Forwardport result:OK | 端口转发任务设置正常。 | 479 | [Fail]Incorrect forward command | 端口转发任务设置失败，端口转发参数错误。 | 480 | [Fail]TCP Port listen failed at XXXX | 端口转发任务设置失败，本地转发端口被占用。 | 481 482 **使用方法：** 483 484 ```shell 485 hdc rport tcp:1234 tcp:1080 486 ``` 487 4885. 删除反向端口转发任务，执行后将指定的“设备端口”转发数据到“主机端口”任务删除，命令格式如下： 489 490 ```shell 491 hdc rport rm remote local 492 ``` 493 494 **返回值：** 495 | 返回值 | 说明 | 496 | -------- | -------- | 497 | Remove forward ruler success, ruler:tcp:XXXX tcp:XXXX | 端口转发任务删除正常。 | 498 | [Fail]Remove forward ruler failed, ruler is not exist tcp:XXXX tcp:XXXX | 端口转发任务删除失败，不存在对应的转发任务。 | 499 500 **使用方法：** 501 502 ```shell 503 hdc rport rm tcp:1234 tcp:1080 504 ``` 505 5066. 已连接设备切换为USB连接方式，命令格式如下： 507 508 ```shell 509 hdc tmode usb 510 ``` 511 512 **返回值：** 513 | 返回值 | 说明 | 514 | -------- | -------- | 515 | 无 | 切换成功。 | 516 | [Fail]ExecuteCommand need connect-key | 设备列表无网络连接方式设备，无法指定设备切换连接方式。 | 517 518 **使用方法：** 519 520 ```shell 521 hdc tmode usb 522 ``` 523 5247. 已连接设备切换为网络连接方式，命令格式如下： 525 526 ```shell 527 hdc tmode port [port-number] 528 ``` 529 530 **参数：** 531 | 参数 | 参数说明 | 532 | -------- | -------- | 533 | port-number | 监听连接的网络端口号，范围:1~65536。 | 534 535 **返回值：** 536 | 返回值 | 说明 | 537 | -------- | -------- | 538 | 无 | 切换成功。 | 539 | [Fail]ExecuteCommand need connect-key | 切换失败，设备列表无设备，无法指定设备切换连接方式。 | 540 | [Fail]Incorrect port range | 端口号超出可设置范围（1~65536）。 | 541 542 **使用方法：** 543 544 ```shell 545 hdc tmode port 1234 546 ``` 547 548 > **注意：** 549 > 切换前，请确保条件满足：远端设备与近端执行机处于同一网络，且执行机可ping通远端设备IP。 550 > 551 > 如不满足以上条件请勿使用该命令进行切换。 552 553 > **说明：** 554 > 执行完毕后，远端daemon将会退出并重启，USB连接将会断开，默认启用TCP连接，且仅可通过TCP进行连接，如需恢复USB连接有以下两种方法： 555 > 556 > （1）执行hdc tconn [ip]:[port]命令进行TCP连接后，执行hdc tmode usb恢复。 557 > 558 > （2）通过恢复出厂设置恢复。 559 5608. 指定连接的设备，命令格式如下： 561 562 ```shell 563 hdc tconn host[:port] [-remove] 564 ``` 565 566 **参数：** 567 | 参数 | 参数说明 | 568 | -------- | -------- | 569 | host[:port] | 设备IP地址与端口号，格式按照“IP地址：端口号“。 | 570 | -remove | 【可选】断开指定设备的连接。 | 571 572 **返回值：** 573 | 返回值 | 说明 | 574 | -------- | -------- | 575 | Connect OK | 连接成功。 | 576 | [Info]Target is connected, repeat opration | 设备当前已连接。 | 577 | [Fail]Connect failed | 连接失败。 | 578 579 **使用方法：** 580 581 ```shell 582 hdc tconn 192.168.0.1:8888 583 hdc tconn 192.168.0.1:8888 -remove // 断开指定网络设备连接 584 ``` 585 586### 文件相关命令 587 588| 命令 | 说明 | 589| -------- | -------- | 590| file send _local remote_ | 从本地发送文件至远端设备。 | 591| file recv _remote local_ | 从远端设备发送文件至本地。 | 592 5931. 从本地发送文件至远端设备，命令格式如下： 594 595 ```shell 596 hdc file send local remote 597 ``` 598 599 **参数：** 600 | 参数名 | 说明 | 601 | -------- | -------- | 602 | local | 本地待发送的文件路径。 | 603 | remote | 远程待接收的文件路径。 | 604 605 **返回值：** 606 607 文件发送成功，返回传输成功的结果信息。文件发送失败，返回传输失败的具体信息。 608 609 **使用方法：** 610 611 ```shell 612 hdc file send E:\example.txt /data/local/tmp/example.txt 613 ``` 614 6152. 从远端设备发送文件至本地，命令格式如下： 616 617 ```shell 618 hdc file recv remote local 619 ``` 620 621 **参数：** 622 | 参数名 | 说明 | 623 | -------- | -------- | 624 | local | 本地待接收的文件路径。 | 625 | remote | 远程待发送的文件路径。 | 626 627 **返回值：** 628 629 文件接收成功，返回传输成功的结果信息。文件接收失败，返回传输失败的具体信息。 630 631 **使用方法：** 632 633 ```shell 634 hdc file recv /data/local/tmp/a.txt ./a.txt 635 ``` 636 637### 应用相关命令 638 639| 命令 | 说明 | 640| -------- | -------- | 641| install [-r/-d/-g] _packageFile_ | 安装指定的应用package文件。 | 642| uninstall_ packageName_ | 卸载指定的应用包package包名。 | 643 6441. 安装APP package，命令格式如下： 645 646 ```shell 647 hdc install [-r/-d/-g] packageFile 648 ``` 649 650 **参数：** 651 | 参数名 | 说明 | 652 | -------- | -------- | 653 | packageFile | 应用安装包文件名。 | 654 | -r | 替换已存在应用。 | 655 | -d | 允许降级安装。 | 656 | -g | 应用动态授权。 | 657 658 **返回值：** 659 | 返回值 | 说明 | 660 | -------- | -------- | 661 | 无 | 成功情况下无返回值。 | 662 | 具体安装失败原因 | 失败情况下返回具体安装失败信息。 | 663 664 **使用方法：** 665 666 以安装com.example.hello包为例： 667 668 ```shell 669 hdc install E:\com.example.hello.hap 670 ``` 671 6722. 卸载应用，命令格式如下： 673 674 ```shell 675 hdc uninstall [-k] packageName 676 ``` 677 678 **参数：** 679 | 参数名 | 说明 | 680 | -------- | -------- | 681 | packageName | 应用安装包。 | 682 | -k | 保留/data/cache。 | 683 684 **返回值：** 685 | 返回值 | 说明 | 686 | -------- | -------- | 687 | 无 | 成功情况下无返回值。 | 688 | 具体卸载失败原因 | 失败情况下返回具体卸载失败信息。 | 689 690 **使用方法：** 691 692 以卸载com.example.hello包为例： 693 694 ```shell 695 hdc uninstall com.example.hello 696 ``` 697 698### 调试相关命令 699 700| 命令 | 说明 | 701| -------- | -------- | 702| jpid | 显示可调试应用列表。 | 703| hilog [options] | 打印设备端的日志信息，options表示hilog支持的参数，可通过hdc hilog -h查阅支持的参数列表 。 | 704| shell [COMMAND] | 交互命令，COMMAND表示需要执行的单次命令。不同类型或版本的系统支持的COMMAND命令有所差异，可以通过hdc shell ls /system/bin查阅支持的命令列表。 | 705 7061. 抓取log信息，命令格式如下： 707 708 ```shell 709 hdc hilog[options] 710 ``` 711 712 **参数：** 713 | 参数 | 说明 | 714 | -------- | -------- | 715 | [options] | hilog支持的参数，可通过hdc hilog -h查阅支持的参数列表。 | 716 717 **返回值：** 718 | 返回值 | 说明 | 719 | -------- | -------- | 720 | 返回具体信息 | 抓取的日志信息。 | 721 722 **使用方法：** 723 724 ```shell 725 hdc hilog 726 hdc shell "hilog -r" // 清理hilog缓存日志 727 ``` 728 7292. 显示可调试应用列表，命令格式如下： 730 731 ```shell 732 hdc jpid 733 ``` 734 735 **返回值：** 736 | 返回值 | 说明 | 737 | -------- | -------- | 738 | 应用名列表 | 可调试应用名列表。 | 739 | [empty] | 无可调式应用。 | 740 741 **使用方法：** 742 743 ```shell 744 hdc jpid 745 ``` 746 7473. 交互命令，命令格式如下： 748 749 ```shell 750 hdc shell [COMMAND] 751 ``` 752 753 **参数：** 754 | 参数 | 说明 | 755 | -------- | -------- | 756 | [COMMAND] | 调试命令行可用命令，详细可用命令help来获取全部命令提示。 | 757 758 **返回值：** 759 | 返回值 | 说明 | 760 | -------- | -------- | 761 | 交互命令返回内容 | 返回内容详情请参见其他交互命令返回内容。 | 762 | /bin/sh: XXX : inaccessible or not found | 不支持的交互命令。 | 763 764 **使用方法：** 765 766 ```shell 767 hdc shell ps -ef 768 hdc shell help -a // 查询全部可用命令 769 ``` 770 771## 常见场景 772 773### USB连接场景 774 775**环境确认** 776| 确认项 | 正常 | 异常处理 | 777| -------- | -------- | -------- | 778| USB调试选项 | 开启 | 设备的USB调试模式如无法自动开启，请尝试重启设备。 | 779| USB数据连接线 | 使用USB数据连接线连接到调试PC的USB接口。 | 如使用低带宽、无数据通信功能的USB连接线可能导致无法识别HDC设备，建议更换官方USB数据连接线。 | 780| USB接口 | 主板直出USB接口（台式机为后面板的USB接口，笔记本为机身的USB接口） | 如使用转接头/拓展坞/台式机前面板USB接口，存在带宽低和USB同步异常等问题，会导致频繁断连，推荐使用直连方式连接PC和设备。 | 781| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容。 | 参见环境准备章节。 | 782| 驱动 | 连接HDC设备后，设备管理器通用串行总线设备存在设备"HDC Device"或"HDC Interface" | 请安装驱动。 | 783 784**连接步骤** 785 786```shell 787hdc shell //USB直连需要确认设备非处在tcp连接模式，直接连接即可。 788``` 789 790### TCP连接场景 791 792**环境确认** 793| 确认项 | 正常 | 异常处理 | 794| -------- | -------- | -------- | 795| 网络连接 | PC、手机设备处于同一网络。 | 连接同一WiFi或手机开启热点。 | 796| 网络状态 | telnet ip:port正常，网速稳定。 | 请选择稳定的网络连接方式。 | 797| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容。 | 参见环境准备章节。 | 798 799**连接步骤** 800 8011. PC通过USB连接设备。 802 8032. 设置亮屏幕，执行以下命令： 804 805 ```shell 806 hdc shell “power-shell setmode 602” 807 ``` 808 809 保持亮屏状态，避免熄屏导致 wifi断掉；如果此时设备断连，需要重新较快输入tconn连接指令 810 8113. 将设备通过USB模式切换至tcp模式，执行以下命令： 812 813 ```shell 814 hdc tmode port 8710//port 后加指定端口号（可自行设置） 815 ``` 816 8174. 通过tcp连接设备（需要事先知道设备IP），执行以下命令： 818 819 ```shell 820 hdc tconn ip:8710 821 ``` 822 823 ip可在手机查看设备侧的ip地址，端口号为上一步指定的，默认值为8710。 824 8255. 查看已连接设备，执行以下命令： 826 827 ```shell 828 hdc list targets 829 ``` 830 831 返回值为ip:port形式即为连接成功，单台设备可以正常使用hdc命令，多台设备需要-t指定设备使用hdc命令。 832 8336. （可选）TCP模式切换回USB模式,在已连接TCP模式状态下，执行以下命令： 834 835 ```shell 836 hdc tmode usb 837 ``` 838 839 切换后将恢复USB模式。 840 841### 远程连接场景 842 843远程连接结构如图所示。 844 845 846 847**服务端配置** 848 849服务端通过USB连接到对应的HDC设备后执行以下命令： 850 851```shell 852hdc kill // 关闭本地hdc服务 853hdc -s ip:8710 -m // 启动网络转发的hdc服务 854 // 其中ip为服务端自身的IP，windows可通过ipconfig查询，unix系统可通过ifconfig查询 855 // 8710为默认端口号，也可设置为其他端口号如：18710 856 // 启动后服务端将打印日志 857``` 858 859**客户端连接** 860 861客户端连接需要确保可以连通服务端IP地址，满足前述条件后执行以下命令： 862```shell 863hdc -s ip:8710 [command] // 其中ip为服务端IP， 864 // command可以为任意hdc可用命令，例如list targets 865``` 866 867### 日志获取场景 868 869**server端日志** 870 871执行以下命令开启日志获取： 872 873```shell 874hdc kill 875hdc -l5 start 876``` 877 878收集到的完整日志存放路径： 879 880| 平台 | 路径 | 备注 | 881| -------- | -------- | -------- | 882| Windows | %temp%\hdc.log | 实际路径参考，实际使用请替换用户名变量<br/>C:\Users\用户名\AppData\Local\Temp\hdc.log<br/>**说明：**<br/>Windows的文件路径使用反斜线“\”。 | 883| Linux | /tmp/hdc.log | - | 884| MacOS | $TMPDIR/hdc.log | - | 885 886**设备端日志** 887 888开启hilog日志工具，获取对应日志，命令如下： 889 890```shell 891hdc shell hilog -w start // 开启hilog日志落盘 892hdc shell ls /data/log/hilog // 查看已落盘hilog日志 893hdc file recv /data/log/hilog // 获取hilog已落盘日志（包含内核日志） 894``` 895 896## 常见问题 897 898### 设备无法识别 899 900**现象描述** 901 902命令行执行`hdc list targets`命令后，返回结果为`[empty]`。 903 904可通过以下方式排查。 905 906- 情况一：查看设备管理是否显示HDC设备。 907 908 Windows环境： 909 910 在`设备管理器`>`通用串行总线设备`中是否显示`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 911 912 Linux环境： 913 914 在命令行执行`lsusb`,在返回的内容中查看是否有`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 915 916 MacOS环境： 917 918 使用`系统信息`或`系统概述`来查看USB设备，步骤如下： 919 920 1. 按住键盘上的Option键，点按菜单。 921 922 2. 选取`系统信息`或`系统概述`。 923 924 3. 在随后出现的窗口中，选择左边的`USB`。 925 926 4. 在随后显示的设备树查看是否有`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 927 928 **可采取的解决方法** 929 930 以上环境如没有显示HDC设备，则说明无法识别设备，可以根据实际场景尝试以下方法： 931 932 - 使用其他USB物理接口。 933 - 更换USB数据连接线。 934 - 使用其他计算机调试。 935 - 设备开启USB调试模式。 936 - 设备出现弹窗点击允许调试。 937 - 如可通过TCP模式连接，可执行`hdc tmode usb`命令恢复USB连接。 938 - 设备恢复出厂设备。 939 940- 情况二：存在USB设备，但是驱动损坏，显示"HDC Device"⚠警告图标。 941 942 现象描述：该问题常见于Windows环境，现象为`设备管理器`>`通用串行总线设备`中，`HDC Device`显示为黄标警告，且描述信息为该设备无法正常工作。可尝试重新安装驱动解决，如重新安装驱动无法解决，可以尝试更换USB连接数据线/拓展坞/USB接口。 943 944 **重新安装驱动的方法** 945 946 1. 打开`设备管理器`，右键点击存在警告图标的`HDC Device`； 947 948 2. 出现的菜单中点击`更新驱动程序`； 949 950 3. 出现的提示窗口（第1/3个）中，选取`浏览我的电脑以查找驱动程序`； 951 952 4. 出现的提示窗口（第2/3个）中，选取`让我从计算机上的可用驱动程序列表中选取`； 953 954 5. 出现的提示窗口（第3/3个）中，取消勾选`显示兼容硬件`，选择厂商：`WinUSB设备`，选择型号：`WinUSB设备`，选择完成后点击`下一步`按钮。 955 956- 情况三：连接设备时出现`[Fail]Failed to communicate with daemon`。 957 958 现象描述：命令行执行hdc相关命令，执行失败返回`[Fail]Failed to communicate with daemon`。 959 960 可能存在以下原因，可参考排查： 961 962 - hdc SDK与设备不匹配: 如果设备更新到最新版本，可更新hdc（SDK）工具至最新版本。 963 - 端口被占用： 964 965 常见于hdc和hdc_std使用同一端口，同时运行时HDC_SERVER_PORT设置的端口互相冲突（未设置则使用默认端口8710，仍然会冲突），注意只运行其中一个。其他软件占用hdc默认端口也会导致该问题发生。 966 967- 情况四：连接设备时出现`Connect server failed`。 968 969 出现该现象，可能有如下原因： 970 971 - **端口抢占** 972 973 解决方法如下： 974 1. 排查自带hdc的软件进程。 975 976 包括自带hdc的软件（DevEco Studio、DevEco Testing），如存在请关闭这些软件后再执行hdc相关命令。 977 978 2. 查询HDC端口情况。 979 980 以设置的HDC_SERVER_PORT为8710端口为例，在不同平台查询命令如下： 981 982 Unix： 983 984 ```shell 985 netstat -an |grep 8710 986 ``` 987 988 Windows: 989 990 ```shell 991 netstat -an |findstr 8710 992 ``` 993 994 如存在抢占的软件，可以关闭该软件进程或者更换HDC_SERVER_PORT环境变量为其他端口号。 995 996 3. 排查未关闭的其他版本hdc server 997 998 Windows： 999 1000 使用`任务管理器`>`详细信息`查询hdc.exe进程,右键打开文件所在位置，核对位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc.exe进程(hdc kill或者任务管理器直接结束进程)并重新执行hdc命令。（关闭hdc server后执行hdc命令会重新启动hdc server） 1001 1002 Unix： 1003 1004 使用`ps -ef |grep hdc`查询hdc后台server进程，核对进程启动位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc进程(hdc kill或者kill -9 hdc进程的PID)并重新执行hdc命令。（关闭hdc server后执行hdc命令会重新启动hdc server） 1005 1006 - **注册表异常** 1007 1008 解决方法：清理注册表，步骤如下： 1009 1010 1. 同时按下`Win`+`R`键，启动运行工具，输入栏输入`regedit`打开注册表。 1011 2. 注册表地址栏输入以下内容并按下`回车`，即可进入USB类设备驱动程序的注册表。 1012 1013 ```shell 1014 计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{88bae032-5a81-49f0-bc3d-a4ff138216d6} 1015 ``` 1016 1017 3. 找到`UpperFilters`键，右键`修改`编辑，**备份**并清空其中数值数据内容（如清空后无法解决问题可依照备份恢复）。 1018 4. 刷新设备管理器/插拔USB接口/重启计算机。 1019 1020### hdc无法运行 1021 1022**现象描述** 1023 1024使用命令行执行hdc.exe/hdc 二进制文件无法运行。 1025 1026**可能原因&解决方法** 1027 1028- 运行环境异常 1029 1030 Linux运行环境：建议使用Ubuntu18.04及以上64版本，如发送libc++.so引用错误请使用ldd/readelf等命令检查库引用。 1031 1032 MacOS运行环境：建议使用MacOS 11及以上版本。 1033 1034 Windows运行环境：建议使用Windows10/Windows11 64位版本，如低版本缺失WinUSB库/驱动，请使用Zadig工具更新。对于符合设备，需要使用Zadig工具安装libusb-win32驱动。[Zadig链接](https://github.com/pbatard/libwdi/releases) 1035 1036- 运行方式不当：请使用命令行依照正确命令运行hdc工具，而非鼠标双击文件。 1037 1038### 其他问题排查常用步骤 1039 10401. 命令行执行`hdc list targets`查看返回值。 10412. 查看`设备管理`是否有`HDC Device`。 10423. 执行`hdc kill`关闭server后，执行`hdc -l5 start`收集日志（hdc.log位于执行端TEMP目录，不同平台目录位置存在差异，可参考[日志获取场景](#日志获取场景)）。 10434. 通过hdc.log日志定位相关问题。 1044
