Declares the USB Serial DDK APIs used by the host to access the serial port device. It provides the capabilities of reading data from and writing data to serial ports and configuring parameters. This API is applicable to scenarios where serial port devices need to be accessed through the USB port, such as industrial control and embedded device communication.
File to include: <usb_serial/usb_serial_api.h>
Library: libusb_serial_ndk.z.so
System capability: SystemCapability.Driver.UsbSerial.Extension
Since: 18
Related module: USBSerialDDK
| Name | Description |
|---|---|
| int32_t OH_UsbSerial_Init(void) | Initializes the USB Serial DDK. This API must be called before calling any other USB Serial DDK APIs. It establishes a communication connection with the DDK service and loads the necessary driver resources. Call OH_UsbSerial_Release() after use to release the DDK and avoid resource leaks. |
| int32_t OH_UsbSerial_Release(void) | Releases the USB Serial DDK. This API must be used in pairs with OH_UsbSerial_Init(). After release, no other USB Serial DDK APIs can be called. |
| int32_t OH_UsbSerial_Open(uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_Device **dev) | Opens a USB serial port device by deviceId and interfaceIndex. This API establishes a connection with the specified USB serial port device and returns a device handle for subsequent operations. Call OH_UsbSerial_Close() after use to close the device; otherwise, the device resources may not be released correctly. |
| int32_t OH_UsbSerial_Close(UsbSerial_Device **dev) | Closes a USB serial port device. This API releases the resources occupied by the device and must be used in pairs with OH_UsbSerial_Open(). |
| int32_t 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. |
| int32_t 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. |
| int32_t OH_UsbSerial_SetBaudRate(UsbSerial_Device *dev, uint32_t baudRate) | Sets the baud rate of a USB serial port device. If the parameters of the USB serial port device are the default values (8 data bits, 1 stop bit, and no parity check for data transmission), only this API needs to be called to set the baud rate. |
| int32_t OH_UsbSerial_SetParams(UsbSerial_Device *dev, UsbSerial_Params *params) | Sets the parameters of the USB serial port device. If the parameters of the USB serial port device are not set to the default values (the data bit is 8, the stop bit is 1, and parity is disabled for data transfer), you only need to call this API to set the related parameters. |
| int32_t OH_UsbSerial_SetTimeout(UsbSerial_Device *dev, int timeout) | Sets the timeout interval (ms) for reading data reported by a USB serial port device. If this function is not called, the timeout value is 0 by default, indicating that data is returned immediately regardless of whether data is read. If you need to wait for a certain period of time or data must be read, call this API to set the timeout interval. |
| int32_t OH_UsbSerial_SetFlowControl(UsbSerial_Device *dev, UsbSerial_FlowControl flowControl) | Sets the flow control parameters. Flow control in USB serial port device communication is used to manage the rate of data transmission, ensuring that the sender does not send more data than the receiver can process. If the USB serial port device implements flow control, this API must be called. If this API is not called, no flow control is used by default. |
| int32_t OH_UsbSerial_Flush(UsbSerial_Device *dev) | Clears the input and output buffers (and waits for the data in the output buffer to be sent). When sending data to a USB serial port device, a large amount of data may be buffered in the kernel waiting to be sent. If the application closes the device or exits without waiting for this data to be actually sent, some data may be lost. Calling this API ensures that all data is sent before subsequent operations continue. |
| int32_t OH_UsbSerial_FlushInput(UsbSerial_Device *dev) | Clears the input buffer, and the data in the buffer is cleared immediately. During the communication process with a USB serial port device, especially in the debugging phase, out-of-order data packets or other abnormal conditions may occur. This API can be used to clear the abnormal state on the receiving end and restore normal communication. This API does not affect the data pending transmission in the output buffer. |
| int32_t OH_UsbSerial_FlushOutput(UsbSerial_Device *dev) | Clears the output buffer, and the data in the buffer is cleared immediately. During the communication process with a USB serial port device, especially in the debugging phase, out-of-order data packets or other abnormal conditions may occur. This API can be used to clear the abnormal state on the sending end and restore normal communication. This API does not affect the received data in the input buffer. |
int32_t OH_UsbSerial_Init(void)
Description
Initializes the USB Serial DDK. This API must be called before calling any other USB Serial DDK APIs. It establishes a communication connection with the DDK service and loads the necessary driver resources. Call OH_UsbSerial_Release() after use to release the DDK and avoid resource leaks.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS Returns this code if the API is called successfully. USB_SERIAL_DDK_NO_PERM Returns this code if permission verification fails. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INIT_ERROR Returns this code if the DDK fails to be initialized. |
int32_t OH_UsbSerial_Release(void)
Description
Releases the USB Serial DDK. This API must be used in pairs with OH_UsbSerial_Init(). After release, no other USB Serial DDK APIs can be called.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized or has been released. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the device status. |
int32_t OH_UsbSerial_Open(uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_Device **dev)
Description
Opens a USB serial port device by deviceId and interfaceIndex. This API establishes a connection with the specified USB serial port device and returns a device handle for subsequent operations. Call OH_UsbSerial_Close() after use to close the device; otherwise, the device resources may not be released correctly.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| uint64_t deviceId | Device ID, which represents the device to operate. It can be obtained by calling OH_Usb_GetDevices. |
| uint8_t interfaceIndex | Interface index, which corresponds to bInterfaceNumber in the USB protocol. |
| UsbSerial_Device **dev | Device handle, which is an output parameter used to return the opened USB serial port device handle. Call OH_UsbSerial_Close() to release it after use. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has correctly obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: dev is a null pointer or *dev is a null pointer. Check the validity of the parameters. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_MEMORY_ERROR Insufficient memory. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_DEVICE_NOT_FOUND The device or interface is not found. |
int32_t OH_UsbSerial_Close(UsbSerial_Device **dev)
Description
Closes a USB serial port device. This API releases the resources occupied by the device and must be used in pairs with OH_UsbSerial_Open().
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device **dev | Device handle, which is an input/output parameter. The pointer is set to null after the device is closed. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has correctly obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: dev is a null pointer or *dev is a null pointer. Check the validity of the parameters. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened correctly. |
int32_t OH_UsbSerial_Read(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesRead)
Description
Reads data from the USB serial port device to the buffer.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
| uint8_t *buff | Buffer for reading data from the USB serial port device. It is allocated by the caller, with a size not less than bufferSize. |
| uint32_t bufferSize | Buffer size. |
| uint32_t *bytesRead | Number of bytes actually read. In blocking mode, the function returns only after the number of bytes actually read equals bufferSize. If a timeout is set, the return value may be less than bufferSize. For details, see OH_UsbSerial_SetTimeout(). |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: 1. dev is a null pointer; 2. buff is a null pointer; 3. bufferSize is 0; 4. bytesRead is a null pointer. Check the validity of the parameters. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_MEMORY_ERROR The buff address is invalid. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened properly. |
int32_t OH_UsbSerial_Write(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesWritten)
Description
Writes the data in the buffer to the USB serial port device.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
| uint8_t *buff | Buffer for the data to be written to the USB serial port device. It must be allocated by the caller and its capacity must not be less than bufferSize. |
| uint32_t bufferSize | Buffer size. |
| uint32_t *bytesWritten | Number of bytes actually written. It is valid only when the API returns success, and it may be less than bufferSize. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has correctly obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: 1. dev is a null pointer; 2. buff is a null pointer; 3. bufferSize is 0; 4. bytesWritten is a null pointer. Check the validity of the parameters. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service fails to execute. Check the parameters and device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurs in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened properly. |
int32_t OH_UsbSerial_SetBaudRate(UsbSerial_Device *dev, uint32_t baudRate)
Description
Sets the baud rate for a USB serial port device. If the parameters of the USB serial port device are set to the default values (the data bit is 8, the stop bit is 1, and parity is disabled for data transfer), you only need to call this API to set the baud rate.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
| uint32_t baudRate | Baud rate of the USB serial port device, in baud. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: dev is a null pointer. Check the validity of the parameter. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened properly. |
int32_t OH_UsbSerial_SetParams(UsbSerial_Device *dev, UsbSerial_Params *params)
Description
Sets the parameters of the USB serial port device. If the parameters of the USB serial port device are not set to the default values (the data bit is 8, the stop bit is 1, and parity is disabled for data transfer), you only need to call this API to set related parameters.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
| UsbSerial_Params *params | USB serial port device parameters. For details, see UsbSerial_Params. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: 1. dev is a null pointer; 2. params is a null pointer. Check the validity of the parameters. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened properly. |
int32_t OH_UsbSerial_SetTimeout(UsbSerial_Device *dev, int timeout)
Description
Sets the timeout interval (ms) for reading data reported by a USB serial port device. If this function is not called, the timeout value is 0 by default, indicating that data is returned immediately regardless of whether data is read. If you need to wait for a certain period of time or data must be read, call this API to set the timeout interval.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
| int timeout | Timeout for reading data from the USB serial port device. When the value is in the range (0, 25500], it indicates a time value in milliseconds, which is rounded to the nearest 100 milliseconds as the actual timeout. For example, when 12321 is input, the actual timeout is 12300. When the value is 0, data is returned immediately without waiting. When the value is -1, data is read in blocking mode, that is, the read operation returns only after data of the specified length is read. For details, see OH_UsbSerial_Read(). It is recommended to use 0 in polling scenarios, (0, 25500] in scenarios requiring timeout control, and -1 in scenarios where complete data must be read. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has correctly obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: 1. dev is a null pointer; 2. timeout < -1 or timeout > 25500. Check the parameter validity and the timeout. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and the device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device has been opened properly. |
int32_t OH_UsbSerial_SetFlowControl(UsbSerial_Device *dev, UsbSerial_FlowControl flowControl)
Description
Sets the flow control parameters. Flow control in USB serial port device communication is used to manage the rate of data transmission, ensuring that the sender does not send more data than the receiver can process. If the USB serial port device implements flow control, this API must be called. If this API is not called, no flow control is used by default.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
| UsbSerial_FlowControl flowControl | Flow control mode. For details, see UsbSerial_FlowControl. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: dev is a null pointer. Check the validity of the parameter. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened properly. |
int32_t OH_UsbSerial_Flush(UsbSerial_Device *dev)
Description
Clears the input and output buffers (and waits for the data in the output buffer to be sent). When sending data to a USB serial port device, a large amount of data may be buffered in the kernel waiting to be sent. If the application closes the device or exits without waiting for this data to be actually sent, some data may be lost. Calling this API ensures that all data is sent before subsequent operations continue.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: dev is a null pointer. Check the validity of the parameter. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened properly. |
int32_t OH_UsbSerial_FlushInput(UsbSerial_Device *dev)
Description
Clears the input buffer, and the data in the buffer is cleared immediately. During the communication process with a USB serial port device, especially in the debugging phase, out-of-order data packets or other abnormal conditions may occur. This API can be used to clear the abnormal state on the receiving end and restore normal communication. This API does not affect the data pending transmission in the output buffer.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: dev is a null pointer. Check the validity of the parameter. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened properly. |
int32_t OH_UsbSerial_FlushOutput(UsbSerial_Device *dev)
Description
Clears the output buffer, and the data in the buffer is cleared immediately. During the communication process with a USB serial port device, especially in the debugging phase, out-of-order data packets or other abnormal conditions may occur. This API can be used to clear the abnormal state on the sending end and restore normal communication. This API does not affect the received data in the input buffer.
Required permissions: ohos.permission.ACCESS_DDK_USB_SERIAL
Since: 18
Parameters
| Name | Description |
|---|---|
| UsbSerial_Device *dev | Device handle, obtained by calling OH_UsbSerial_Open() to open the device. |
Returns
| Type | Description |
|---|---|
| int32_t | USB_SERIAL_DDK_SUCCESS The API is called successfully. USB_SERIAL_DDK_NO_PERM Permission verification failed. Check whether the application has obtained the ohos.permission.ACCESS_DDK_USB_SERIAL permission. USB_SERIAL_DDK_INVALID_PARAMETER Parameter check failed. Possible causes: dev is a null pointer. Check the validity of the parameter. USB_SERIAL_DDK_INIT_ERROR The DDK is not initialized. Call OH_UsbSerial_Init() to initialize the DDK first. USB_SERIAL_DDK_SERVICE_ERROR The DDK service failed to execute. Check the parameters and device status. USB_SERIAL_DDK_IO_ERROR An I/O error occurred in the DDK. Check the device specifications and parameters. USB_SERIAL_DDK_INVALID_OPERATION Invalid operation. Ensure that the device is opened properly. |