1# USB实时传输 2 3## 场景介绍 4 5实时传输是通过USB协议在固定时间窗口内完成数据传输，确保数据流的时序稳定性和低延迟，但允许少量数据丢失（如视频丢帧、音频杂音）的传输模式。这种传输方式适用于USB耳机、USB音响、视频会议设备等对连续性要求高、容错性强的场景。 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 // direction为请求方向，0表示写入数据，128表示读取数据 97 return value.direction === 128 && value.type === usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS; 98 }) 99 if (usbEndprint !== undefined) { 100 usbInterface = usbInterfaces[i]; 101 break; 102 } 103 } 104 } 105 if (usbEndprint === undefined) { 106 console.error(`get usbEndprint error`) 107 return; 108 } 109 ``` 110 1115. 连接设备，注册通信接口。 112 113 ```ts 114 // 注册通信接口，注册成功返回0，注册失败返回其他错误码。 115 let claimInterfaceResult: number = usbManager.claimInterface(devicePipe, usbInterface, true); 116 if (claimInterfaceResult !== 0) { 117 console.error(`claimInterface error = ${claimInterfaceResult}`) 118 return; 119 } 120 121 // 传输类型类型为“实时传输”时，需设置设备接口。设置成功返回0，注册失败返回其他错误码。 122 if (this.type === usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS) { 123 let setInterfaceResult = usbManager.setInterface(devicePipe, usbInterface); 124 if (setInterfaceResult !== 0) { 125 console.info(`setInterfaceResult error = ${setInterfaceResult}`) 126 return; 127 } 128 } 129 ``` 130 1316. 传输数据。 132 133 ```ts 134 try { 135 // 通信接口注册成功，传输数据 136 let transferParams: usbManager.UsbDataTransferParams = { 137 devPipe: devicePipe, 138 flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK, 139 endpoint: usbEndprint.address, 140 type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS, 141 timeout: 2000, 142 length: 10, 143 callback: () => {}, 144 userData: new Uint8Array(10), 145 buffer: new Uint8Array(10), 146 isoPacketCount: 2, 147 }; 148 149 transferParams.callback = (err: Error, callBackData: usbManager.SubmitTransferCallback) => { 150 console.info('callBackData = ' + JSON.stringify(callBackData)); 151 console.info('transfer success，result = ' + transferParams.buffer.toString()); 152 } 153 usbManager.usbSubmitTransfer(transferParams); 154 console.info('USB transfer request submitted.'); 155 } catch (error) { 156 console.error('USB transfer failed:', error); 157 } 158 ``` 159 1607. 取消传输，释放接口，关闭设备消息控制通道。 161 162 ```ts 163 usbManager.usbCancelTransfer(transferParams); 164 usbManager.releaseInterface(devicePipe, usbInterface); 165 usbManager.closePipe(devicePipe); 166 ``` 167 168### 调测验证 169 1701. 主机端通过USB接口连接支持实时传输的设备（USB耳机等）。 1712. 执行上述代码。 1723. log中搜索关键字`transfer success`，表示实时传输接口调用成功。