1# USB Serial DDK Development 2 3## Overview 4 5Non-standard serial port devices, such as temperature and humidity meters and special identity card readers, are used in industrial scenarios and on some legacy devices. If the system does not have a driver that adapts to the devices, the devices cannot be used after being connected. The USB Serial Driver Development Kit (DDK) is a toolset that helps you develop USB serial drivers at the application layer based on the user mode. The USB Serial DDK provides a series of APIs for the host to access devices, including APIs for enabling and disabling devices on the host and read/write data through serial ports. With these APIs, third-party peripheral devices can seamlessly integrate with the OpenHarmony ecosystem. 6 7### Basic Concepts 8 9Before developing the SCSI Peripheral DDK, you must understand the following basic concepts: 10 11- **USB serial port** 12 13 USB-to-Serial is an interface conversion technology that allows data communication with traditional serial ports (such as RS-232 and RS-485) over USB interfaces. This technology is usually implemented by using a dedicated hardware adapter or a specific built-in chip. 14 15- **AMS** 16 17 The Ability Manager Service (AMS) is a system service used to coordinate the running relationships of abilities and schedule the lifecycle of abilities. You can use it to start and disable **DriverExtensionAbility** during driver development. 18 19- **BMS** 20 21 The Bundle Manager Service (BMS) is responsible for application installation, uninstallation, and data management on OpenHarmony. 22 23- **DDK** 24 25 DDK is a tool package provided by OpenHarmony for developing drivers for non-standard USB serial port devices based on the peripheral framework. 26 27- **Non-standard peripherals** 28 29 Non-standard peripherals (also called custom peripherals or dedicated peripherals) are peripherals that do not comply with general standards or are customized for specific application scenarios. This type of device usually requires special software support or special interfaces to implement communication with the host system. 30 31- **Standard peripherals** 32 33 Standard peripherals refer to peripherals (such as USB keyboards and mouse devices) that comply with industry standards and specifications. Such devices typically have uniform interface protocols, physical dimensions, and electrical characteristics, so that they can be used interchangeably between different systems. 34 35### Implementation Principles 36 37A non-standard peripheral application obtains the USB serial port device ID by using the peripheral management service, and delivers the ID and the action to the USB serial port driver application through RPC. The USB serial port driver application can set the serial port attributes (such as the baud rate, data bit, and parity bit) and read the serial port data by calling the USB Serial DDK API. Then, the DDK API uses the HDI service to deliver instructions to the kernel driver, and the kernel driver uses instructions to communicate with the device. 38 39**Figure 1** Principles of invoking the USB Serial DDK 40 41 42 43### Constraints 44 45- The open APIs of USB Serial DDK can be used to develop drivers of non-standard USB peripherals that use USB serial ports. 46 47- The open APIs of USB Serial DDK can be used only within the **DriverExtensionAbility** lifecycle. 48 49- To use the open APIs of USB Serial DDK, you need to declare the matching ACL permissions in **module.json5**, for example, **ohos.permission.ACCESS_DDK_USB_SERIAL**. 50 51## Environment Setup 52 53Before you get started, make necessary preparations by following instructions in [Environment Preparation](environmental-preparation.md). 54 55## How to Develop 56 57### Available APIs 58 59| Name| Description| 60| -------- | -------- | 61| OH_UsbSerial_Init(void) | Initializes the USB Serial DDK.| 62| OH_UsbSerial_Release(void) | Releases the USB Serial DDK.| 63| OH_UsbSerial_Open(uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_Device **dev) | Opens the USB serial port device based on the specified **deviceId** and **interfaceIndex**. Call **OH_UsbSerial_Close ()** to close the device after use. Otherwise, memory leakage occurs.| 64| OH_UsbSerial_Close(UsbSerial_Device **dev) | Closes the USB serial port device after use. Otherwise, memory leakage occurs.| 65| OH_UsbSerial_Read(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesRead) | Reads data from the USB serial port device to the buffer.| 66| OH_UsbSerial_Write(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesWritten) | Writes the data in the buffer to the USB serial port device.| 67| OH_UsbSerial_SetBaudRate(UsbSerial_DeviceHandle *dev, uint32_t baudRate) | Sets the baud rate for a USB serial port device. Call this API if the data bit of the serial port is **8**, the stop bit is **1**, and parity check is not performed.| 68| OH_UsbSerial_SetParams(UsbSerial_Device *dev, UsbSerial_Params *params) | Sets the parameters of the USB serial port device, including the baud rate, data transfer bit, stop bit, and parity check.| 69| OH_UsbSerial_SetTimeout(UsbSerial_Device *dev, int timeout) | Sets the timeout interval for reading data reported by a USB serial port device. The default value is **0**.| 70| OH_UsbSerial_SetFlowControl(UsbSerial_Device *dev, UsbSerial_FlowControl flowControl) | Sets flow control parameters.| 71| OH_UsbSerial_Flush(UsbSerial_Device *dev) | Flushes the input and output buffers after the write operation is complete.| 72| OH_UsbSerial_FlushInput(UsbSerial_Device *dev) | Refreshes the input buffer. The data in the buffer is cleared immediately.| 73| OH_UsbSerial_FlushOutput(UsbSerial_Device *dev) | Refreshes the output buffer. The data in the buffer is cleared immediately.| 74 75For details about the APIs, see [USB Serial DDK](../../reference/apis-driverdevelopment-kit/_serial_ddk.md). 76 77### How to Develop 78 79To develop the USB serial port driver by using the USB Serial DDK, perform the following steps: 80 81**Adding Dynamic Link Libraries** 82 83Add the following libraries to **CMakeLists.txt**. 84```txt 85libusb_serial_ndk.z.so 86``` 87 88**Including Header Files** 89```c++ 90#include <serial/usb_serial_api.h> 91#include <serial/usb_serial_types.h> 92``` 93 941. Initialize the USB Serial DDK. 95 96 Use **OH_UsbSerial_Init** in **usb_serial_api.h** to initialize the USB Serial DDK. 97 98 ```c++ 99 // Initialize the USB Serial DDK. 100 OH_UsbSerial_Init(); 101 ``` 102 1032. Open the USB serial port device. 104 105 Use **OH_UsbSerial_Open** in **usb_serial_api.h** to enable the device. 106 107 ```c++ 108 UsbSerial_Device *dev = NULL; 109 uint64_t deviceId = 1688858450198529; 110 uint8_t interfaceIndex = 0; 111 // Open the USB serial port device specified by deviceId and interfaceIndex. 112 OH_UsbSerial_Open(deviceId, interfaceIndex, &dev); 113 ``` 114 1153. Sets the parameters of the USB serial port device. 116 117 Use **OH_UsbSerial_SetParams** in **usb_serial_api.h** to set the serial port parameters, or directly use **OH_UsbSerial_SetBaudRate** to set the baud rate, and use **OH_UsbSerial_SetTimeout** to set the timeout interval for reading data. 118 119 ```c++ 120 UsbSerial_Params params; 121 params.baudRate = 9600; 122 params.nDataBits = 8; 123 params.nStopBits = 1; 124 params.parity = 0; 125 // Set serial port parameters. 126 OH_UsbSerial_SetParams(dev, ¶ms); 127 128 // Set the baud rate. 129 uint32_t baudRate = 9600; 130 OH_UsbSerial_SetBaudRate(dev, baudRate); 131 132 // Set the timeout interval. 133 int timeout = 500; 134 OH_UsbSerial_SetTimeout(dev, timeout); 135 ``` 136 1374. Set flow control and flush the buffer. 138 139 Use **OH_UsbSerial_SetFlowControl** in **usb_serial_api.h** to set the flow control mode, use **OH_UsbSerial_Flush** to flush the buffer, use **OH_UsbSerial_FlushInput** to flush the input buffer, and use **OH_UsbSerial_FlushOutput** to flush the output buffer. 140 141 ```c++ 142 // Set flow control. 143 OH_UsbSerial_SetFlowControl(dev, USB_SERIAL_SOFTWARE_FLOW_CONTROL); 144 145 // Flush the buffer. 146 OH_UsbSerial_Flush(dev); 147 148 // Flush the input buffer. 149 OH_UsbSerial_FlushInput(dev); 150 151 // Flush the output buffer. 152 OH_UsbSerial_FlushOutput(dev); 153 ``` 1545. Write or read data to or from a USB serial port device. 155 156 Use **OH_UsbSerial_Write** in **usb_serial_api.h** to send data to the device, and use **OH_UsbSerial_Read** to read the data sent by the device. 157 158 ```c++ 159 uint32_t bytesWritten = 0; 160 // Command used by the test device to read data. The command varies depending on the device protocol. 161 uint8_t writeBuff[8] = {0x01, 0x03, 0x00, 0x00, 0x00, 0x01, 0x84, 0xA}; 162 // Send data over the connection. 163 OH_UsbSerial_Write(dev, writeBuff, sizeof(writeBuff), &bytesWritten); 164 165 // Callback invoked to receive data. 166 uint8_t readBuff[100]; 167 uint32_t bytesRead = 0; 168 OH_UsbSerial_Read(dev, readBuff, sizeof(readBuff), &bytesRead); 169 ``` 170 1716. Close the USB serial port device. 172 173 After all requests are processed and before the program exits, use **OH_UsbSerial_Close** in **usb_serial_api.h** to close the device. 174 ```c++ 175 // Close the device. 176 OH_UsbSerial_Close(&dev); 177 ``` 178 1797. Release the USB Serial DDK. 180 181 After the USB serial port device is closed, use **OH_UsbSerial_Release** in **usb_serial_api.h** to release the USB Serial DDK. 182 183 ```c++ 184 // Release the USB Serial DDK. 185 OH_UsbSerial_Release(); 186 ``` 187 188### Debugging and Verification 189 190Upon completion of driver application development, you can install the application on the OpenHarmony device. The test procedure is as follows: 191 1921. Click the driver application on the device. The application is started on the device. 1932. Click the set button to set serial port attributes such as the baud rate. 1943. Click the data read button to read the data of the serial port device. 195
