# UART Usage Guidelines - [How to Use](#section47784125013) - [Obtaining a UART Device Handle](#section146445153110) - [Setting the UART Baud Rate](#section1862705516339) - [Obtaining the UART Baud Rate](#section1263651563414) - [Setting the UART Device Attributes](#section1770091483814) - [Obtaining UART Device Attributes](#section117543316384) - [Setting the UART Transmission Mode](#section187233112369) - [Writing Data of a Specified Length into a UART Device](#section82416423368) - [Reading Data of a Specified Length from a UART Device](#section192177171373) - [Destroying the UART Device Handle](#section63131236354) ## How to Use [Figure 1](#fig1852173020185) shows the process of using a UART device. **Figure 1** Process of using a UART device ![](figures/en-us_image_0000001054006983.png) ## Obtaining a UART Device Handle Before performing UART communication, call **UartOpen** to obtain a UART device handle. This function returns the pointer to the UART device handle with a specified port number. DevHandle UartOpen\(uint32\_t port\); **Table 1** Description of **UartOpen**

Parameter	Description
port	UART port number.
Return Value	Description
NULL	Failed to obtain the UART device handle.
Device handle	Pointer to the UART device handle.

The following example shows how to obtain a UART device handle based on the assumption that the UART port number is **3**: ``` DevHandle handle = NULL; /* The UART device handle */ uint32_t port = 3; /* UART port number */ handle = UartOpen(port); if (handle == NULL) { HDF_LOGE("UartOpen: failed!\n"); return; } ``` ## Setting the UART Baud Rate After obtaining the UART device handle, set the UART baud rate by calling the following function: int32\_t UartSetBaud\(DevHandle handle, uint32\_t baudRate\); **Table 2** Description of **UartSetBaud**

Parameter	Description
handle	Pointer to the UART device handle.
baudRate	Baud rate of the UART to set.
Return Value	Description
0	Succeeded in setting the UART baud rate.
Negative value	Failed to set the UART baud rate.

The following example shows how to set the UART baud rate to **9600**: ``` int32_t ret; /* Set the UART baud rate to 9600. */ ret = UartSetBaud(handle, 9600); if (ret != 0) { HDF_LOGE("UartSetBaud: failed, ret %d\n", ret); } ``` ## Obtaining the UART Baud Rate After setting the UART baud rate, obtain the current baud rate by calling the following function: int32\_t UartGetBaud\(DevHandle handle, uint32\_t \*baudRate\); **Table 3** Description of **UartGetBaud**

Parameter	Description
handle	Pointer to the UART device handle.
baudRate	Pointer to the UART baud rate.
Return Value	Description
0	Succeeded in obtaining the UART baud rate.
Negative value	Failed to obtain the UART baud rate.

The following example shows how to obtain the UART baud rate: ``` int32_t ret; uint32_t baudRate; /* Obtain the UART baud rate. */ ret = UartGetBaud(handle, &baudRate); if (ret != 0) { HDF_LOGE("UartGetBaud: failed, ret %d\n", ret); } ``` ## Setting the UART Device Attributes Before performing UART communication, set the UART device attributes by calling the following function: int32\_t UartSetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); **Table 4** Description of **UartSetAttribute**

Parameter	Description
handle	Pointer to the UART device handle.
attribute	Pointer to the UART device attributes to set.
Return Value	Description
0	Succeeded in setting the UART device attributes.
Negative value	Failed to set the UART device attributes.

The following example shows how to set the UART device attributes: ``` int32_t ret; struct UartAttribute attribute; attribute.dataBits = UART_ATTR_DATABIT_7; /* Set the number of data bits to 7. */ attribute.parity = UART_ATTR_PARITY_NONE; /* Set the parity bit to no parity. */ attribute.stopBits = UART_ATTR_STOPBIT_1; /* Set the stop bit to 1. */ attribute.rts = UART_ATTR_RTS_DIS; /* Disable the RTS signal. */ attribute.cts = UART_ATTR_CTS_DIS; /* Disable the CTS signal. */ attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; /* Enable RX FIFO. */ attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; /* Enable TX FIFO. */ /* Set the UART device attributes. */ ret = UartSetAttribute(handle, &attribute); if (ret != 0) { HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret); } ``` ## Obtaining UART Device Attributes After setting the UART device attributes, obtain the current device attributes by calling the following function: int32\_t UartGetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); **Table 5** Description of **UartGetAttribute**

Parameter	Description
handle	Pointer to the UART device handle.
attribute	Pointer to the UART device attributes.
Return Value	Description
0	Succeeded in obtaining the UART device attributes.
Negative value	Failed to obtain the UART device attributes.

The following example shows how to obtain the UART device attributes: ``` int32_t ret; struct UartAttribute attribute; /* Obtain the UART attributes. */ ret = UartGetAttribute(handle, &attribute); if (ret != 0) { HDF_LOGE("UartGetAttribute: failed, ret %d\n", ret); } ``` ## Setting the UART Transmission Mode Before performing UART communication, set the UART transmission mode by calling the following function: int32\_t UartSetTransMode\(DevHandle handle, enum UartTransMode mode\); **Table 6** Description of **UartSetTransMode**

Parameter	Description
handle	Pointer to the UART device handle.
mode	UART transmission mode to set.
Return Value	Description
0	Succeeded in setting the UART transmission mode.
Negative value	Failed to set the UART transmission mode.

The following example shows how to set the transmission mode to **UART\_MODE\_RD\_BLOCK**: ``` int32_t ret; /* Set the UART transmission mode. */ ret = UartSetTransMode(handle, UART_MODE_RD_BLOCK); if (ret != 0) { HDF_LOGE("UartSetTransMode: failed, ret %d\n", ret); } ``` ## Writing Data of a Specified Length into a UART Device To write data into a UART device, call the following function: int32\_t UartWrite\(DevHandle handle, uint8\_t \*data, uint32\_t size\); **Table 7** Description of **UartWrite**

Parameter	Description
handle	Pointer to the UART device handle.
data	Pointer to the data to write.
size	Length of the data to write.
Return Value	Description
0	Succeeded in writing data into the UART device.
Negative value	Failed to write data into the UART device.

The following example shows how to write data of a specified length into the UART device: ``` int32_t ret; uint8_t wbuff[5] = {1, 2, 3, 4, 5}; /* Write 5-byte data into the UART device. */ ret = UartWrite(handle, wbuff, 5); if (ret != 0) { HDF_LOGE("UartWrite: failed, ret %d\n", ret); } ``` ## Reading Data of a Specified Length from a UART Device To read data from a UART device, call the following function: int32\_t UartRead\(DevHandle handle, uint8\_t \*data, uint32\_t size\); **Table 8** Description of **UartRead**

Parameter	Description
handle	Pointer to the UART device handle.
data	Pointer to the buffer for receiving the data.
size	Length of the data to read.
Return Value	Description
Non-negative value	Length of the data read from the UART device.
Negative value	Failed to read data from the UART device.

The following example shows how to read data of a specified length from the UART device: ``` int32_t ret; uint8_t rbuff[5] = {0}; /* Read 5-byte data from the UART device. */ ret = UartRead(handle, rbuff, 5); if (ret < 0) { HDF_LOGE("UartRead: failed, ret %d\n", ret); } ``` >![](public_sys-resources/icon-caution.gif) **CAUTION:** >Data is successfully read from the UART device if a non-negative value is returned. If the return value is **0**, no valid data can be read from the UART device. If the return value is greater than **0**, the return value is the length of the data actually read from the UART device. The length is less than or equal to the value of **size** and does not exceed the maximum length of data to read at a time specified by the UART controller in use. ## Destroying the UART Device Handle After the UART communication, destroy the UART device handle by calling the following function: void UartClose\(DevHandle handle\); This function will release the resources previously obtained. **Table 9** Description of **UartClose**

Parameter	Description
handle	Pointer to the UART device handle

The following example shows how to destroy the UART device handle: ``` UartClose(handle); /* Destroy the UART device handle. */ ```