• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# USB Device Management
2
3## When to Use
4
5When a USB device is inserted, you can use **usbManager** to obtain basic information about the USB device, such as the device type and supported functions. The host communicates with the USB device through the encapsulated pipe. In OpenHarmony, the USB management service is the core component that manages the connection and communication with USB devices. With the USB management service, applications can detect the USB connection and disconnection, manage permission requests and device configurations of USB devices, and perform data transfer and device control.
6
7## Environment Preparation
8
9### Environment Requirements
10
11- Development tool and configuration:
12
13  DevEco Studio, as the driver development tool, allows you to develop, debug, and package drivers. [Download and install](https://developer.huawei.com/consumer/cn/download/) DevEco Studio and verify basic operations to ensure that it can function properly. For details, see [Creating and Running a Project](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-create-new-project-V14) in [DevEco Studio User Guide](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-tools-overview-V14).
14
15
16- SDK version configuration:
17
18  The ArkTs APIs for peripheral management can be used only when the SDK is of API version 16 or later.
19
20
21- HDC configuration:
22
23  HarmonyOS Device Connector (hdc) is a command-line tool for debugging. It can be used to interact with real devices or the Emulators on Windows, Linux, and macOS. For details about the configuration, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
24
25### Environment Setup
26
27- Install [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 4.1 or later on the PC.
28- Update the public SDK to API version 16 or later. For details, see [Update Guide](https://gitee.com/openharmony/docs/blob/master/en/application-dev/faqs/full-sdk-switch-guide.md).
29- Install hdc on the PC. You can use it to interact with a real device or the Emulator on Windows, Linux, or macOS. For details, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
30- Use a USB cable to connect an OpenHarmony device to the PC.
31
32## How to Develop
33
34### Available APIs
35
36USB device management provides the following functions: querying the USB device list, controlling USB device permissions, and setting USB device configurations.
37
38The following table lists the USB APIs currently available. For details, see [@ohos.usbManager (USB Manager)](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md).
39
40**Table 1** Open USB APIs
41
42| API                                                      | Description                                                        |
43| ------------------------------------------------------------ | ------------------------------------------------------------ |
44| hasRight(deviceName: string): boolean                         | Checks whether the USB has the device access permissions.|
45| requestRight(deviceName: string): Promise<boolean>       | Requests the temporary permission for the application to access the USB device. This API uses a promise to return the result.                       |
46| removeRight(deviceName: string): boolean | Removes the device access permissions of the application.|
47| connectDevice(device: USBDevice): Readonly<USBDevicePipe> | Connects to the USB device based on the device information returned by **getDevices()**.               |
48| getDevices(): Array<Readonly<USBDevice>>          | Obtains the list of USB devices connected to the host. If no device is connected, an empty list is returned.                                           |
49| setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number | Sets the USB device configuration.                                            |
50| setInterface(pipe: USBDevicePipe, iface: USBInterface): number   | Sets a USB interface.                                            |
51| claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number | Claims a USB interface.                                                  |
52| closePipe(pipe: USBDevicePipe): number                         | Closes a USB device pipe.                                      |
53| releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number | Releases a USB interface.                                                  |
54| getFileDescriptor(pipe: USBDevicePipe): number                 | Obtains the file descriptor of a USB device.                                            |
55| getRawDescriptor(pipe: USBDevicePipe): Uint8Array              | Obtains the raw USB descriptor.                                       |
56
57### How to Develop
58
59A USB device can be used as a host to connect to a device for management. The procedure is as follows:
60
61
621. Import modules.
63
64   ```ts
65   // Import the usbManager module.
66   import { usbManager } from '@kit.BasicServicesKit';
67   import { BusinessError } from '@kit.BasicServicesKit';
68   ```
69
702. Obtain the USB device list.
71
72   ```ts
73   // Obtain the USB device list.
74   let deviceList : Array<usbManager.USBDevice> = usbManager.getDevices();
75   /*
76   Example deviceList structure:
77   [
78     {
79       name: "1-1",
80       serial: "",
81       manufacturerName: "",
82       productName: "",
83       version: "",
84       vendorId: 7531,
85       productId: 2,
86       clazz: 9,
87       subClass: 0,
88       protocol: 1,
89       devAddress: 1,
90       busNum: 1,
91       configs: [
92         {
93           id: 1,
94           attributes: 224,
95           isRemoteWakeup: true,
96           isSelfPowered: true,
97           maxPower: 0,
98           name: "1-1",
99           interfaces: [
100             {
101               id: 0,
102               protocol: 0,
103               clazz: 9,
104               subClass: 0,
105               alternateSetting: 0,
106               name: "1-1",
107               endpoints: [
108                 {
109                   address: 129,
110                   attributes: 3,
111                   interval: 12,
112                   maxPacketSize: 4,
113                   direction: 128,
114                   number: 1,
115                   type: 3,
116                   interfaceId: 0,
117                 }
118               ]
119             }
120           ]
121         }
122       ]
123     }
124   ]
125   */
126   ```
127
1283. Obtain the device operation permissions.
129
130   ```ts
131   let deviceName : string = deviceList[0].name;
132   // Request the permissions to operate a specified device.
133   usbManager.requestRight(deviceName).then((hasRight : boolean) => {
134     console.info("usb device request right result: " + hasRight);
135   }).catch((error : BusinessError)=> {
136     console.info("usb device request right failed : " + error);
137   });
138   ```
139
1404. Open the device.
141
142   ```ts
143   // Open the device, and obtain the USB device pipe for data transfer.
144   let pipe : usbManager.USBDevicePipe = usbManager.connectDevice(deviceList[0]);
145   let interface1 : usbManager.USBInterface = deviceList[0].configs[0].interfaces[0];
146   /*
147    Claim the corresponding interface from **deviceList**.
148   interface1 must be one present in the device configuration.
149   */
150   usbManager.claimInterface(pipe, interface1, true);
151   ```
152
1535. Release the USB interface, and close the USB device.
154
155   ```ts
156   usbManager.releaseInterface(pipe, interface1);
157   usbManager.closePipe(pipe);
158   ```
159
160