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