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