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