1# USB Service Development
2
3
4
5## When to Use
6
7In Host mode, you can obtain the list of connected USB devices, enable or disable the devices, manage device access permissions, and perform data transfer or control transfer.
8
9
10## Available APIs
11
12The USB service provides the following functions: query of USB device list, bulk data transfer, control transfer, and access permission management.
13
14The following table lists the USB APIs currently available. For details, see the [API Reference](../../reference/apis-basic-services-kit/js-apis-usbManager.md).
15
16**Table 1** Open USB APIs
17
18| Name                                                      | Description                                                        |
19| ------------------------------------------------------------ | ------------------------------------------------------------ |
20| hasRight(deviceName: string): boolean                         | Checks whether the user has the device access permissions.|
21| requestRight(deviceName: string): Promise<boolean>       | Requests the device access permissions for the application. This API uses a promise to return the result.                       |
22| removeRight(deviceName: string): boolean | Revokes the device access permissions of the application.|
23| connectDevice(device: USBDevice): Readonly<USBDevicePipe> | Connects to the USB device based on the device information returned by `getDevices()`.               |
24| getDevices(): Array<Readonly<USBDevice>>          | Obtains the list of USB devices connected to the host. If no device is connected, an empty list is returned.                                           |
25| setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number | Sets the USB device configuration.                                            |
26| setInterface(pipe: USBDevicePipe, iface: USBInterface): number   | Sets a USB interface.                                            |
27| claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number | Claims a USB interface.                                                  |
28| bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> | Performs bulk transfer.                                                  |
29| closePipe(pipe: USBDevicePipe): number                         | Closes a USB device pipe.                                      |
30| releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number | Releases a USB interface.                                                  |
31| getFileDescriptor(pipe: USBDevicePipe): number                 | Obtains the file descriptor.                                              |
32| getRawDescriptor(pipe: USBDevicePipe): Uint8Array              | Obtains the raw USB descriptor.                                       |
33| usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout?: number): Promise<number> | Performs control transfer.                                                  |
34
35
36## How to Develop
37
38You can set a USB device as a host to connect to a device for data transfer. The development procedure is as follows:
39
40
411. Obtain the USB device list.
42
43   ```ts
44   // Import the USB API package.
45   import { usbManager } from '@kit.BasicServicesKit';
46   // Obtain the USB device list.
47   let deviceList : Array<usbManager.USBDevice> = usbManager.getDevices();
48   /*
49   Example deviceList structure:
50   [
51     {
52       name: "1-1",
53       serial: "",
54       manufacturerName: "",
55       productName: "",
56       version: "",
57       vendorId: 7531,
58       productId: 2,
59       clazz: 9,
60       subClass: 0,
61       protocol: 1,
62       devAddress: 1,
63       busNum: 1,
64       configs: [
65         {
66           id: 1,
67           attributes: 224,
68           isRemoteWakeup: true,
69           isSelfPowered: true,
70           maxPower: 0,
71           name: "1-1",
72           interfaces: [
73             {
74               id: 0,
75               protocol: 0,
76               clazz: 9,
77               subClass: 0,
78               alternateSetting: 0,
79               name: "1-1",
80               endpoints: [
81                 {
82                   address: 129,
83                   attributes: 3,
84                   interval: 12,
85                   maxPacketSize: 4,
86                   direction: 128,
87                   number: 1,
88                   type: 3,
89                   interfaceId: 0,
90                 }
91               ]
92             }
93           ]
94         }
95       ]
96     }
97   ]
98   */
99   ```
100
1012. Obtain the device operation permissions.
102
103   ```ts
104   import { usbManager } from '@kit.BasicServicesKit';
105   import { BusinessError } from '@kit.BasicServicesKit';
106
107   let deviceName : string = deviceList[0].name;
108   // Request the permissions to operate a specified device.
109   usbManager.requestRight(deviceName).then((hasRight : boolean) => {
110     console.info("usb device request right result: " + hasRight);
111   }).catch((error : BusinessError)=> {
112     console.info("usb device request right failed : " + error);
113   });
114   ```
115
1163. Open the device.
117
118   ```ts
119   // Open the device, and obtain the USB device pipe for data transfer.
120   let pipe : usbManager.USBDevicePipe = usbManager.connectDevice(deviceList[0]);
121   let interface1 : usbManager.USBInterface = deviceList[0].configs[0].interfaces[0];
122   /*
123    Claim the corresponding interface from **deviceList**.
124   interface1 must be one present in the device configuration.
125   */
126   usbManager.claimInterface(pipe, interface1, true);
127   ```
128
1294. Perform data transfer. Currently, only bulk transfer and control transfer are supported.
130
131    - Bulk transfer
132
133    ```ts
134    import { usbManager } from '@kit.BasicServicesKit';
135    import { BusinessError } from '@kit.BasicServicesKit';
136    /*
137      Read data. Select the corresponding RX endpoint from deviceList for data transfer.
138    (endpoint.direction == 0x80); dataUint8Array indicates the data to read. The data type is Uint8Array.
139    */
140    let inEndpoint : usbManager.USBEndpoint = interface1.endpoints[2];
141    let outEndpoint : usbManager.USBEndpoint = interface1.endpoints[1];
142    let dataUint8Array : Uint8Array = new Uint8Array(1024);
143    usbManager.bulkTransfer(pipe, inEndpoint, dataUint8Array, 15000).then((dataLength : number) => {
144    if (dataLength >= 0) {
145      console.info("usb readData result Length : " + dataLength);
146    } else {
147      console.info("usb readData failed : " + dataLength);
148    }
149    }).catch((error : BusinessError) => {
150    console.info("usb readData error : " + JSON.stringify(error));
151    });
152    // Send data. Select the corresponding TX endpoint from deviceList for data transfer. (endpoint.direction == 0)
153    usbManager.bulkTransfer(pipe, outEndpoint, dataUint8Array, 15000).then((dataLength : number) => {
154      if (dataLength >= 0) {
155        console.info("usb writeData result write length : " + dataLength);
156      } else {
157        console.info("writeData failed");
158      }
159    }).catch((error : BusinessError) => {
160      console.info("usb writeData error : " + JSON.stringify(error));
161    });
162    ```
163
164    - Control transfer
165
166    ```ts
167    import { usbManager } from '@kit.BasicServicesKit';
168    import { BusinessError } from '@kit.BasicServicesKit';
169
170    /*
171      Construct control transfer parameters.
172    */
173    let param: usbManager.USBDeviceRequestParams = {
174      bmRequestType: 0x80,    // 0x80 indicates a standard request for data transfer from the device to the host.
175      bRequest: 0x06,    // 0x06 indicates a request for the descriptor.
176      wValue:0x01 << 8 | 0,    // The value is of two bytes. The high byte indicates the descriptor type. Here, 0x01 indicates the device descriptor. The low byte indicates the descriptor index. The value is set to 0 because it is not involved for the device descriptor.
177      wIndex: 0,    // Descriptor index. The value can be 0.
178      wLength: 18,    // Descriptor length. The value 18 indicates that a maximum of 1024 characters are supported.
179      data: new Uint8Array(18)
180    };
181
182    usbManager.usbControlTransfer(pipe, param).then((ret: number) => {
183    console.info("usbControlTransfer = ${ret}");
184    })
185    ```
186
1875. Release the USB interface, and close the USB device.
188
189   ```ts
190   usbManager.releaseInterface(pipe, interface1);
191   usbManager.closePipe(pipe);
192   ```
193