1# USB Control Transfer 2 3## When to Use 4 5The control transfer is used to obtain and set the device status, and control the device attribute status. You can determine whether the control transfer can read or write data based on the endpoint types supported by the device. 6 7## Preparing the Environment 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 [Switching to Full SDK](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 36| API | Description | 37| ------------------------------------------------------------ |--------| 38| usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout?: number): Promise<number> | Performs control transfer. | 39 40For details about the APIs of device management and transfer modes, see [@ohos.usbManager (USB Manager)](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md). 41 42### Development Procedure 43 44Connect a host to a device and use the **usbControlTransfer** API to transfer data. The following steps describe how to implement a control transfer: 45 46 471. Import modules. 48 49 ```ts 50 // Import the usbManager module. 51 import { usbManager } from '@kit.BasicServicesKit'; 52 import { BusinessError } from '@kit.BasicServicesKit'; 53 ``` 54 552. Obtain the USB device list. 56 57 ```ts 58 // Obtain the USB device list. 59 let deviceList : Array<usbManager.USBDevice> = usbManager.getDevices(); 60 /* 61 Example deviceList structure: 62 [ 63 { 64 name: "1-1", 65 serial: "", 66 manufacturerName: "", 67 productName: "", 68 version: "", 69 vendorId: 7531, 70 productId: 2, 71 clazz: 9, 72 subClass: 0, 73 protocol: 1, 74 devAddress: 1, 75 busNum: 1, 76 configs: [ 77 { 78 id: 1, 79 attributes: 224, 80 isRemoteWakeup: true, 81 isSelfPowered: true, 82 maxPower: 0, 83 name: "1-1", 84 interfaces: [ 85 { 86 id: 0, 87 protocol: 0, 88 clazz: 9, 89 subClass: 0, 90 alternateSetting: 0, 91 name: "1-1", 92 endpoints: [ 93 { 94 address: 129, 95 attributes: 3, 96 interval: 12, 97 maxPacketSize: 4, 98 direction: 128, 99 number: 1, 100 type: 3, 101 interfaceId: 0, 102 } 103 ] 104 } 105 ] 106 } 107 ] 108 } 109 ] 110 */ 111 ``` 112 1133. Obtain the device operation permissions. 114 115 ```ts 116 let deviceName : string = deviceList[0].name; 117 // Request the permissions to operate a specified device. 118 usbManager.requestRight(deviceName).then((hasRight : boolean) => { 119 console.info("usb device request right result: " + hasRight); 120 }).catch((error : BusinessError)=> { 121 console.info("usb device request right failed : " + error); 122 }); 123 ``` 124 1254. Open the device. 126 127 ```ts 128 // Open the device, and obtain the USB device pipe for data transfer. 129 let pipe : usbManager.USBDevicePipe = usbManager.connectDevice(deviceList[0]); 130 let interface1 : usbManager.USBInterface = deviceList[0].configs[0].interfaces[0]; 131 132 /* 133 Claim the corresponding interface from deviceList. 134 interface1 must be one present in the device configuration. 135 */ 136 usbManager.claimInterface(pipe, interface1, true); 137 ``` 138 1395. Perform data transfer. 140 141 ```ts 142 /* 143 Construct control transfer parameters. 144 */ 145 let param: usbManager.USBDeviceRequestParams = { 146 bmRequestType: 0x80, // 0x80 indicates a standard request for data transfer from the device to the host. 147 bRequest: 0x06, // 0x06 indicates a request for the descriptor. 148 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. 149 wIndex: 0, // Descriptor index. The value can be 0. 150 wLength: 18, // Descriptor length. The value 18 indicates the length of a device descriptor. A maximum of 1024 characters are supported. 151 data: new Uint8Array(18) 152 }; 153 154 usbManager.usbControlTransfer(pipe, param).then((ret: number) => { 155 console.info("usbControlTransfer = ${ret}"); 156 }) 157 ``` 158 1596. Release the USB interface, and close the USB device pipe. 160 161 ```ts 162 usbManager.releaseInterface(pipe, interface1); 163 usbManager.closePipe(pipe); 164 ``` 165