• 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| usbSubmitTransfer(transfer: UsbDataTransferParams): void                                                         | 异步传输接口（支持实时、批量、中断传输）。                                   |
39| usbCancelTransfer(transfer: UsbDataTransferParams): void                                                         | 取消已提交的异步传输。                                             |
40
41更多关于设备管理和传输模式的详细接口介绍，请查阅[API参考文档](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md)。
42
43### 开发步骤
44
45主机（Host）连接设备（Device），通过`usbSubmitTransfer`接口进行数据传输。以下步骤描述了如何使用中断传输方式来传输数据：
46
471. 导入模块。
48
49    ```ts
50    // 导入usbManager模块。
51    import { usbManager } from '@kit.BasicServicesKit';
52    ```
53
542. 获取设备列表。
55
56    ```ts
57    // 获取连接主设备的USB设备列表
58    let usbDevices: Array<usbManager.USBDevice> = usbManager.getDevices();
59    console.info('usbDevices: ', JSON.stringify(usbDevices));
60    if(usbDevices.length === 0) {
61      console.info('usbDevices is empty');
62      return;
63    }
64    ```
65
663. 获取设备操作权限。
67
68    ```ts
69    // 此处对列表中的第一台USB设备判断是否拥有访问权限
70    let usbDevice: usbManager.USBDevice = usbDevices[0];
71    if(!usbManager.hasRight(usbDevice.name)) {
72      await usbManager.requestRight(usbDevice.name).then(result => {
73        if(!result) {
74          // 没有访问设备的权限且用户不授权则退出
75          console.info('user is not granted the operation permission');
76          return;
77        }
78      });
79    }
80    ```
81
824. 获取通过中断传输读取数据的端点。
83
84   ```ts
85   let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(usbDevice);
86   let usbConfigs: usbManager.USBConfiguration[] = usbDevice.configs;
87   let usbInterfaces: usbManager.USBInterface[] = [];
88   let usbInterface: usbManager.USBInterface | undefined = undefined
89   let usbEndpoints: usbManager.USBEndpoint[] = [];
90   let usbEndprint: usbManager.USBEndpoint | undefined = undefined
91   for (let i = 0; i < usbConfigs.length; i++) {
92     usbInterfaces = usbConfigs[i].interfaces;
93     for (let i = 0; i < usbInterfaces.length; i++) {
94       usbEndpoints = usbInterfaces[i].endpoints;
95       usbEndprint = usbEndpoints.find((value) => {
96         return value.direction === 128 && value.type === usbManager.UsbEndpointTransferType.TRANSFER_TYPE_INTERRUPT;
97       })
98       if (usbEndprint !== undefined) {
99         usbInterface = usbInterfaces[i];
100         break;
101       }
102     }
103   }
104   if (usbEndprint === undefined) {
105     console.error(`get usbEndprint error`)
106     return;
107   }
108   ```
109
1105. 连接设备，注册通信接口。
111
112    ```ts
113    // 注册通信接口，注册成功返回0，注册失败返回其他错误码。
114    let claimInterfaceResult: number = usbManager.claimInterface(devicePipe, usbInterface, true);
115    if (claimInterfaceResult !== 0) {
116      console.error(`claimInterface error = ${claimInterfaceResult}`)
117      return;
118    }
119    ```
120
1216. 传输数据。
122
123   ```ts
124   try {
125     // 通信接口注册成功，传输数据
126     let transferParams: usbManager.UsbDataTransferParams = {
127       devPipe: devicePipe,
128       flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK,
129       endpoint: usbEndprint.address,
130       type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_INTERRUPT,
131       timeout: 2000,
132       length: 10,
133       callback: () => {},
134       userData: new Uint8Array(10),
135       buffer: new Uint8Array(10),
136       isoPacketCount: 2,
137     };
138
139     transferParams.callback = (err: Error, callBackData: usbManager.SubmitTransferCallback) => {
140       console.info('callBackData = ' + JSON.stringify(callBackData));
141       console.info('transfer success，result = ' + transferParams.buffer.toString());
142     }
143     usbManager.usbSubmitTransfer(transferParams);
144     console.info('USB transfer request submitted.');
145   } catch (error) {
146     console.error('USB transfer failed:', error);
147   }
148   ```
149
1507. 取消传输，释放接口，关闭设备消息控制通道。
151
152    ```ts
153    usbManager.usbCancelTransfer(transferParams);
154    usbManager.releaseInterface(devicePipe, usbInterface);
155    usbManager.closePipe(devicePipe);
156    ```
157
158### 调测验证
159
1601. 主机端通过USB接口连接支持中断传输的终端设备（鼠标、键盘等）。
1612. 执行上述代码。
1623. log中搜索关键字`transfer success`，表示中断传输接口调用成功。
163