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实时传输是通过USB协议在固定时间窗口内完成数据传输，确保数据流的时序稳定性和低延迟，但允许少量数据丢失（如视频丢帧、音频杂音）的传输模式。这种传输方式适用于USB耳机、USB音响、视频会议设备等对连续性要求高、容错性强的场景。 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://gitcode.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| usbSubmitTransfer(transfer: UsbDataTransferParams): void | 异步传输接口（支持实时、批量、中断传输）。 | 46| usbCancelTransfer(transfer: UsbDataTransferParams): void | 取消已提交的异步传输。 | 47 48更多关于设备管理和传输模式的详细接口介绍，请查阅[API参考文档](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md)。 49 50### 开发步骤 51 52主机（Host）连接设备（Device），通过`usbSubmitTransfer`接口进行数据传输。以下步骤描述了如何使用实时传输方式来传输数据： 53 54> **说明：** 55> 56> 以下示例代码只是使用实时传输方式来传输数据的必要流程，需要放入具体的方法中执行。在实际调用时，设备开发者需要遵循设备相关协议进行调用，确保数据的正确传输和设备的兼容性。 57 581. 导入模块。 59 60 ```ts 61 // 导入usbManager模块。 62 import { usbManager } from '@kit.BasicServicesKit'; 63 ``` 64 652. 获取设备列表。 66 67 ```ts 68 // 获取连接主设备的USB设备列表 69 let usbDevices: Array<usbManager.USBDevice> = usbManager.getDevices(); 70 console.info(`usbDevices: ${usbDevices}`); 71 if(usbDevices.length === 0) { 72 console.error('usbDevices is empty'); 73 return; 74 } 75 ``` 76 773. 获取设备操作权限。 78 79 ```ts 80 // 此处对列表中的第一台USB设备判断是否拥有访问权限 81 // 函数名仅作为示例，实际需要与业务结合命名 82 async function transferDefault() { 83 let usbDevice: usbManager.USBDevice = usbDevices[0]; 84 if(!usbManager.hasRight(usbDevice.name)) { 85 await usbManager.requestRight(usbDevice.name).then(result => { 86 if(!result) { 87 // 没有访问设备的权限且用户不授权则退出 88 console.error('The user does not have permission to perform this operation'); 89 return; 90 } 91 }); 92 } 93 } 94 ``` 95 964. 获取通过实时传输读取数据的端点。 97 98 ```ts 99 let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(usbDevice); 100 let usbConfigs: usbManager.USBConfiguration[] = usbDevice.configs; 101 let usbInterfaces: usbManager.USBInterface[] = []; 102 let usbInterface: usbManager.USBInterface | undefined = undefined 103 let usbEndpoints: usbManager.USBEndpoint[] = []; 104 let usbEndpoint: usbManager.USBEndpoint | undefined = undefined 105 for (let i = 0; i < usbConfigs.length; i++) { 106 usbInterfaces = usbConfigs[i].interfaces; 107 for (let j = 0; j < usbInterfaces.length; j++) { 108 usbEndpoints = usbInterfaces[j].endpoints; 109 usbEndpoint = usbEndpoints.find((value) => { 110 // direction为请求方向，0表示写入数据，128表示读取数据 111 return value.direction === 128 && value.type === usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS; 112 }) 113 if (usbEndpoint !== undefined) { 114 usbInterface = usbInterfaces[j]; 115 break; 116 } 117 } 118 } 119 if (usbEndpoint === undefined) { 120 console.error(`get usbEndpoint error`) 121 return; 122 } 123 ``` 124 1255. 连接设备，注册通信接口。 126 127 ```ts 128 // 注册通信接口，注册成功返回0，注册失败返回其他错误码。 129 let claimInterfaceResult: number = usbManager.claimInterface(devicePipe, usbInterface, true); 130 if (claimInterfaceResult !== 0) { 131 console.error(`claimInterface error = ${claimInterfaceResult}`) 132 return; 133 } 134 135 // 传输类型类型为“实时传输”时，需设置设备接口。设置成功返回0，注册失败返回其他错误码。 136 if (usbEndpoint.type === usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS) { 137 let setInterfaceResult = usbManager.setInterface(devicePipe, usbInterface); 138 if (setInterfaceResult !== 0) { 139 console.error(`setInterfaceResult error = ${setInterfaceResult}`) 140 return; 141 } 142 } 143 ``` 144 1456. 传输数据。 146 147 ```ts 148 try { 149 // 通信接口注册成功，传输数据 150 let transferParams: usbManager.UsbDataTransferParams = { 151 devPipe: devicePipe, 152 flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK, 153 endpoint: usbEndpoint.address, 154 type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS, 155 timeout: 2000, 156 length: 10, 157 callback: () => {}, 158 userData: new Uint8Array(10), 159 buffer: new Uint8Array(10), 160 isoPacketCount: 2, 161 }; 162 163 transferParams.callback = (err: Error, callBackData: usbManager.SubmitTransferCallback) => { 164 console.info(`callBackData = ${callBackData}`); 165 console.info('transfer success，result = ' + transferParams.buffer.toString()); 166 } 167 usbManager.usbSubmitTransfer(transferParams); 168 console.info('USB transfer request submitted.'); 169 } catch (error) { 170 console.error(`USB transfer failed: ${error}`); 171 } 172 ``` 173 1747. 取消传输，释放接口，关闭设备消息控制通道。 175 176 ```ts 177 usbManager.usbCancelTransfer(transferParams); 178 usbManager.releaseInterface(devicePipe, usbInterface); 179 usbManager.closePipe(devicePipe); 180 ``` 181 182### 调测验证 183 1841. 主机端通过USB接口连接支持实时传输的设备（USB耳机等）。 1852. 执行上述代码。 1863. log中搜索关键字`transfer success`，表示实时传输接口调用成功。