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设备插入时，可以通过`usbManager`获取一些USB设备的基本信息，如设备类型、支持的功能等。 Host侧主要通过封装的pipe来完成和USB设备的通信。在OpenHarmony系统中，USB管理服务是核心组件，负责管理与USB设备的连接和通信。通过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 43USB设备管理主要提供的功能有：查询USB设备列表、USB设备权限控制、设置USB设备配置等。 44 45USB类开放能力如下，具体请查阅[API参考文档](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md)。 46 47**表1** USB类的开放能力接口 48 49| 接口名 | 描述 | 50| ------------------------------------------------------------ | ------------------------------------------------------------ | 51| hasRight(deviceName: string): boolean | 判断是否有权访问该设备。 | 52| requestRight(deviceName: string): Promise<boolean> | 请求软件包的临时权限以访问设备。使用Promise异步回调。 | 53| removeRight(deviceName: string): boolean | 移除软件包对设备的访问权限。| 54| connectDevice(device: USBDevice): Readonly<USBDevicePipe> | 根据`getDevices()`返回的设备信息打开USB设备。 | 55| getDevices(): Array<Readonly<USBDevice>> | 获取接入主设备的USB设备列表。如果没有设备接入，那么将会返回一个空的列表。 | 56| setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number | 设置设备的配置。 | 57| setInterface(pipe: USBDevicePipe, iface: USBInterface): number | 设置设备的接口。 | 58| claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number | 注册通信接口。 | 59| closePipe(pipe: USBDevicePipe): number | 关闭设备消息控制通道。 | 60| releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number | 释放注册过的通信接口。 | 61| getFileDescriptor(pipe: USBDevicePipe): number | 获取文件描述符。 | 62| getRawDescriptor(pipe: USBDevicePipe): Uint8Array | 获取原始的USB描述符。 | 63 64### 开发步骤 65 66USB设备可作为Host连接Device进行设备管理，开发示例如下： 67 68 691. 导入模块。 70 71 ```ts 72 // 导入usbManager模块。 73 import { usbManager } from '@kit.BasicServicesKit'; 74 import { BusinessError } from '@kit.BasicServicesKit'; 75 ``` 76 772. 获取设备列表。 78 79 ```ts 80 // 获取设备列表。 81 let deviceList : Array<usbManager.USBDevice> = usbManager.getDevices(); 82 console.info(`deviceList: ${deviceList}`); 83 if(deviceList.length === 0) { 84 console.error('deviceList is empty'); 85 return; 86 } 87 /* 88 deviceList结构示例 89 [ 90 { 91 name: "1-1", 92 serial: "", 93 manufacturerName: "", 94 productName: "", 95 version: "", 96 vendorId: 7531, 97 productId: 2, 98 clazz: 9, 99 subClass: 0, 100 protocol: 1, 101 devAddress: 1, 102 busNum: 1, 103 configs: [ 104 { 105 id: 1, 106 attributes: 224, 107 isRemoteWakeup: true, 108 isSelfPowered: true, 109 maxPower: 0, 110 name: "1-1", 111 interfaces: [ 112 { 113 id: 0, 114 protocol: 0, 115 clazz: 9, 116 subClass: 0, 117 alternateSetting: 0, 118 name: "1-1", 119 endpoints: [ 120 { 121 address: 129, 122 attributes: 3, 123 interval: 12, 124 maxPacketSize: 4, 125 direction: 128, 126 number: 1, 127 type: 3, 128 interfaceId: 0, 129 } 130 ] 131 } 132 ] 133 } 134 ] 135 } 136 ] 137 */ 138 ``` 139 1403. 获取设备操作权限。 141 142 ```ts 143 let deviceName : string = deviceList[0].name; 144 // 申请操作指定的device的操作权限。 145 usbManager.requestRight(deviceName).then((hasRight : boolean) => { 146 console.info("usb device request right result: " + hasRight); 147 }).catch((error : BusinessError)=> { 148 console.error(`usb device request right failed : ${error}`); 149 }); 150 ``` 151 1524. 打开Device设备。 153 154 ```ts 155 // 打开设备，获取数据传输通道。 156 let pipe : usbManager.USBDevicePipe = usbManager.connectDevice(deviceList[0]); 157 let interface1 : usbManager.USBInterface = deviceList[0].configs[0].interfaces[0]; 158 /* 159 打开对应接口，在设备信息（deviceList）中选取对应的interface。 160 interface1为设备配置中的一个接口。 161 */ 162 usbManager.claimInterface(pipe, interface1, true); 163 ``` 164 1655. 释放接口，关闭设备。 166 167 ```ts 168 usbManager.releaseInterface(pipe, interface1); 169 usbManager.closePipe(pipe); 170 ``` 171 172### 相关实例 173 174针对USB管理开发，有以下相关实例可供参考： 175 176- [`DeviceManagementCollection`：设备管理合集（ArkTS）（API9）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DeviceManagement/DeviceManagementCollection)