USB

This module provides USB device management functions, including USB device list query, bulk data transfer, control transfer, and permission control.

NOTE

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

import usb from "@ohos.usb";

usb.getDevices

getDevices(): Array<Readonly<USBDevice>>

Obtains the USB device list.

System capability: SystemCapability.USB.USBManager

• Return value

• Example

  let devicesList = usb.getDevices();
  console.log(`devicesList = ${JSON.stringify(devicesList)}`);
  // devicesList is a list of USB devices.
  // A simple example of devicesList is provided as follows:
  [
    {
      name: "1-1",
      serial: "",
      manufacturerName: "",
      productName: "",
      version: "",
      vendorId: 7531,
      productId: 2,
      clazz: 9,
      subclass: 0,
      protocol: 1,
      devAddress: 1,
      busNum: 1,
      configs: [
        {
          id: 1,
          attributes: 224,
          isRemoteWakeup: true,
          isSelfPowered: true,
          maxPower: 0,
          name: "1-1",
          interfaces: [
            {
              id: 0,
              protocol: 0,
              clazz: 9,
              subclass: 0,
              alternateSetting: 0,
              name: "1-1",
              endpoints: [
                {
                  address: 129,
                  attributes: 3,
                  interval: 12,
                  maxPacketSize: 4,
                  direction: 128,
                  number: 1,
                  type: 3,
                  interfaceId: 0,
                },
              ],
            },
          ],
        },
      ],
    },
  ]
  

usb.connectDevice

connectDevice(device: USBDevice): Readonly<USBDevicePipe>

Connects to a USB device.

Before you do this, call usb.getDevices to obtain the USB device list, and then call usb.requestRight to request the device access permission.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let devicepipe= usb.connectDevice(device);
  console.log(`devicepipe = ${JSON.stringify(devicepipe)}`);
  

usb.hasRight

hasRight(deviceName: string): boolean

Checks whether the application has the permission to access the device.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let devicesName="1-1";
  let bool = usb.hasRight(devicesName);
  console.log(bool);
  

usb.requestRight

requestRight(deviceName: string): Promise<boolean>

Requests the temporary permission for the application to access the USB device.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let devicesName="1-1";
  usb.requestRight(devicesName).then((ret) => {
    console.log(`requestRight = ${JSON.stringify(ret)}`);
  });
  

usb.claimInterface

claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number

Claims a USB interface.

Before you do this, call usb.getDevices to obtain the USB device list and USB interfaces, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let ret = usb.claimInterface(devicepipe, interfaces);
  console.log(`claimInterface = ${ret}`);
  

usb.releaseInterface

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.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let ret = usb.releaseInterface(devicepipe, interfaces);
  console.log(`releaseInterface = ${ret}`);
  

usb.setConfiguration

setConfiguration(pipe: USBDevicePipe, config: USBConfig): number

Sets the device configuration.

Before you do this, call usb.getDevices to obtain the USB device list and device configuration, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let ret = usb.setConfiguration(devicepipe, config);
  console.log(`setConfiguration = ${ret}`);
  

usb.setInterface

setInterface(pipe: USBDevicePipe, iface: USBInterface): number

Sets a USB interface.

Before you do this, call usb.getDevices to obtain the USB device list and interfaces, call usb.requestRight to request the device access permission, call usb.connectDevice to obtain devicepipe as an input parameter, and call usb.claimInterface to claim a USB interface..

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let ret = usb.setInterface(devicepipe, interfaces);
  console.log(`setInterface = ${ret}`);
  

usb.getRawDescriptor

getRawDescriptor(pipe: USBDevicePipe): Uint8Array

Obtains the raw USB descriptor.

Before you do this, call usb.getDevices to obtain the USB device list, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let ret = usb.getRawDescriptor(devicepipe);
  

usb.getFileDescriptor

getFileDescriptor(pipe: USBDevicePipe): number

Obtains the file descriptor.

Before you do this, call usb.getDevices to obtain the USB device list, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  let ret = usb.getFileDescriptor(devicepipe);
  

usb.controlTransfer

controlTransfer(pipe: USBDevicePipe, contrlparam: USBControlParams, timeout?: number): Promise<number>

Performs control transfer.

Before you do this, call usb.getDevices to obtain the USB device list, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• Example

  usb.controlTransfer(devicepipe, USBControlParams).then((ret) => {
   console.log(`controlTransfer = ${JSON.stringify(ret)}`);
  })
  

usb.bulkTransfer

bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout?: number): Promise<number>

Performs bulk transfer.

Before you do this, call usb.getDevices to obtain the USB device list and endpoints, call usb.requestRight to request the device access permission, call usb.connectDevice to obtain devicepipe as an input parameter, and call usb.claimInterface to claim a USB interface.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• 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 a USB interface. After that, call usb.bulkTransfer to start bulk transfer.
  usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => {
   console.log(`bulkTransfer = ${JSON.stringify(ret)}`);
  });
  

usb.closePipe

closePipe(pipe: USBDevicePipe): number

Closes a USB device pipe.

Before you do this, call usb.getDevices to obtain the USB device list, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

• Parameters

• Return value

• 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.

System capability: SystemCapability.USB.USBManager

USBInterface

Represents a USB interface. One USBConfig can contain multiple USBInterface instances, each providing a specific function.

System capability: SystemCapability.USB.USBManager

USBConfig

Represents the USB configuration. One USBDevice can contain multiple USBConfig instances.

System capability: SystemCapability.USB.USBManager

USBDevice

Represents USB device information.

System capability: SystemCapability.USB.USBManager

USBDevicePipe

Represents a USB device pipe, which is used to determine a USB device.

System capability: SystemCapability.USB.USBManager

USBControlParams

Represents control transfer parameters.

System capability: SystemCapability.USB.USBManager

USBRequestTargetType

Represents the request target type.

System capability: SystemCapability.USB.USBManager

USBControlRequestType

Enumerates control request types.

System capability: SystemCapability.USB.USBManager

USBRequestDirection

Enumerates request directions.

System capability: SystemCapability.USB.USBManager