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:

1. Declare a hal_usart_handle_t handle structure, for example: hal_usart_handle_t husart;

2. Configure the low-level hardware (GPIO, CLOCK, NVIC, etc.):

   • 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 an alternate function.

   • NVIC configuration when using interrupt processing (HAL_USART_Transmit_IT(), 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 when using DMA processing (HAL_USART_Transmit_DMA(), 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.

3. Initialize the USART driver by selecting a USART instance and calling HAL_USART_Init(). Depending on USE_HAL_USART_CLK_ENABLE_MODEL, HAL_USART_Init() can enable the USART clock. For example: HAL_USART_Init(&husart, HAL_USART1);

4. Declare a hal_usart_config_t structure, fill it, and call HAL_USART_SetConfig(). 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 by calling HAL_USART_SetConfig(&husart, &my_config).

   If needed, configure and enable or disable the USART to wake up the MCU from stop mode. Use the UART APIs HAL_UART_SetStopModeWakeUpAddress(), HAL_UART_EnableStopMode() and HAL_UART_DisableStopMode() by casting the USART handle to UART type hal_usart_handle_t.

5. Callback registration When the compilation define USE_HAL_USART_REGISTER_CALLBACKS is set to 1U, configure the driver callbacks dynamically using a user-defined 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 you need 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.

Register callbacks when handle global_state is HAL_USART_STATE_INIT or 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, as listed by the default values in the table above.

1. Acquire/Release the HAL USART handle

   • When the compilation flag USE_HAL_MUTEX is set to 1, a multithreaded user application can acquire the USART HAL handle to execute a transmit or a receive process or a sequence of transmit/receive. When the process or sequence ends, release the USART HAL handle.

   • The HAL acquire/release functions are based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal):

     • Use HAL_USART_AcquireBus() to acquire/take the HAL USART handle.

     • Use HAL_USART_ReleaseBus() to release the HAL USART handle.

   • When the compilation flag USE_HAL_MUTEX is set to 0 or not defined, HAL_USART_AcquireBus() and HAL_USART_ReleaseBus() are not available.

Warning

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