HAL USART How to Use ¶

group USART_How_To_Use

How to use the USART HAL module driver ¶

The USART Synchronous SPI HAL driver in synchronous SPI master/slave mode can be used as follows: ¶

• Declare a hal_usart_handle_t handle structure, for example: hal_usart_handle_t husart;

• Initialize the USART low level resources :

  • Enable the USART interface clock if you have not set USE_HAL_USART_CLK_ENABLE_MODEL to HAL_CLK_ENABLE_PERIPH_ONLY or HAL_CLK_ENABLE_PERIPH_PWR_SYSTEM (in those cases HAL_USART_Init() will enable the clock).

  • USART pins configuration:

    • Enable the clock for the USART GPIOs

    • Configure these USART pins as alternate function.

  • NVIC configuration if one needs to use interrupt process ( HAL_USART_Transmit_IT() and HAL_USART_Receive_IT() , HAL_USART_TransmitReceive_IT() and their _Opt equivalent APIs):

    • Configure the USART interrupt priority.

    • Enable the NVIC USART IRQ Channel.

  • DMA Configuration if one needs to use DMA process ( HAL_USART_Transmit_DMA() and HAL_USART_Receive_DMA() , HAL_USART_TransmitReceive_DMA() and their _Opt equivalent 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 to the USART handle with HAL_USART_SetTxDMA() or HAL_USART_SetRxDMA() .

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

• Initialize the USART with HAL_USART_Init() and by selecting an instance, for example: HAL_USART_Init(husart, HAL_USART1);

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

• In the configuration structure, program the Baud Rate, Word Length, Stop Bit, Parity, Prescaler value, Device Mode, Direction (Receiver/Transmitter), Clock Polarity, Clock Phase and Last Bit Clock Pulse.

• Apply the configuration with HAL_USART_SetConfig(&my_config)

• if needed, to configure and enable/disable the USART to wake up the MCU from stop mode, resort to UART API’s HAL_UART_SetStopModeWakeUpAddress() , HAL_UART_EnableStopMode() and HAL_UART_DisableStopMode() in casting the USART handle to UART type hal_usart_handle_t .

Callbacks definition in Interrupt or DMA mode: ¶

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

Callback name	Default value	Callback registration function
TxHalfCpltCallback	HAL_USART_TxHalfCpltCallback()	HAL_USART_RegisterTxHalfCpltCallback()
TxCpltCallback	HAL_USART_TxCpltCallback()	HAL_USART_RegisterTxCpltCallback()
RxHalfCpltCallback	HAL_USART_RxHalfCpltCallback()	HAL_USART_RegisterRxHalfCpltCallback()
RxCpltCallback	HAL_USART_RxCpltCallback()	HAL_USART_RegisterRxCpltCallback()
ErrorCallback	HAL_USART_ErrorCallback()	HAL_USART_RegisterErrorCallback()
AbortCpltCallback	HAL_USART_AbortCpltCallback()	HAL_USART_RegisterAbortCpltCallback()
TxRxCpltCallback	HAL_USART_TxRxCpltCallback()	HAL_USART_RegisterTxRxCpltCallback()
RxFifoFullCallback	HAL_USART_RxFifoFullCallback()	HAL_USART_RegisterRxFifoFullCallback()
TxFifoEmptyCallback	HAL_USART_TxFifoEmptyCallback()	HAL_USART_RegisterTxFifoEmptyCallback()

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

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

Callbacks can be registered in handle global_state HAL_USART_STATE_INIT and HAL_USART_STATE_IDLE.

When the compilation define USE_HAL_USART_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.

Warning

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