• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# USB Bulk Transfer
2
3## When to Use
4
5Bulk transfer is used to transfer and receive a large amount of data without bandwidth or interval requirements, for example, file or image transfer. Devices such as printers and scanners support this type of transfer.
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 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| bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number>  | Performs bulk 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 **bulkTransfer** API to transfer data. The following steps describe how to implement a bulk transfer:
45
461. Import modules.
47
48   ```ts
49   // Import the usbManager module.
50   import { usbManager } from '@kit.BasicServicesKit';
51   import { BusinessError } from '@kit.BasicServicesKit';
52   ```
53
542. Obtain the USB device list.
55
56    ```ts
57   // Obtain the USB device list.
58   let deviceList : Array<usbManager.USBDevice> = usbManager.getDevices();
59   /*
60   Example deviceList structure:
61   [
62     {
63       name: "1-1",
64       serial: "",
65       manufacturerName: "",
66       productName: "",
67       version: "",
68       vendorId: 7531,
69       productId: 2,
70       clazz: 9,
71       subClass: 0,
72       protocol: 1,
73       devAddress: 1,
74       busNum: 1,
75       configs: [
76         {
77           id: 1,
78           attributes: 224,
79           isRemoteWakeup: true,
80           isSelfPowered: true,
81           maxPower: 0,
82           name: "1-1",
83           interfaces: [
84             {
85               id: 0,
86               protocol: 0,
87               clazz: 9,
88               subClass: 0,
89               alternateSetting: 0,
90               name: "1-1",
91               endpoints: [
92                 {
93                   address: 129,
94                   attributes: 3,
95                   interval: 12,
96                   maxPacketSize: 4,
97                   direction: 128,
98                   number: 1,
99                   type: 3,
100                   interfaceId: 0,
101                 }
102               ]
103             }
104           ]
105         }
106       ]
107     }
108   ]
109   */
110   ```
111
1123. Obtain the device operation permissions.
113
114   ```ts
115   let deviceName : string = deviceList[0].name;
116   // Request the permissions to operate a specified device.
117   usbManager.requestRight(deviceName).then((hasRight : boolean) => {
118     console.info("usb device request right result: " + hasRight);
119   }).catch((error : BusinessError)=> {
120     console.info("usb device request right failed : " + error);
121   });
122   ```
123
1244. Open the device.
125
126   ```ts
127   // Open the device, and obtain the USB device pipe for data transfer.
128   let pipe : usbManager.USBDevicePipe = usbManager.connectDevice(deviceList[0]);
129   let interface1 : usbManager.USBInterface = deviceList[0].configs[0].interfaces[0];
130   /*
131    Claim the corresponding interface from deviceList.
132   interface1 must be one present in the device configuration.
133   */
134   usbManager.claimInterface(pipe, interface1, true);
135   ```
136
1375. Perform data transfer.
138
139    ```ts
140    /*
141      Read data. Select the corresponding RX endpoint from deviceList for data transfer.
142    (endpoint.direction == 0x80); dataUint8Array indicates the data to read. The data type is Uint8Array.
143    */
144    let inEndpoint : usbManager.USBEndpoint = interface1.endpoints[2];
145    let outEndpoint : usbManager.USBEndpoint = interface1.endpoints[1];
146    let dataUint8Array : Uint8Array = new Uint8Array(1024);
147    usbManager.bulkTransfer(pipe, inEndpoint, dataUint8Array, 15000).then((dataLength : number) => {
148    if (dataLength >= 0) {
149      console.info("usb readData result Length : " + dataLength);
150    } else {
151      console.info("usb readData failed : " + dataLength);
152    }
153    }).catch((error : BusinessError) => {
154    console.info("usb readData error : " + JSON.stringify(error));
155    });
156    // Send data. Select the corresponding TX endpoint from deviceList for data transfer. (endpoint.direction == 0)
157    usbManager.bulkTransfer(pipe, outEndpoint, dataUint8Array, 15000).then((dataLength : number) => {
158      if (dataLength >= 0) {
159        console.info("usb writeData result write length : " + dataLength);
160      } else {
161        console.info("writeData failed");
162      }
163    }).catch((error : BusinessError) => {
164      console.info("usb writeData error : " + JSON.stringify(error));
165    });
166    ```
167
1686. Release the USB interface, and close the USB device pipe.
169
170   ```ts
171   usbManager.releaseInterface(pipe, interface1);
172   usbManager.closePipe(pipe);
173   ```
174