>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.
>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.
## Modules to Import<a name="section290293011431"></a>
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list, and then call [usb.requestRight](#section1865915394353) to request the device access permission.
<td class="cellrowborder" valign="top" width="65.74%" headers="mcps1.1.3.1.2 "><p id="p61806241379"><a name="p61806241379"></a><a name="p61806241379"></a>Returns <strong id="b374713583399"><a name="b374713583399"></a><a name="b374713583399"></a>true</strong> if the user has the permission to access the device; returns <strong id="b73287154014"><a name="b73287154014"></a><a name="b73287154014"></a>false</strong> otherwise.</p>
Before 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.
usb.claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number
Claims a USB interface.
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list and USB interfaces, call [usb.requestRight](#section1865915394353) to request the device access permission, and call [usb.connectDevice](#section910254722918) to obtain **devicepipe** as an input parameter.
<td class="cellrowborder" valign="top" width="39.74602539746026%" headers="mcps1.1.5.1.4 "><p id="p17171016185216"><a name="p17171016185216"></a><a name="p17171016185216"></a>Device pipe, which is used to determine the bus number and device address.</p>
<td class="cellrowborder" valign="top" width="39.74602539746026%" headers="mcps1.1.5.1.4 "><p id="p2718316195211"><a name="p2718316195211"></a><a name="p2718316195211"></a>USB interface, which is used to determine the index of the interface to claim.</p>
<td class="cellrowborder" valign="top" width="39.74602539746026%" headers="mcps1.1.5.1.4 "><p id="p1720161611526"><a name="p1720161611526"></a><a name="p1720161611526"></a>Optional parameter that determines whether to forcibly claim the USB interface. The default value is <strong id="b2873547174813"><a name="b2873547174813"></a><a name="b2873547174813"></a>false</strong>, indicating not to forcibly claim the USB interface.</p>
<td class="cellrowborder" valign="top" width="65.28%" headers="mcps1.1.3.1.2 "><p id="p20467115711241"><a name="p20467115711241"></a><a name="p20467115711241"></a>Returns <strong id="b28948816529"><a name="b28948816529"></a><a name="b28948816529"></a>0</strong> if the USB interface is successfully claimed; returns an error code otherwise.</p>
</td>
</tr>
</tbody>
</table>
- Example
```
let ret = usb.claimInterface(devicepipe, interfaces);
usb.releaseInterface\(pipe: USBDevicePipe, iface: USBInterface\): number
Before 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.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.|
| iface | [USBInterface](#usbinterface) | Yes| USB interface, which is used to determine the index of the interface to claim.|
| force | boolean | No| Whether to forcibly claim the USB interface. The default value is **false**, indicating not to forcibly claim the USB interface.|
- Return value
| Type| Description|
| -------- | -------- |
| number | Returns **0** if the USB interface is successfully claimed; returns an error code otherwise.|
- Example
```
let ret = usb.claimInterface(devicepipe, interfaces);
console.log(`claimInterface = ${ret}`);
```
## usb.releaseInterface
usb.releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number
Releases a USB interface.
Before you do this, ensure that you have claimed the interface by calling [usb.claimInterface](#section41056254494).
<td class="cellrowborder" valign="top" width="38.519999999999996%" headers="mcps1.1.5.1.4 "><p id="p198771214185413"><a name="p198771214185413"></a><a name="p198771214185413"></a>Device pipe, which is used to determine the bus number and device address.</p>
<td class="cellrowborder" valign="top" width="38.519999999999996%" headers="mcps1.1.5.1.4 "><p id="p13877181420547"><a name="p13877181420547"></a><a name="p13877181420547"></a>USB interface, which is used to determine the index of the interface to release.</p>
<td class="cellrowborder" valign="top" width="57.14%" headers="mcps1.1.3.1.2 "><p id="p18243112172516"><a name="p18243112172516"></a><a name="p18243112172516"></a>Returns <strong id="b142281811260"><a name="b142281811260"></a><a name="b142281811260"></a>0</strong> if the USB interface is successfully released; returns an error code otherwise.</p>
</td>
</tr>
</tbody>
</table>
- Example
```
let ret = usb.releaseInterface(devicepipe, interfaces);
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.|
| iface | [USBInterface](#usbinterface) | Yes| USB interface, which is used to determine the index of the interface to release.|
- Return value
| Type| Description|
| -------- | -------- |
| number | Returns **0** if the USB interface is successfully released; returns an error code otherwise.|
- Example
```
let ret = usb.releaseInterface(devicepipe, interfaces);
console.log(`releaseInterface = ${ret}`);
```
## usb.setConfiguration
usb.setConfiguration(pipe: USBDevicePipe, config: USBConfig): number
Sets the device configuration.
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list and device configuration, call [usb.requestRight](#section1865915394353) to request the device access permission, and call [usb.connectDevice](#section910254722918) to obtain **devicepipe** as an input parameter.
<td class="cellrowborder" valign="top" width="45.69456945694569%" headers="mcps1.1.5.1.4 "><p id="p115161830195710"><a name="p115161830195710"></a><a name="p115161830195710"></a>Device pipe, which is used to determine the bus number and device address.</p>
<td class="cellrowborder" valign="top" width="67.25%" headers="mcps1.1.3.1.2 "><p id="p1516442172518"><a name="p1516442172518"></a><a name="p1516442172518"></a>Returns <strong id="b9415254392"><a name="b9415254392"></a><a name="b9415254392"></a>0</strong> if the USB configuration is successfully set; returns an error code otherwise.</p>
</td>
</tr>
</tbody>
</table>
- Example
```
let ret = usb.setConfiguration(devicepipe, config);
usb.setInterface\(pipe: USBDevicePipe, iface: USBInterface\): number
Before 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.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.|
| config | [USBConfig](#usbconfig) | Yes| USB configuration to set.|
- Return value
| Type| Description|
| -------- | -------- |
| number | Returns **0** if the USB configuration is successfully set; returns an error code otherwise.|
- Example
```
let ret = usb.setConfiguration(devicepipe, config);
console.log(`setConfiguration = ${ret}`);
```
## usb.setInterface
usb.setInterface(pipe: USBDevicePipe, iface: USBInterface): number
Sets a USB interface.
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list and interfaces, call [usb.requestRight](#section1865915394353) to request the device access permission, and call [usb.connectDevice](#section910254722918) to obtain **devicepipe** as an input parameter.
<td class="cellrowborder" valign="top" width="39.4%" headers="mcps1.1.5.1.4 "><p id="p64511725195917"><a name="p64511725195917"></a><a name="p64511725195917"></a>Device pipe, which is used to determine the bus number and device address.</p>
<td class="cellrowborder" valign="top" width="58.269999999999996%" headers="mcps1.1.3.1.2 "><p id="p14451925205917"><a name="p14451925205917"></a><a name="p14451925205917"></a>Returns <strong id="b1789672118129"><a name="b1789672118129"></a><a name="b1789672118129"></a>0</strong> if the USB interface is successfully set; returns an error code otherwise.</p>
</td>
</tr>
</tbody>
</table>
- Example
```
let ret = usb.setInterface(devicepipe, interfaces);
Before 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, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter.
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list, call [usb.requestRight](#section1865915394353) to request the device access permission, and call [usb.connectDevice](#section910254722918) to obtain **devicepipe** as an input parameter.
<td class="cellrowborder" valign="top" width="37.22%" headers="mcps1.1.5.1.4 "><p id="p184921456112"><a name="p184921456112"></a><a name="p184921456112"></a>Device pipe, which is used to determine the bus number and device address.</p>
usb.getFileDescriptor\(pipe: USBDevicePipe\): number
Before 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.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.|
- Return value
| Type| Description|
| -------- | -------- |
| Uint8Array | Raw descriptor data.|
- Example
```
let ret = usb.getRawDescriptor(devicepipe);
```
## usb.getFileDescriptor
usb.getFileDescriptor(pipe: USBDevicePipe): number
Obtains the file descriptor.
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list, call [usb.requestRight](#section1865915394353) to request the device access permission, and call [usb.connectDevice](#section910254722918) to obtain **devicepipe** as an input parameter.
<td class="cellrowborder" valign="top" width="40.33%" headers="mcps1.1.5.1.4 "><p id="p84082301210"><a name="p84082301210"></a><a name="p84082301210"></a>Device pipe, which is used to determine the bus number and device address.</p>
<td class="cellrowborder" valign="top" width="67.12%" headers="mcps1.1.3.1.2 "><p id="p4422166132810"><a name="p4422166132810"></a><a name="p4422166132810"></a>File descriptor of the USB device.</p>
Before 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.
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list, call [usb.requestRight](#section1865915394353) to request the device access permission, and call [usb.connectDevice](#section910254722918) to obtain **devicepipe** as an input parameter.
<td class="cellrowborder" valign="top" width="41.24%" headers="mcps1.1.5.1.4 "><p id="p8779145936"><a name="p8779145936"></a><a name="p8779145936"></a>USB device pipe, which is used to determine the USB device.</p>
<td class="cellrowborder" valign="top" width="41.24%" headers="mcps1.1.5.1.4 "><p id="p87791245533"><a name="p87791245533"></a><a name="p87791245533"></a>Timeout duration. This parameter is optional. The default value is <strong id="b11780926132116"><a name="b11780926132116"></a><a name="b11780926132116"></a>0</strong>, indicating no timeout.</p>
<td class="cellrowborder" valign="top" width="63.79%" headers="mcps1.1.3.1.2 "><p id="p340635120499"><a name="p340635120499"></a><a name="p340635120499"></a>Returns the size of the transmitted or received data block if the control transfer is successful; returns <strong id="b19451442152714"><a name="b19451442152714"></a><a name="b19451442152714"></a>-1</strong> if an exception occurs.</p>
Before 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.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.|
| contrlparam | [USBControlParams](#usbcontrolparams) | Yes| Control transfer parameters.|
| timeout | number | No| Timeout duration. The default value is **0**, indicating no timeout.|
- Return value
| Type| Description|
| -------- | -------- |
| Promise<number> | Returns the size of the transmitted or received data block if the control transfer is successful; returns **-1** if an exception occurs.|
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list and endpoints, call [usb.requestRight](#section1865915394353) to request the device access permission, call [usb.connectDevice](#section910254722918) to obtain **devicepipe** as an input parameter, and call [usb.claimInterface](#section41056254494) to claim the USB interface.
<td class="cellrowborder" valign="top" width="45.66456645664567%" headers="mcps1.1.5.1.4 "><p id="p1982716141569"><a name="p1982716141569"></a><a name="p1982716141569"></a>USB device pipe, which is used to determine the USB device.</p>
<td class="cellrowborder" valign="top" width="45.66456645664567%" headers="mcps1.1.5.1.4 "><p id="p98271149613"><a name="p98271149613"></a><a name="p98271149613"></a>USB endpoint, which is used to determine the USB port for data transfer.</p>
<td class="cellrowborder" valign="top" width="45.66456645664567%" headers="mcps1.1.5.1.4 "><p id="p1982720141468"><a name="p1982720141468"></a><a name="p1982720141468"></a>Timeout duration. This parameter is optional. The default value is <strong id="b1179575510347"><a name="b1179575510347"></a><a name="b1179575510347"></a>0</strong>, indicating no timeout.</p>
<td class="cellrowborder" valign="top" width="68.03%" headers="mcps1.1.3.1.2 "><p id="p47448548549"><a name="p47448548549"></a><a name="p47448548549"></a>Returns the size of the transmitted or received data block if the control transfer is successful; returns <strong id="b1534141920393"><a name="b1534141920393"></a><a name="b1534141920393"></a>-1</strong> if an exception occurs.</p>
</td>
</tr>
</tbody>
</table>
- Example
```
// Call usb.getDevices to obtain a data set. Then, obtain a USB device and its access permission.
// Pass the obtained USB device as a parameter to usb.connectDevice. Then, call usb.connectDevice to connect the USB device.
// Call usb.claimInterface to claim the USB interface. After that, call usb.bulkTransfer to start bulk transfer.
Before 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.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.|
| endpoint | [USBEndpoint](#usbendpoint) | Yes| USB endpoint, which is used to determine the USB port for data transfer.|
| buffer | Uint8Array | Yes| Buffer for writing or reading data.|
| timeout | number | No| Timeout duration. The default value is **0**, indicating no timeout.|
- Return value
| Type| Description|
| -------- | -------- |
| Promise<number> | Returns the size of the transmitted or received data block if the control transfer is successful; returns **-1** if an exception occurs.|
- Example
```
// Call usb.getDevices to obtain a data set. Then, obtain a USB device and its access permission.
// Pass the obtained USB device as a parameter to usb.connectDevice. Then, call usb.connectDevice to connect the USB device.
// Call usb.claimInterface to claim the USB interface. After that, call usb.bulkTransfer to start bulk transfer.
Before you do this, call [usb.getDevices](#section1885592111287) to obtain the USB device list, call [usb.requestRight](#section1865915394353) to request the device access permission, and call [usb.connectDevice](#section910254722918) to obtain **devicepipe** as an input parameter.
<tdclass="cellrowborder"valign="top"width="38.59385938593859%"headers="mcps1.1.4.1.3 "><pid="p9942716696"><aname="p9942716696"></a><aname="p9942716696"></a>Maximum size of data packets on the endpoint.</p>
<tdclass="cellrowborder"valign="top"width="38.59385938593859%"headers="mcps1.1.4.1.3 "><pid="p4598558171112"><aname="p4598558171112"></a><aname="p4598558171112"></a>Unique ID of the interface to which the endpoint belongs.</p>
Represents a USB interface. One [USBConfig](#section1172111051715) can contain multiple **USBInterface** instances, each providing a specific function.
<tdclass="cellrowborder"valign="top"width="44.354435443544354%"headers="mcps1.1.4.1.3 "><pid="p16707308165"><aname="p16707308165"></a><aname="p16707308165"></a>Unique ID of the USB interface.</p>
<tdclass="cellrowborder"valign="top"width="44.354435443544354%"headers="mcps1.1.4.1.3 "><pid="p237014114169"><aname="p237014114169"></a><aname="p237014114169"></a>Settings for alternating between descriptors of the same USB interface.</p>
<tdclass="cellrowborder"valign="top"width="44.354435443544354%"headers="mcps1.1.4.1.3 "><pid="p683718011161"><aname="p683718011161"></a><aname="p683718011161"></a>Endpoints that belong to the USB interface.</p>
</td>
</tr>
</tbody>
</table>
## USBConfig<a name="section1172111051715"></a>
Represents the USB configuration. One [USBDevice](#section14936845182012) can contain multiple **USBConfig** instances.
<tdclass="cellrowborder"valign="top"width="37.99379937993799%"headers="mcps1.1.4.1.3 "><pid="p1094317273193"><aname="p1094317273193"></a><aname="p1094317273193"></a>Unique ID of the USB configuration.</p>
<tdclass="cellrowborder"valign="top"width="37.99379937993799%"headers="mcps1.1.4.1.3 "><pid="p161021238181916"><aname="p161021238181916"></a><aname="p161021238181916"></a>Maximum power consumption, in mA.</p>
<tdclass="cellrowborder"valign="top"width="37.99379937993799%"headers="mcps1.1.4.1.3 "><pid="p18689114391910"><aname="p18689114391910"></a><aname="p18689114391910"></a>Configuration name, which can be left empty.</p>
<tdclass="cellrowborder"valign="top"width="37.99379937993799%"headers="mcps1.1.4.1.3 "><pid="p235313485193"><aname="p235313485193"></a><aname="p235313485193"></a>Support for remote wakeup.</p>
<tdclass="cellrowborder"valign="top"width="37.99379937993799%"headers="mcps1.1.4.1.3 "><pid="p1086955314191"><aname="p1086955314191"></a><aname="p1086955314191"></a>Support for independent power supplies.</p>
Before 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.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe.|
- Return value
| Type| Description|
| -------- | -------- |
| number | Returns **0** if the USB device pipe is closed successfully; returns an error code otherwise.|
- Example
```
let ret = usb.closePipe(devicepipe);
console.log(`closePipe = ${ret}`);
```
## USBEndpoint
Represents the USB endpoint from which data is sent or received. You can obtain the USB endpoint through [USBInterface](#usbinterface).
| Name| Type| Description|
| -------- | -------- | -------- |
| address | number | Endpoint address. <br>**System capability**: SystemCapability.USB.USBManager|
| attributes | number | Endpoint attributes. <br>**System capability**: SystemCapability.USB.USBManager|
| interval | number | Endpoint interval. <br>**System capability**: SystemCapability.USB.USBManager|
| maxPacketSize | number | Maximum size of data packets on the endpoint. <br>**System capability**: SystemCapability.USB.USBManager|
| direction | [USBRequestDirection](#usbrequestdirection) | Endpoint direction. <br>**System capability**: SystemCapability.USB.USBManager|
| number | number | Endpoint number. <br>**System capability**: SystemCapability.USB.USBManager|
| type | number | Endpoint type. <br>**System capability**: SystemCapability.USB.USBManager|
| interfaceId | number | Unique ID of the interface to which the endpoint belongs. <br>**System capability**: SystemCapability.USB.USBManager|
## USBInterface
Represents a USB interface. One [USBConfig](#usbconfig) can contain multiple **USBInterface** instances, each providing a specific function.
| Name| Type| Description|
| -------- | -------- | -------- |
| id | number | Unique ID of the USB interface. <br>**System capability**: SystemCapability.USB.USBManager|
| protocol | number | Interface protocol. <br>**System capability**: SystemCapability.USB.USBManager|
| clazz | number | Device type. <br>**System capability**: SystemCapability.USB.USBManager|
| subClass | number | Device subclass. <br>**System capability**: SystemCapability.USB.USBManager|
| alternateSetting | number | Settings for alternating between descriptors of the same USB interface. <br>**System capability**: SystemCapability.USB.USBManager|
| name | string | Interface name. <br>**System capability**: SystemCapability.USB.USBManager|
| endpoints | Array<[USBEndpoint](#usbendpoint)> | Endpoints that belong to the USB interface. <br>**System capability**: SystemCapability.USB.USBManager|
## USBConfig
Represents the USB configuration. One [USBDevice](#usbdevice) can contain multiple **USBConfig** instances.
| Name| Type| Description|
| -------- | -------- | -------- |
| id | number | Unique ID of the USB configuration. <br>**System capability**: SystemCapability.USB.USBManager|
| attributes | number | Configuration attributes. <br>**System capability**: SystemCapability.USB.USBManager|
| maxPower | number | Maximum power consumption, in mA. <br>**System capability**: SystemCapability.USB.USBManager|
| name | string | Configuration name, which can be left empty. <br>**System capability**: SystemCapability.USB.USBManager|
| isRemoteWakeup | boolean | Support for remote wakeup. <br>**System capability**: SystemCapability.USB.USBManager|
| isSelfPowered | boolean | Support for independent power supplies. <br>**System capability**: SystemCapability.USB.USBManager|
<tdclass="cellrowborder"valign="top"width="38.53614638536146%"headers="mcps1.1.4.1.3 "><pid="p191111139143312"><aname="p191111139143312"></a><aname="p191111139143312"></a>Request control type.</p>
<tdclass="cellrowborder"valign="top"width="38.53614638536146%"headers="mcps1.1.4.1.3 "><pid="p1673791919332"><aname="p1673791919332"></a><aname="p1673791919332"></a>Index of the request parameter value.</p>
<tdclass="cellrowborder"valign="top"width="38.53614638536146%"headers="mcps1.1.4.1.3 "><pid="p1565854183315"><aname="p1565854183315"></a><aname="p1565854183315"></a>Data written to or read from the buffer.</p>
<tdclass="cellrowborder"valign="top"width="37.46%"headers="mcps1.1.4.1.3 "><pid="p596515259559"><aname="p596515259559"></a><aname="p596515259559"></a>Request for writing data from the host to the device.</p>
<tdclass="cellrowborder"valign="top"width="37.46%"headers="mcps1.1.4.1.3 "><pid="p134812124563"><aname="p134812124563"></a><aname="p134812124563"></a>Request for reading data from the device to the host.</p>
<tdclass="cellrowborder"valign="top"width="32.45%"headers="mcps1.1.4.1.3 "><pid="p191370245"><aname="p191370245"></a><aname="p191370245"></a>Serial port device</p>
<tdclass="cellrowborder"valign="top"width="32.45%"headers="mcps1.1.4.1.3 "><pid="p1813110844"><aname="p1813110844"></a><aname="p1813110844"></a>Ethernet port device</p>
