• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# USB控制传输
2
3## 场景介绍
4
5控制传输主要用于主机（Host）和设备（Device）进行设备状态的获取和设置，进行设备属性状态的的控制。根据设备支持的端点类型支持控制传输读和写。
6
7## 环境准备
8
9### 环境要求
10
11- 开发工具及配置：
12
13  DevEco Studio作为驱动开发工具，是进行驱动开发必备条件之一，开发者可以使用该工具进行开发、调试、打包等操作。请[下载安装](https://developer.huawei.com/consumer/cn/download/)该工具，并参考[DevEco Studio使用指南](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V14/ide-tools-overview-V14)中的[创建工程及运行](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V14/ide-create-new-project-V14)进行基本的操作验证，保证DevEco Studio可正常运行。
14
15
16- SDK版本配置：
17
18  扩展外设管理提供的ArkTs接口，所需SDK版本为API16及以上才可使用。
19
20
21- HDC配置：
22
23  HDC（HarmonyOS Device Connector）是为开发人员提供的用于调试的命令行工具，通过该工具可以在Windows/Linux/Mac系统上与真实设备或者模拟器进行交互，详细参考[HDC配置](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/hdc-V5)。
24
25### 搭建环境
26
27- 在PC上安装[DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio)，要求版本在4.1及以上。
28- 将public-SDK更新到API 16或以上，更新SDK的具体操作可参见[更新指南](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/faqs/full-sdk-switch-guide.md)。
29- PC安装HDC工具（HarmonyOS Device Connector），通过该工具可以在Windows/Linux/Mac系统上与真实设备或者模拟器进行交互，详细参考[HDC配置](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/hdc-V5)。
30- 用USB线缆将搭载OpenHarmony的设备连接到PC。
31
32## 开发指导
33
34### 接口说明
35
36| 接口名                                                       | 描述     |
37| ------------------------------------------------------------ |--------|
38| usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout?: number): Promise<number> | 控制传输。  |
39
40更多关于设备管理和传输模式的详细接口介绍，请查阅[API参考文档](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md)。
41
42### 开发步骤
43
44主机（Host）连接设备（Device），通过`usbControlTransfer`接口进行数据传输。以下步骤描述了如何使用控制传输方式来传输数据：
45
46
471. 导入模块。
48
49   ```ts
50   // 导入usbManager模块。
51   import { usbManager } from '@kit.BasicServicesKit';
52   import { BusinessError } from '@kit.BasicServicesKit';
53   ```
54
552. 获取设备列表。
56
57   ```ts
58   // 获取设备列表。
59   let deviceList : Array<usbManager.USBDevice> = usbManager.getDevices();
60   /*
61   deviceList结构示例
62   [
63     {
64       name: "1-1",
65       serial: "",
66       manufacturerName: "",
67       productName: "",
68       version: "",
69       vendorId: 7531,
70       productId: 2,
71       clazz: 9,
72       subClass: 0,
73       protocol: 1,
74       devAddress: 1,
75       busNum: 1,
76       configs: [
77         {
78           id: 1,
79           attributes: 224,
80           isRemoteWakeup: true,
81           isSelfPowered: true,
82           maxPower: 0,
83           name: "1-1",
84           interfaces: [
85             {
86               id: 0,
87               protocol: 0,
88               clazz: 9,
89               subClass: 0,
90               alternateSetting: 0,
91               name: "1-1",
92               endpoints: [
93                 {
94                   address: 129,
95                   attributes: 3,
96                   interval: 12,
97                   maxPacketSize: 4,
98                   direction: 128,
99                   number: 1,
100                   type: 3,
101                   interfaceId: 0,
102                 }
103               ]
104             }
105           ]
106         }
107       ]
108     }
109   ]
110   */
111   ```
112
1133. 获取设备操作权限。
114
115   ```ts
116   let deviceName : string = deviceList[0].name;
117   // 申请操作指定的device的操作权限。
118   usbManager.requestRight(deviceName).then((hasRight : boolean) => {
119     console.info("usb device request right result: " + hasRight);
120   }).catch((error : BusinessError)=> {
121     console.info("usb device request right failed : " + error);
122   });
123   ```
124
1254. 打开设备。
126
127   ```ts
128   // 打开设备，获取数据传输通道。
129   let pipe : usbManager.USBDevicePipe = usbManager.connectDevice(deviceList[0]);
130   let interface1 : usbManager.USBInterface = deviceList[0].configs[0].interfaces[0];
131
132   /*
133    打开对应接口，在设备信息（deviceList）中选取对应的interface。
134   interface1为设备配置中的一个接口。
135   */
136   usbManager.claimInterface(pipe, interface1, true);
137   ```
138
1395. 数据传输。
140
141    ```ts
142    /*
143      构造控制传输参数
144    */
145    let param: usbManager.USBDeviceRequestParams = {
146      bmRequestType: 0x80,    //0x80指一次由设备到主机的标准请求命令
147      bRequest: 0x06,    //0x06指获取描述符
148      wValue:0x01 << 8 | 0,    //该值为2个字节，高字节指描述符类型，此处0x01指设备描述符；低字节指描述符索引，设备描述符不涉及，填0
149      wIndex: 0,    //索引值，可填0
150      wLength: 18,    //描述符的长度，此处18表示设备描述符长度，最大支持1024
151      data: new Uint8Array(18)
152    };
153
154    usbManager.usbControlTransfer(pipe, param).then((ret: number) => {
155    console.info("usbControlTransfer = ${ret}");
156    })
157    ```
158
1596. 释放接口，关闭设备。
160
161   ```ts
162   usbManager.releaseInterface(pipe, interface1);
163   usbManager.closePipe(pipe);
164   ```