HAL UART How to Use ¶

group UART_How_To_Use

How to use the UART HAL module driver ¶

The UART HAL driver can be used as follows: ¶

• Declare a hal_uart_handle_t handle structure, for example: hal_uart_handle_t huart;

• Initialize the UART low-level resources:

  • Enable the USARTx interface clock if you have not set USE_HAL_UART_CLK_ENABLE_MODEL to HAL_CLK_ENABLE_PERIPH_ONLY or HAL_CLK_ENABLE_PERIPH_PWR_SYSTEM (in those cases HAL_UART_Init() will enable the clock).

  • UART pins configuration:

    • Enable the clock for the UART GPIOs

    • Configure these UART pins as alternate function.

  • NVIC configuration if one needs to use interrupt process ( HAL_UART_Transmit_IT() and HAL_UART_Receive_IT() , … APIs):

    • Configure the USARTx interrupt priority.

    • Enable the NVIC USARTx IRQ Channel.

  • DMA configuration if one needs to use DMA process ( HAL_UART_Transmit_DMA() and HAL_UART_Receive_DMA() , … APIs):

    • Declare a DMA handle structure for the Tx or Rx channel.

    • Enable the DMAx interface clock.

    • Configure the declared DMA handle structure with the required Tx or Rx parameters.

    • Associate the initialized DMA handle with the UART handle with HAL_UART_SetTxDMA() or HAL_UART_SetRxDMA() .

    • For each DMA channel (Tx and Rx), configure the corresponding NVIC line priority and enable it.

• Initialize the UART with HAL_UART_Init() and by selecting an instance, for example: HAL_UART_Init(huart, HAL_UART1);

• Declare a hal_uart_config_t structure, for example: hal_uart_config_t my_config;

• In the configuration structure, program the baud rate, word length, stop bit, parity, prescaler value, hardware flow control, direction (Receiver/Transmitter), over-sampling and one-bit sampling.

• Apply the configuration with HAL_UART_SetConfig(&my_config)

• If required, one can enable one specific mode on the UART:

  • Half duplex mode with HAL_UART_EnableHalfDuplexMode()

  • Multi processor mode with HAL_UART_EnableMultiProcessorMode()

  • LIN mode with HAL_UART_EnableLINMode()

  • RS-485 mode with HAL_UART_EnableRS485Mode()

• If required, program UART advanced features (TX/RX pins swap, auto baud rate detection,…) with a set of different configuration functions.

Callbacks definition in interrupt or DMA mode: ¶

When the compilation define USE_HAL_UART_REGISTER_CALLBACKS is set to 1U, the user can dynamically configure the driver callbacks, via its own method:

Callback name	Default value	Callback registration function
TxHalfCpltCallback	HAL_UART_TxHalfCpltCallback()	HAL_UART_RegisterTxHalfCpltCallback()
TxCpltCallback	HAL_UART_TxCpltCallback()	HAL_UART_RegisterTxCpltCallback()
RxHalfCpltCallback	HAL_UART_RxHalfCpltCallback()	HAL_UART_RegisterRxHalfCpltCallback()
RxCpltCallback	HAL_UART_RxCpltCallback()	HAL_UART_RegisterRxCpltCallback()
ErrorCallback	HAL_UART_ErrorCallback()	HAL_UART_RegisterErrorCallback()
AbortCpltCallback	HAL_UART_AbortCpltCallback()	HAL_UART_RegisterAbortCpltCallback()
AbortTransmitCpltCallback	HAL_UART_AbortTransmitCpltCallback()	HAL_UART_RegisterAbortTransmitCpltCallback()
AbortReceiveCpltCallback	HAL_UART_AbortReceiveCpltCallback()	HAL_UART_RegisterAbortReceiveCpltCallback()
RxFifoFullCallback	HAL_UART_RxFifoFullCallback()	HAL_UART_RegisterRxFifoFullCallback()
TxFifoEmptyCallback	HAL_UART_TxFifoEmptyCallback()	HAL_UART_RegisterTxFifoEmptyCallback()
LINBreakCallback	HAL_UART_LINBreakCallback()	HAL_UART_RegisterLINBreakCallback()
ClearToSendCallback	HAL_UART_ClearToSendCallback()	HAL_UART_RegisterClearToSendCallback()

If one needs to unregister a callback, register the default callback via the registration function.

By default, after the HAL_UART_Init() and when the state is HAL_UART_STATE_INIT, all callbacks are set to the corresponding default weak functions.

Callbacks can be registered in handle global_state HAL_UART_STATE_INIT and HAL_UART_STATE_CONFIGURED.

When the compilation define USE_HAL_UART_REGISTER_CALLBACKS is set to 0U or not defined, the callback registration feature is not available and weak callbacks are used, represented by the default value in the table above.

Note

In the following documentation one considers USARTx as a reflection of every UART instances, USART instances, and LPUART instances as well.

Note

In DMA Tx configuration, one also needs to enable the USARTx IRQ to complete the DMA transfer.