1# USB 2 3This module provides USB device management functions, including USB device list query, bulk data transfer, control transfer, and permission control. 4 5> **NOTE**<br> 6> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 7 8## Modules to Import 9 10```js 11import usb from "@ohos.usb"; 12``` 13 14## usb.getDevices 15 16getDevices(): Array<Readonly<USBDevice>> 17 18Obtains the USB device list. 19 20**System capability**: SystemCapability.USB.USBManager 21 22- **Return value** 23 | Type| Description| 24 | -------- | -------- | 25 | Array<Readonly<[USBDevice](#usbdevice)>> | Device information list. | 26 27- **Example** 28 ```js 29 let devicesList = usb.getDevices(); 30 console.log(`devicesList = ${JSON.stringify(devicesList)}`); 31 // devicesList is a list of USB devices. 32 // A simple example of devicesList is provided as follows: 33 [ 34 { 35 name: "1-1", 36 serial: "", 37 manufacturerName: "", 38 productName: "", 39 version: "", 40 vendorId: 7531, 41 productId: 2, 42 clazz: 9, 43 subclass: 0, 44 protocol: 1, 45 devAddress: 1, 46 busNum: 1, 47 configs: [ 48 { 49 id: 1, 50 attributes: 224, 51 isRemoteWakeup: true, 52 isSelfPowered: true, 53 maxPower: 0, 54 name: "1-1", 55 interfaces: [ 56 { 57 id: 0, 58 protocol: 0, 59 clazz: 9, 60 subclass: 0, 61 alternateSetting: 0, 62 name: "1-1", 63 endpoints: [ 64 { 65 address: 129, 66 attributes: 3, 67 interval: 12, 68 maxPacketSize: 4, 69 direction: 128, 70 number: 1, 71 type: 3, 72 interfaceId: 0, 73 }, 74 ], 75 }, 76 ], 77 }, 78 ], 79 }, 80 ] 81 ``` 82 83 84## usb.connectDevice 85 86connectDevice(device: USBDevice): Readonly<USBDevicePipe> 87 88Connects to a USB device. 89 90Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, and then call [usb.requestRight](#usbrequestright) to request the device access permission. 91 92**System capability**: SystemCapability.USB.USBManager 93 94- **Parameters** 95 | Name| Type| Mandatory| Description| 96 | -------- | -------- | -------- | -------- | 97 | device | [USBDevice](#usbdevice) | Yes| USB device information. | 98 99- **Return value** 100 | Type| Description| 101 | -------- | -------- | 102 | Readonly<[USBDevicePipe](#usbdevicepipe)> | USB device pipe for data transfer. | 103 104- **Example** 105 ```js 106 let devicepipe= usb.connectDevice(device); 107 console.log(`devicepipe = ${JSON.stringify(devicepipe)}`); 108 ``` 109 110 111## usb.hasRight 112 113hasRight(deviceName: string): boolean 114 115Checks whether the application has the permission to access the device. 116 117**System capability**: SystemCapability.USB.USBManager 118 119- **Parameters** 120 | Name| Type| Mandatory| Description| 121 | -------- | -------- | -------- | -------- | 122 | deviceName | string | Yes| Device name. | 123 124- **Return value** 125 | Type| Description| 126 | -------- | -------- | 127 | boolean | Returns **true** if the application has the permission to access the device; returns **false** otherwise. | 128 129- **Example** 130 ```js 131 let devicesName="1-1"; 132 let bool = usb.hasRight(devicesName); 133 console.log(bool); 134 ``` 135 136 137## usb.requestRight 138 139requestRight(deviceName: string): Promise<boolean> 140 141Requests the temporary permission for the application to access the USB device. 142 143**System capability**: SystemCapability.USB.USBManager 144 145- **Parameters** 146 | Name| Type| Mandatory| Description| 147 | -------- | -------- | -------- | -------- | 148 | deviceName | string | Yes| Device name. | 149 150- **Return value** 151 | Type| Description| 152 | -------- | -------- | 153 | Promise<boolean> | Returns **true** if the temporary device access permissions are granted; returns **false** otherwise. | 154 155- **Example** 156 ```js 157 let devicesName="1-1"; 158 usb.requestRight(devicesName).then((ret) => { 159 console.log(`requestRight = ${JSON.stringify(ret)}`); 160 }); 161 ``` 162 163## usb.claimInterface 164 165claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number 166 167Claims a USB interface. 168 169Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and USB interfaces, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 170 171**System capability**: SystemCapability.USB.USBManager 172 173- **Parameters** 174 | Name| Type| Mandatory| Description| 175 | -------- | -------- | -------- | -------- | 176 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | 177 | iface | [USBInterface](#usbinterface) | Yes| USB interface, which is used to determine the index of the interface to claim. | 178 | force | boolean | No| Whether to forcibly claim the USB interface. The default value is **false**, indicating not to forcibly claim the USB interface. | 179 180- **Return value** 181 | Type| Description| 182 | -------- | -------- | 183 | number | Returns **0** if the USB interface is successfully claimed; returns an error code otherwise. | 184 185- **Example** 186 ```js 187 let ret = usb.claimInterface(devicepipe, interfaces); 188 console.log(`claimInterface = ${ret}`); 189 ``` 190 191 192## usb.releaseInterface 193 194releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 195 196Releases a USB interface. 197 198Before you do this, ensure that you have claimed the interface by calling [usb.claimInterface](#usbclaiminterface). 199 200**System capability**: SystemCapability.USB.USBManager 201 202- **Parameters** 203 | Name| Type| Mandatory| Description| 204 | -------- | -------- | -------- | -------- | 205 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | 206 | iface | [USBInterface](#usbinterface) | Yes| USB interface, which is used to determine the index of the interface to release. | 207 208- **Return value** 209 | Type| Description| 210 | -------- | -------- | 211 | number | Returns **0** if the USB interface is successfully released; returns an error code otherwise. | 212 213- **Example** 214 ```js 215 let ret = usb.releaseInterface(devicepipe, interfaces); 216 console.log(`releaseInterface = ${ret}`); 217 ``` 218 219 220## usb.setConfiguration 221 222setConfiguration(pipe: USBDevicePipe, config: USBConfig): number 223 224Sets the device configuration. 225 226Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and device configuration, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 227 228**System capability**: SystemCapability.USB.USBManager 229 230- **Parameters** 231 | Name| Type| Mandatory| Description| 232 | -------- | -------- | -------- | -------- | 233 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | 234 | config | [USBConfig](#usbconfig) | Yes| USB configuration to set. | 235 236- **Return value** 237 | Type| Description| 238 | -------- | -------- | 239 | number | Returns **0** if the USB configuration is successfully set; returns an error code otherwise. | 240 241- **Example** 242 ```js 243 let ret = usb.setConfiguration(devicepipe, config); 244 console.log(`setConfiguration = ${ret}`); 245 ``` 246 247## usb.setInterface 248 249setInterface(pipe: USBDevicePipe, iface: USBInterface): number 250 251Sets a USB interface. 252 253Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and interfaces, call [usb.requestRight](#usbrequestright) to request the device access permission, call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter, and call [usb.claimInterface](#usbclaiminterface) to claim a USB interface.. 254 255**System capability**: SystemCapability.USB.USBManager 256 257- **Parameters** 258 | Name| Type| Mandatory| Description| 259 | -------- | -------- | -------- | -------- | 260 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | 261 | iface | [USBInterface](#usbinterface) | Yes| USB interface to set. | 262 263- **Return value** 264 | Type| Description| 265 | -------- | -------- | 266 | number | Returns **0** if the USB interface is successfully set; returns an error code otherwise. | 267 268- **Example** 269 ```js 270 let ret = usb.setInterface(devicepipe, interfaces); 271 console.log(`setInterface = ${ret}`); 272 ``` 273 274 275## usb.getRawDescriptor 276 277getRawDescriptor(pipe: USBDevicePipe): Uint8Array 278 279Obtains the raw USB descriptor. 280 281Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 282 283**System capability**: SystemCapability.USB.USBManager 284 285- **Parameters** 286 | Name| Type| Mandatory| Description| 287 | -------- | -------- | -------- | -------- | 288 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | 289 290- **Return value** 291 | Type| Description| 292 | -------- | -------- | 293 | Uint8Array | Raw descriptor data. The value **undefined** indicates that the operation has failed. | 294 295- **Example** 296 ```js 297 let ret = usb.getRawDescriptor(devicepipe); 298 ``` 299 300 301## usb.getFileDescriptor 302 303getFileDescriptor(pipe: USBDevicePipe): number 304 305Obtains the file descriptor. 306 307Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 308 309**System capability**: SystemCapability.USB.USBManager 310 311- **Parameters** 312 | Name| Type| Mandatory| Description| 313 | -------- | -------- | -------- | -------- | 314 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | 315 316- **Return value** 317 | Type| Description| 318 | -------- | -------- | 319 | number | File descriptor of the USB device. The value **-1** indicates that the operation has failed. | 320 321- **Example** 322 ```js 323 let ret = usb.getFileDescriptor(devicepipe); 324 ``` 325 326 327## usb.controlTransfer 328 329controlTransfer(pipe: USBDevicePipe, contrlparam: USBControlParams, timeout?: number): Promise<number> 330 331Performs control transfer. 332 333Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 334 335**System capability**: SystemCapability.USB.USBManager 336 337- **Parameters** 338 | Name| Type| Mandatory| Description| 339 | -------- | -------- | -------- | -------- | 340 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device. | 341 | contrlparam | [USBControlParams](#usbcontrolparams) | Yes| Control transfer parameters. | 342 | timeout | number | No| Timeout duration. The default value is **0**, indicating no timeout. | 343 344- **Return value** 345 | Type| Description| 346 | -------- | -------- | 347 | Promise<number> | Returns the size of the transmitted or received data block if the control transfer is successful; returns **-1** if an exception occurs. | 348 349- **Example** 350 ```js 351 usb.controlTransfer(devicepipe, USBControlParams).then((ret) => { 352 console.log(`controlTransfer = ${JSON.stringify(ret)}`); 353 }) 354 ``` 355 356 357## usb.bulkTransfer 358 359bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout?: number): Promise<number> 360 361Performs bulk transfer. 362 363Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and endpoints, call [usb.requestRight](#usbrequestright) to request the device access permission, call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter, and call [usb.claimInterface](#usbclaiminterface) to claim a USB interface. 364 365**System capability**: SystemCapability.USB.USBManager 366 367- **Parameters** 368 | Name| Type| Mandatory| Description| 369 | -------- | -------- | -------- | -------- | 370 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device. | 371 | endpoint | [USBEndpoint](#usbendpoint) | Yes| USB endpoint, which is used to determine the USB port for data transfer. | 372 | buffer | Uint8Array | Yes| Buffer for writing or reading data. | 373 | timeout | number | No| Timeout duration. The default value is **0**, indicating no timeout. | 374 375- **Return value** 376 | Type| Description| 377 | -------- | -------- | 378 | Promise<number> | Returns the size of the transmitted or received data block if the control transfer is successful; returns **-1** if an exception occurs. | 379 380- **Example** 381 ```js 382 // Call usb.getDevices to obtain a data set. Then, obtain a USB device and its access permission. 383 // Pass the obtained USB device as a parameter to usb.connectDevice. Then, call usb.connectDevice to connect the USB device. 384 // Call usb.claimInterface to claim a USB interface. After that, call usb.bulkTransfer to start bulk transfer. 385 usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => { 386 console.log(`bulkTransfer = ${JSON.stringify(ret)}`); 387 }); 388 ``` 389 390 391## usb.closePipe 392 393closePipe(pipe: USBDevicePipe): number 394 395Closes a USB device pipe. 396 397Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 398 399**System capability**: SystemCapability.USB.USBManager 400 401- **Parameters** 402 | Name| Type| Mandatory| Description| 403 | -------- | -------- | -------- | -------- | 404 | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe. | 405 406- **Return value** 407 | Type| Description| 408 | -------- | -------- | 409 | number | Returns **0** if the USB device pipe is closed successfully; returns an error code otherwise. | 410 411- **Example** 412 ```js 413 let ret = usb.closePipe(devicepipe); 414 console.log(`closePipe = ${ret}`); 415 ``` 416 417 418## USBEndpoint 419 420Represents the USB endpoint from which data is sent or received. You can obtain the USB endpoint through [USBInterface](#usbinterface). 421 422**System capability**: SystemCapability.USB.USBManager 423 424| Name| Type| Description| 425| -------- | -------- | -------- | 426| address | number | Endpoint address. | 427| attributes | number | Endpoint attributes. | 428| interval | number | Endpoint interval. | 429| maxPacketSize | number | Maximum size of data packets on the endpoint. | 430| direction | [USBRequestDirection](#usbrequestdirection) | Endpoint direction. | 431| number | number | Endpoint number. | 432| type | number | Endpoint type. | 433| interfaceId | number | Unique ID of the interface to which the endpoint belongs. | 434 435 436## USBInterface 437 438Represents a USB interface. One [USBConfig](#usbconfig) can contain multiple **USBInterface** instances, each providing a specific function. 439 440**System capability**: SystemCapability.USB.USBManager 441 442| Name| Type| Description| 443| -------- | -------- | -------- | 444| id | number | Unique ID of the USB interface. | 445| protocol | number | Interface protocol. | 446| clazz | number | Device type. | 447| subClass | number | Device subclass. | 448| alternateSetting | number | Settings for alternating between descriptors of the same USB interface. | 449| name | string | Interface name. | 450| endpoints | Array<[USBEndpoint](#usbendpoint)> | Endpoints that belong to the USB interface. | 451 452 453## USBConfig 454 455Represents the USB configuration. One [USBDevice](#usbdevice) can contain multiple **USBConfig** instances. 456 457**System capability**: SystemCapability.USB.USBManager 458 459| Name| Type| Description| 460| -------- | -------- | -------- | 461| id | number | Unique ID of the USB configuration. | 462| attributes | number | Configuration attributes. | 463| maxPower | number | Maximum power consumption, in mA. | 464| name | string | Configuration name, which can be left empty. | 465| isRemoteWakeup | boolean | Support for remote wakeup. | 466| isSelfPowered | boolean | Support for independent power supplies. | 467| interfaces | Array <[USBInterface](#usbinterface)> | Supported interface attributes. | 468 469 470## USBDevice 471 472Represents USB device information. 473 474**System capability**: SystemCapability.USB.USBManager 475 476| Name| Type| Description| 477| -------- | -------- | -------- | 478| busNum | number | Bus address. | 479| devAddress | number | Device address. | 480| serial | string | Device SN. | 481| name | string | Device name. | 482| manufacturerName | string | Device manufacturer. | 483| productName | string | Product information. | 484| version | string | Version. | 485| vendorId | number | Vendor ID. | 486| productId | number | Product ID. | 487| clazz | number | Device class. | 488| subClass | number | Device subclass. | 489| protocol | number | Device protocol code. | 490| configs | Array<[USBConfig](#usbconfig)> | Device configuration descriptor information. | 491 492 493## USBDevicePipe 494 495Represents a USB device pipe, which is used to determine a USB device. 496 497**System capability**: SystemCapability.USB.USBManager 498 499| Name| Type| Description| 500| -------- | -------- | -------- | 501| busNum | number | Bus address. | 502| devAddress | number | Device address. | 503 504 505## USBControlParams 506 507Represents control transfer parameters. 508 509**System capability**: SystemCapability.USB.USBManager 510 511| Name| Type| Description| 512| -------- | -------- | -------- | 513| request | number | Request type. | 514| target | [USBRequestTargetType](#usbrequesttargettype) | Type of the request target. | 515| reqType | [USBControlRequestType](#usbcontrolrequesttype) | Request control type. | 516| value | number | Request parameters| 517| index | number | Index of the request parameter value. | 518| data | Uint8Array | Buffer for writing or reading data. | 519 520 521## USBRequestTargetType 522 523Represents the request target type. 524 525**System capability**: SystemCapability.USB.USBManager 526 527| Name| Default Value | Description| 528| -------- | -------- | -------- | 529| USB_REQUEST_TARGET_DEVICE | 0 | Device. | 530| USB_REQUEST_TARGET_INTERFACE | 1 | Interface. | 531| USB_REQUEST_TARGET_ENDPOINT | 2 | Endpoint| 532| USB_REQUEST_TARGET_OTHER | 3 | Others| 533 534 535## USBControlRequestType 536 537Enumerates control request types. 538 539**System capability**: SystemCapability.USB.USBManager 540 541| Name| Default Value | Description| 542| -------- | -------- | -------- | 543| USB_REQUEST_TYPE_STANDARD | 0 | Standard| 544| USB_REQUEST_TYPE_CLASS | 1 | Class. | 545| USB_REQUEST_TYPE_VENDOR | 2 | Vendor| 546 547 548## USBRequestDirection 549 550Enumerates request directions. 551 552**System capability**: SystemCapability.USB.USBManager 553 554| Name| Default Value | Description| 555| -------- | -------- | -------- | 556| USB_REQUEST_DIR_TO_DEVICE | 0 | Request for writing data from the host to the device. | 557| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | Request for reading data from the device to the host. | 558