1# USB Service Development 2 3## When to Use 4 5In 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. 6 7## APIs 8 9The USB service provides the following functions: query of USB device list, bulk data transfer, control transfer, and access permission management. 10 11The following table lists the USB APIs currently available. For details, see the [API Reference](../reference/apis/js-apis-usbManager.md). 12 13**Table 1** Open USB APIs 14 15| API | Description | 16| ------------------------------------------------------------ | ------------------------------------------------------------ | 17| hasRight(deviceName: string): boolean | Checks whether the user has the device access permissions. | 18| requestRight(deviceName: string): Promise\<boolean> | Requests the temporary permission for a given application to access the USB device. This API uses a promise to return the result. | 19| connectDevice(device: USBDevice): Readonly\<USBDevicePipe> | Connects to the USB device based on the device list returned by `getDevices()`. | 20| getDevices(): Array<Readonly\<USBDevice>> | Obtains the list of USB devices connected to the USB host. If no USB device is connected, an empty list is returned. | 21| setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number | Sets the USB device configuration. | 22| setInterface(pipe: USBDevicePipe, iface: USBInterface): number | Sets a USB interface. | 23| claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number | Claims a USB interface. | 24| bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise\<number> | Performs bulk transfer. | 25| closePipe(pipe: USBDevicePipe): number | Closes a USB device pipe. | 26| releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number | Releases a USB interface. | 27| getFileDescriptor(pipe: USBDevicePipe): number | Obtains the file descriptor. | 28| getRawDescriptor(pipe: USBDevicePipe): Uint8Array | Obtains the raw USB descriptor. | 29| controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise\<number> | Performs control transfer. | 30 31## How to Develop 32 33You can set a USB device as the USB host to connect to other USB devices for data transfer. The development procedure is as follows: 34 351. Obtain the USB device list. 36 37 ```js 38 // Import the USB API package. 39 import usb from '@ohos.usbManager'; 40 // Obtain the USB device list. 41 let deviceList = usb.getDevices(); 42 /* 43 Example deviceList structure 44 [ 45 { 46 name: "1-1", 47 serial: "", 48 manufacturerName: "", 49 productName: "", 50 version: "", 51 vendorId: 7531, 52 productId: 2, 53 clazz: 9, 54 subClass: 0, 55 protocol: 1, 56 devAddress: 1, 57 busNum: 1, 58 configs: [ 59 { 60 id: 1, 61 attributes: 224, 62 isRemoteWakeup: true, 63 isSelfPowered: true, 64 maxPower: 0, 65 name: "1-1", 66 interfaces: [ 67 { 68 id: 0, 69 protocol: 0, 70 clazz: 9, 71 subClass: 0, 72 alternateSetting: 0, 73 name: "1-1", 74 endpoints: [ 75 { 76 address: 129, 77 attributes: 3, 78 interval: 12, 79 maxPacketSize: 4, 80 direction: 128, 81 number: 1, 82 type: 3, 83 interfaceId: 0, 84 } 85 ] 86 } 87 ] 88 } 89 ] 90 } 91 ] 92 */ 93 ``` 94 952. Obtain the device operation permissions. 96 97 ```js 98 let deviceName = deviceList[0].name; 99 // Request the permissions to operate a specified device. 100 usb.requestRight(deviceName).then(hasRight => { 101 console.info("usb device request right result: " + hasRight); 102 }).catch(error => { 103 console.info("usb device request right failed : " + error); 104 }); 105 ``` 106 1073. Open the device. 108 109 ```js 110 // Open the device, and obtain the USB device pipe for data transfer. 111 let interface1 = deviceList[0].configs[0].interfaces[0]; 112 /* 113 Claim the corresponding interface from deviceList. 114 interface1 must be one present in the device configuration. 115 */ 116 usb.claimInterface(pipe, interface1, true); 117 ``` 118 1194. Perform data transfer. 120 121 ```js 122 /* 123 Read data. Select the corresponding RX endpoint from deviceList for data transfer. 124 (endpoint.direction == 0x80); dataUint8Array indicates the data to read. The data type is Uint8Array. 125 */ 126 let inEndpoint = interface1.endpoints[2]; 127 let outEndpoint = interface1.endpoints[1]; 128 let dataUint8Array = new Uint8Array(1024); 129 usb.bulkTransfer(pipe, inEndpoint, dataUint8Array, 15000).then(dataLength => { 130 if (dataLength >= 0) { 131 console.info("usb readData result Length : " + dataLength); 132 } else { 133 console.info("usb readData failed : " + dataLength); 134 } 135 }).catch(error => { 136 console.info("usb readData error : " + JSON.stringify(error)); 137 }); 138 // Send data. Select the corresponding TX endpoint from deviceList for data transfer. (endpoint.direction == 0) 139 usb.bulkTransfer(pipe, outEndpoint, dataUint8Array, 15000).then(dataLength => { 140 if (dataLength >= 0) { 141 console.info("usb writeData result write length : " + dataLength); 142 } else { 143 console.info("writeData failed"); 144 } 145 }).catch(error => { 146 console.info("usb writeData error : " + JSON.stringify(error)); 147 }); 148 ``` 149 1505. Release the USB interface, and close the USB device. 151 152 ```js 153 usb.releaseInterface(pipe, interface); 154 usb.closePipe(pipe); 155 ```