HAL UART Functions

Initialization and de-initialization functions

group UART_Exported_Functions_Group1

This subsection provides a set of functions allowing to initialize and deinitialize the USARTx in asynchronous mode.

  • Call the function HAL_UART_Init() to initialize the selected USARTx handle and associate an instance.

  • Call the function HAL_UART_DeInit() to de-initialize the given HAL UART instance by stopping any ongoing process and resetting the state machine .

Functions

hal_status_t HAL_UART_Init ( hal_uart_handle_t * huart , hal_uart_t instance )

Initialize the UART handler for the associated instance.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which will contain the UART instance.

  • instance – USARTx instance.

Return values :

  • HAL_OK – UART instance has been correctly initialized

  • HAL_INVALID_PARAM – UART instance is NULL

  • HAL_ERROR – UART semaphore creation is failed (USE_HAL_MUTEX is set to 1)

void HAL_UART_DeInit ( hal_uart_handle_t * huart )

Deinitializes the UART handler, reset the flags, states and counters.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Basic configuration functions

group UART_Exported_Functions_Group2

This subsection provides a set of functions allowing to configure the USARTx in asynchronous mode.

  • Possible frame format: Depending on the frame length defined by the M1 and M0 bits from the CR1 register (7-bit, 8-bit or 9-bit), the possible UART formats are listed in the following table. 

UART frame format.
  +-----------------------------------------------------------------------+
  |  M1 bit |  M0 bit |  PCE bit  |             UART frame                |
  |---------|---------|-----------|---------------------------------------|
  |    0    |    0    |    0      |    | SB |    8 bit data   | STB |     |
  |---------|---------|-----------|---------------------------------------|
  |    0    |    0    |    1      |    | SB | 7 bit data | PB | STB |     |
  |---------|---------|-----------|---------------------------------------|
  |    0    |    1    |    0      |    | SB |    9 bit data   | STB |     |
  |---------|---------|-----------|---------------------------------------|
  |    0    |    1    |    1      |    | SB | 8 bit data | PB | STB |     |
  |---------|---------|-----------|---------------------------------------|
  |    1    |    0    |    0      |    | SB |    7 bit data   | STB |     |
  |---------|---------|-----------|---------------------------------------|
  |    1    |    0    |    1      |    | SB | 6 bit data | PB | STB |     |
  +-----------------------------------------------------------------------+

Note

  • Prescaler : cannot be modified with a unitary configuration function as it impacts other parameters, one can call HAL_UART_SetConfig() to modify it.

  • Over Sampling : cannot be modified with a unitary configuration function as it impacts other parameters, one can call HAL_UART_SetConfig() to modify it.

Note

  • Prescaler : As there is no unitary configuration function for this parameter, there is no unitary getter as well.

  • Over Sampling : As there is no unitary configuration function for this parameter, there is no unitary getter as well.

Functions

hal_status_t HAL_UART_SetConfig ( hal_uart_handle_t * huart , const hal_uart_config_t * p_config )

Set the basic configuration to enable the use of the UART instance.

Parameters :
Return values :

  • HAL_OK – UART instance has been correctly configured.

  • HAL_INVALID_PARAM – p_config is NULL.

  • HAL_ERROR – Kernel clock is not set.

void HAL_UART_GetConfig ( const hal_uart_handle_t * huart , hal_uart_config_t * p_config )

Get the current basic configuration set in the current UART instance.

Parameters :
hal_status_t HAL_UART_SetWordLength ( const hal_uart_handle_t * huart , hal_uart_word_length_t word_length )

Set the Word Length configuration passed in parameters into the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • word_length – Word length to be applied.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_word_length_t HAL_UART_GetWordLength ( const hal_uart_handle_t * huart )

Get the Word Length configuration according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_word_length_t – Current Word length configuration.

hal_status_t HAL_UART_SetParity ( const hal_uart_handle_t * huart , hal_uart_parity_t parity )

Set the Parity configuration passed in parameters into the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • parity – Parity to be applied.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_parity_t HAL_UART_GetParity ( const hal_uart_handle_t * huart )

Get the Parity configuration according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_parity_t – Current Parity configuration.

hal_status_t HAL_UART_SetStopBits ( const hal_uart_handle_t * huart , hal_uart_stop_bits_t stop_bits )

Set the Stop Bits configuration passed in parameters into the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • stop_bits – Stop Bits to be applied.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_stop_bits_t HAL_UART_GetStopBits ( const hal_uart_handle_t * huart )

Get the Stop Bits configuration according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_stop_bits_t – Current Stop Bits configuration.

hal_status_t HAL_UART_SetXferDirection ( const hal_uart_handle_t * huart , hal_uart_direction_t direction )

Set the XFer Direction configuration passed in parameters into the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • direction – XFer Direction to be applied.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_direction_t HAL_UART_GetXferDirection ( const hal_uart_handle_t * huart )

Get the XFer Direction configuration according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_direction_t – Current XFer Direction configuration.

hal_status_t HAL_UART_SetHwFlowCtl ( const hal_uart_handle_t * huart , hal_uart_hw_control_t hw_flow_ctl )

Set the Hardwre Flow Control configuration passed in parameters into the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • hw_flow_ctl – Hardware Flow Control to be applied.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_hw_control_t HAL_UART_GetHwFlowCtl ( const hal_uart_handle_t * huart )

Get the Hardware Flow Control configuration according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_hw_control_t – Current Hardware Flow Control configuration.

hal_status_t HAL_UART_SetOneBitSample ( const hal_uart_handle_t * huart , hal_uart_one_bit_sample_t one_bit_sample )

Set the One Bit Sample configuration passed in parameters into the handler instance registers.

Note

This feature is not available for LPUART instances.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • one_bit_sample – One Bit Sample to be applied

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_one_bit_sample_t HAL_UART_GetOneBitSample ( const hal_uart_handle_t * huart )

Get the One Bit Sample configuration according to the handler instance registers.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_one_bit_sample_t – Current One Bit Sampling configuration.

hal_status_t HAL_UART_SetBaudRate ( const hal_uart_handle_t * huart , uint32_t baud_rate )

Set the Baud Rate configuration passed in parameters into the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • baud_rate – Baud rate value to set.

Return values :

  • HAL_OK – UART instance has been correctly configured.

  • HAL_INVALID_PARAM – Required baud rate value can’t be set with current config.

uint32_t HAL_UART_GetBaudRate ( const hal_uart_handle_t * huart )

Get the Baud Rate configuration according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

uint32_t – Current baud rate value.

IRDA configuration functions

group UART_Exported_Functions_Group3

This subsection provides a set of functions allowing to configure the USARTx instance in IRDA mode A set of functions is provided to use the IRDA feature:

A set of getter function is also provided to check the current configuration:

It is important to note that the HAL_UART_IRDA_SetConfig API can be called without calling HAL_UART_SetConfig beforehand. The HAL_UART_xxxx API are still available in IRDA and have to be used to communicate.

Warning

Please note that while in IRDA mode LIN mode cannot be enabled, the stop bit configuration cannot be changed (1 bit is locked) and FIFO cannot be enabled.

Functions

hal_status_t HAL_UART_IRDA_SetConfig ( hal_uart_handle_t * huart , const hal_uart_irda_config_t * p_config )

Set the basic configuration to enable the use of the UART instance.

Parameters :
Return values :

  • HAL_OK – UART instance has been correctly configured.

  • HAL_INVALID_PARAM – p_config is NULL.

void HAL_UART_IRDA_GetConfig ( const hal_uart_handle_t * huart , hal_uart_irda_config_t * p_config )

Get the current IRDA configuration set in the current UART instance.

Parameters :
hal_status_t HAL_UART_IRDA_SetPrescaler ( const hal_uart_handle_t * huart , uint32_t irda_prescaler )

Set the IRDA prescaler value.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • irda_prescaler – IRDA prescaler value to set (must be between 0x00 and 0xFF).

Return values :

HAL_OK – UART instance has been correctly configured.

uint32_t HAL_UART_IRDA_GetPrescaler ( const hal_uart_handle_t * huart )

Get the IRDA prescaler value according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

uint32_t – Current IRDA prescaler value.

hal_status_t HAL_UART_IRDA_SetPowerMode ( const hal_uart_handle_t * huart , hal_uart_irda_power_mode_t irda_power_mode )

Get the IRDA power mode according to the handler instance registers.

Parameters :
Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_irda_power_mode_t HAL_UART_IRDA_GetPowerMode ( const hal_uart_handle_t * huart )

Get the IRDA power mode according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_irda_power_mode_t – Current IRDA power mode.

Mode configuration functions

group UART_Exported_Functions_Group4

This subsection provides a set of functions allowing to configure the USARTx instance in particular asynchronous modes. Prior to enable one of the following particular asynchronous modes, one has to configure one’s instance in asynchronous mode with HAL_UART_SetConfig() .

Some modes require configuration which one can set by calling the following API:

One can enable a mode by calling the associated functions:

The different modes are not compatible with each other, so one cannot enable 2 modes on the same instance.

One can disable every mode by calling the associated functions:

One can check if a mode is correctly enabled by calling the associated functions:

For the Multi Processor mode, once one enabled the mode, it is not active yet, one has to call HAL_UART_EnterMultiProcessorMuteMode() to enter in Mute. One can check if the UART is in Mute with HAL_UART_IsEnteredMultiProcessorMuteMode() .

Functions

hal_status_t HAL_UART_EnableLINMode ( const hal_uart_handle_t * huart )

Enable the LIN Mode.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableLINMode ( const hal_uart_handle_t * huart )

Disable the LIN Mode.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_lin_mode_status_t HAL_UART_IsEnabledLINMode ( const hal_uart_handle_t * huart )

Return the LIN Mode status according to the handler instance registers.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_lin_mode_status_t – Current LIN mode status.

hal_status_t HAL_UART_SetLINModeBreakDetectLength ( const hal_uart_handle_t * huart , hal_uart_lin_break_detect_length_t break_detect_length )

In LIN mode, set the Break Detection Length configuration passed in parameters into the handler instance registers.

Note

This feature is not available for LPUART instances.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • break_detect_length – LIN Break Detection Length.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_lin_break_detect_length_t HAL_UART_GetLINModeBreakDetectLength ( const hal_uart_handle_t * huart )

In LIN mode, get the Break Detection Length configuration according to the handler instance registers.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_lin_break_detect_length_t – Current Break Detection Length configuration.

hal_status_t HAL_UART_EnableRS485Mode ( const hal_uart_handle_t * huart )

Enable the RS485 Mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableRS485Mode ( const hal_uart_handle_t * huart )

Disable the RS485 Mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_rs485_mode_status_t HAL_UART_IsEnabledRS485Mode ( const hal_uart_handle_t * huart )

Return the RS485 Mode status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_rs485_mode_status_t – Current RS485 Mode status.

hal_status_t HAL_UART_SetConfigRS485Mode ( const hal_uart_handle_t * huart , const hal_uart_rs485_config_t * p_config )

In RS485 mode, set the configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

  • HAL_OK – UART instance has been correctly configured.

  • HAL_INVALID_PARAM – p_config is NULL.

void HAL_UART_GetConfigRS485Mode ( const hal_uart_handle_t * huart , hal_uart_rs485_config_t * p_config )

In RS485 mode, get the configuration according to the handler instance registers.

Parameters :
hal_status_t HAL_UART_EnableHalfDuplexMode ( const hal_uart_handle_t * huart )

Enable the Half Duplex Mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableHalfDuplexMode ( const hal_uart_handle_t * huart )

Disable the Half Duplex Mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_half_duplex_mode_status_t HAL_UART_IsEnabledHalfDuplexMode ( const hal_uart_handle_t * huart )

Return the Half Duplex Mode status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_half_duplex_mode_status_t – Current Half Duplex Mode status.

hal_status_t HAL_UART_EnableMultiProcessorMode ( const hal_uart_handle_t * huart )

Enable the Multi Processor mode.

Note

This does not make the instance entering in Mute Mode. For this, use HAL_UART_EnterMultiProcessorMuteMode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableMultiProcessorMode ( const hal_uart_handle_t * huart )

Disable the Multi Processor Mode into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_multi_processor_mode_status_t HAL_UART_IsEnabledMultiProcessorMode ( const hal_uart_handle_t * huart )

Return the Multi Processor Mode status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_multi_processor_mode_status_t – Current Multi Processor Mode status.

hal_status_t HAL_UART_SetConfigMultiProcessorMode ( const hal_uart_handle_t * huart , const hal_uart_multi_processor_mode_wakeup_config_t * p_wakeup_config )

For Multi Processor mode, set the Mute configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

  • HAL_OK – UART instance has been correctly configured.

  • HAL_INVALID_PARAM – p_wakeup_config is NULL.

void HAL_UART_GetConfigMultiProcessorMode ( const hal_uart_handle_t * huart , hal_uart_multi_processor_mode_wakeup_config_t * p_wakeup_config )

For Multi Processor mode, get the Mute configuration according to the handler instance registers.

Parameters :
hal_status_t HAL_UART_EnterMultiProcessorMuteMode ( const hal_uart_handle_t * huart )

For Multi Processor Mode, request instance to enter in Mute.

Note

Requires HAL_UART_EnableMultiProcessorMode to be called first.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Request has been sent.

hal_uart_multi_processor_mode_mute_status_t HAL_UART_IsEnteredMultiProcessorMuteMode ( const hal_uart_handle_t * huart )

For Multi Processor Mode, return if the instance is in Mute.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_multi_processor_mode_mute_status_t – Status of the Mute.

Advanced configuration functions

group UART_Exported_Functions_Group5

This subsection provides a set of functions allowing to configure advanced features for the USARTx instance. Please consider all advanced features might not be supported on all instances. Prior to configure advanced features, one has to configure one’s instance in asynchronous mode with HAL_UART_SetConfig() .

One can enable a set of advanced features by calling the associated functions:

One can disable a set of advanced features by calling the associated functions:

One can check if a feature is correctly enabled by calling the associated functions:

One can configure some features by calling the associated functions:

Functions

hal_status_t HAL_UART_EnableTxPinLevelInvert ( const hal_uart_handle_t * huart )

Enable the Tx Pin Level Inversion into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableTxPinLevelInvert ( const hal_uart_handle_t * huart )

Disable the Tx Pin Level Inversion into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_tx_pin_level_invert_status_t HAL_UART_IsEnabledTxPinLevelInvert ( const hal_uart_handle_t * huart )

Return the Tx Pin Level Inversion status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_tx_pin_level_invert_status_t – Current Tx Pin Level Inversion status.

hal_status_t HAL_UART_EnableRxPinLevelInvert ( const hal_uart_handle_t * huart )

Enable the Rx Pin Level Inversion into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableRxPinLevelInvert ( const hal_uart_handle_t * huart )

Disable the Rx Pin Level Inversion into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_rx_pin_level_invert_status_t HAL_UART_IsEnabledRxPinLevelInvert ( const hal_uart_handle_t * huart )

Return the Rx Pin Level Inversion status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_rx_pin_level_invert_status_t – Current Rx Pin Level Inversion status.

hal_status_t HAL_UART_EnableDataInvert ( const hal_uart_handle_t * huart )

Enable the binary Data Inversion into the handler instance registers, (1=L, 0=H).

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableDataInvert ( const hal_uart_handle_t * huart )

Disable the binary Data Inversion into the handler instance registers (1=H, 0=L).

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_data_invert_status_t HAL_UART_IsEnabledDataInvert ( const hal_uart_handle_t * huart )

Return the binary Data Inversion status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_data_invert_status_t – Current Data Inversion status.

hal_status_t HAL_UART_EnableTxRxSwap ( const hal_uart_handle_t * huart )

Enable the Swap between Tx and Rx Pin into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableTxRxSwap ( const hal_uart_handle_t * huart )

Disable the Swap between Tx and Rx Pin into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_tx_rx_swap_status_t HAL_UART_IsEnabledTxRxSwap ( const hal_uart_handle_t * huart )

Return the Swap between Tx and Rx Pin status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_tx_rx_swap_status_t – Current Tx Rx Swap status.

hal_status_t HAL_UART_EnableRxOverRunDetection ( const hal_uart_handle_t * huart )

Enable the Rx Overrun detection into the handler instance registers.

Note

When UART is initialised and configured with basic configuration parameters, this feature is enabled by default.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableRxOverRunDetection ( const hal_uart_handle_t * huart )

Disable the Rx Overrun detection into the handler instance registers.

Note

When UART is initialised and configured with basic configuration parameters, this feature is enabled by default.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_rx_overrun_detection_status_t HAL_UART_IsEnabledRxOverRunDetection ( const hal_uart_handle_t * huart )

Return the Rx Overrun detection status according to the handler instance registers.

Note

When UART is initialised and configured with basic configuration parameters, this feature is enabled by default.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_rx_overrun_detection_status_t – Current Rx Overrun detection status.

hal_status_t HAL_UART_EnableDMAStopOnRxError ( const hal_uart_handle_t * huart )

Enable the DMA Disabling On a Rx Error into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableDMAStopOnRxError ( const hal_uart_handle_t * huart )

Disable the DMA Disabling On a Rx Error into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_dma_stop_on_rx_error_status_t HAL_UART_IsEnabledDMAStopOnRxError ( const hal_uart_handle_t * huart )

Return the DMA Disabling On a Rx Error status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_dma_stop_on_rx_error_status_t – Current DMA Stopping On a Rx Error status.

hal_status_t HAL_UART_EnableMSBFirst ( const hal_uart_handle_t * huart )

Enable the MSB First into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableMSBFirst ( const hal_uart_handle_t * huart )

Disable the MSB First into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_msb_first_status_t HAL_UART_IsEnabledMSBFirst ( const hal_uart_handle_t * huart )

Return the MSB First status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_msb_first_status_t – Current MSB First status.

hal_status_t HAL_UART_SetConfigReceiverTimeout ( const hal_uart_handle_t * huart , uint32_t timeout_bit )

Set the Receiver Timeout configuration passed in parameters into the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • timeout_bit – Value between 0x00 -> 0xFFFFFFU in number of bit.

Return values :

HAL_OK – UART instance has been correctly configured.

uint32_t HAL_UART_GetConfigReceiverTimeout ( const hal_uart_handle_t * huart )

Get the Receiver Timeout configuration according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

uint32_t – Receiver Timeout between 0x00 -> 0xFFFFFFU in number of bit.

hal_status_t HAL_UART_EnableReceiverTimeout ( const hal_uart_handle_t * huart )

Enable the Receiver Timeout into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableReceiverTimeout ( const hal_uart_handle_t * huart )

Disable the Receiver Timeout into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_receiver_timeout_status_t HAL_UART_IsEnabledReceiverTimeout ( const hal_uart_handle_t * huart )

Return the Receiver Timeout status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_receiver_timeout_status_t – Current Receiver Timeout status.

hal_status_t HAL_UART_EnableTransmitter ( const hal_uart_handle_t * huart )

Enable the Transmitter into the handler instance registers.

Note

Refer to Half Duplex mode to use this API.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableTransmitter ( const hal_uart_handle_t * huart )

Disable the Transmitter into the handler instance registers.

Note

Refer to Half Duplex mode to use this API.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_transmitter_status_t HAL_UART_IsEnabledTransmitter ( const hal_uart_handle_t * huart )

Return the Transmitter status according to the handler instance registers.

Note

Refer to Half Duplex mode to use this API.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_transmitter_status_t – Current Transmitter status.

hal_status_t HAL_UART_EnableReceiver ( const hal_uart_handle_t * huart )

Enable the Receiver into the handler instance registers.

Note

Refer to Half Duplex mode to use this API.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableReceiver ( const hal_uart_handle_t * huart )

Disable the Receiver into the handler instance registers.

Note

Refer to Half Duplex mode to use this API.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_receiver_status_t HAL_UART_IsEnabledReceiver ( const hal_uart_handle_t * huart )

Return the Receiver status according to the handler instance registers.

Note

Refer to Half Duplex mode to use this API.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_receiver_status_t – Current Receiver status.

Auto Baud Rate Configuration functions

group UART_Exported_Functions_Group6

This subsection provides a set of functions allowing to use auto baud rate feature for the USARTx instance. Prior to use auto baud rate feature, one has to configure one’s instance in asynchronous mode with HAL_UART_SetConfig() .

A set of functions is provided to use the auto baud rate feature:

The feature has been designed to be used following the procedure:

Functions

hal_status_t HAL_UART_EnableAutoBaudRate ( const hal_uart_handle_t * huart )

Enable the Auto Baud Rate feature.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableAutoBaudRate ( const hal_uart_handle_t * huart )

Disable the Auto Baud Rate feature.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_auto_baud_rate_status_t HAL_UART_IsEnabledAutoBaudRate ( const hal_uart_handle_t * huart )

Return the Auto Baud Rate activation status according to the handler instance registers.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_auto_baud_rate_status_t – Current Auto Baud Rate activation status.

hal_uart_auto_baud_rate_detection_status_t HAL_UART_GetAutoBaudRateStatus ( const hal_uart_handle_t * huart )

Return the Auto Baud Rate Detection state according to the handler instance registers.

Note

This feature is not available for LPUART instances.

Note

Baud Rate Value is available though HAL_UART_GetBaudRate() .

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_auto_baud_rate_detection_status_t – Current Auto Baud Rate detection state.

hal_status_t HAL_UART_SetConfigAutoBaudRateMode ( const hal_uart_handle_t * huart , hal_uart_auto_baud_rate_mode_t auto_baud_rate_mode )

Set the Auto Baud Rate detection configuration passed in parameters into the handler instance registers.

Note

This feature is not available for LPUART instances.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • auto_baud_rate_mode – Auto Baud Rate Mode to set.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_auto_baud_rate_mode_t HAL_UART_GetConfigAutoBaudRateMode ( const hal_uart_handle_t * huart )

Get the Auto Baud Rate detection configuration according to the handler instance registers.

Note

This feature is not available for LPUART instances.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_auto_baud_rate_mode_t – Current Auto Baud Rate detection configuration.

Stop Mode Configuration functions

group UART_Exported_Functions_Group7

This subsection provides a set of functions allowing to use the stop mode feature for the USARTx instance. Prior to use the stop mode feature, one has to configure one’s instance in asynchronous mode with HAL_UART_SetConfig() . A set of functions is provided to use the stop mode feature:

The feature has been designed to be used following the procedure:

Functions

hal_status_t HAL_UART_EnableStopMode ( const hal_uart_handle_t * huart )

Enable the Stop Mode into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableStopMode ( const hal_uart_handle_t * huart )

Disable the Stop Mode into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_stop_mode_status_t HAL_UART_IsEnabledStopMode ( const hal_uart_handle_t * huart )

Return the Stop Mode status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_stop_mode_status_t – Current Stop Mode status.

hal_status_t HAL_UART_SetStopModeWkUpAddr ( const hal_uart_handle_t * huart , uint8_t address )

Set the Stop Mode Wake Up Address passed in parameters into the handler instance registers.

Note

This Api has to be used with HAL_UART_SetStopModeWkUpAddrLength()

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • address – Address to set.

Return values :

HAL_OK – UART instance has been correctly configured.

uint8_t HAL_UART_GetStopModeWkUpAddr ( const hal_uart_handle_t * huart )

Get the Stop Mode Wake Up Address according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

uint8_t – address.

FIFO Configuration functions

group UART_Exported_Functions_Group8

This subsection provides a set of functions allowing to use the fifo mode feature for the USARTx instance. Prior to use the fifo mode feature, one has to configure one’s instance in asynchronous mode with HAL_UART_SetConfig() . A set of functions is provided to use the fifo mode feature:

The feature has been designed to be used following the procedure:

Functions

hal_status_t HAL_UART_EnableFifoMode ( hal_uart_handle_t * huart )

Enable the FIFO into the handler instance registers.

Note

This feature is not available in LIN mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_DisableFifoMode ( hal_uart_handle_t * huart )

Disable the FIFO into the handler instance registers.

Note

This feature is not available in LIN mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_fifo_mode_status_t HAL_UART_IsEnabledFifoMode ( const hal_uart_handle_t * huart )

Return the FIFO status according to the handler instance registers.

Note

This feature is not available in LIN mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_fifo_mode_status_t – Current FIFO status.

hal_status_t HAL_UART_SetTxFifoThreshold ( hal_uart_handle_t * huart , hal_uart_fifo_threshold_t tx_fifo_threshold )

Set the Tx FIFO Threshold configuration passed in parameters into the handler instance registers.

Note

This feature is not available in LIN mode.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • tx_fifo_threshold – Tx FIFO Threshold to applied.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_fifo_threshold_t HAL_UART_GetTxFifoThreshold ( const hal_uart_handle_t * huart )

Get the Tx FIFO Threshold configuration according to the handler instance registers.

Note

This feature is not available in LIN mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_fifo_threshold_t – Current Tx FIFO Threshold configuration.

hal_status_t HAL_UART_SetRxFifoThreshold ( hal_uart_handle_t * huart , hal_uart_fifo_threshold_t rx_fifo_threshold )

Set the Rx FIFO Threshold configuration passed in parameters into the handler instance registers.

Note

This feature is not available in LIN mode.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • rx_fifo_threshold – Rx FIFO Threshold to applied.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_fifo_threshold_t HAL_UART_GetRxFifoThreshold ( const hal_uart_handle_t * huart )

Get the Rx FIFO Threshold configuration according to the handler instance registers.

Note

This feature is not available in LIN mode.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_fifo_threshold_t – Current Rx FIFO Threshold configuration.

Autonomous Mode functions

group UART_Exported_Functions_Group9

This subsection provides a set of functions allowing to use the autonomous mode feature for the USARTx instance. Prior to use the autonomous mode feature, one has to configure one’s instance in asynchronous mode with HAL_UART_SetConfig() . A set of functions is provided to use the autonomous mode feature:

The feature has been designed to be used following the procedure:

Functions

hal_status_t HAL_UART_AM_EnablePacketTrigger ( const hal_uart_handle_t * huart )

Enable the Autonomous Mode Packet Trigger into the handler instance registers.

Warning

When using this API, TE block will be reset to let the autonomous mode controlling it.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_AM_DisablePacketTrigger ( const hal_uart_handle_t * huart )

Disable the Autonomous Mode Packet Trigger into the handler instance registers.

Warning

When using this API, TE block will be set back for the standard mode to be functional.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_am_packet_trig_status_t HAL_UART_AM_IsEnabledPacketTrigger ( const hal_uart_handle_t * huart )

Return the Autonomous Mode Packet Trigger status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

Current – Autonomous Mode Packet Trigger status.

hal_status_t HAL_UART_AM_SetConfigPacketTrigger ( const hal_uart_handle_t * huart , const hal_uart_am_trig_config_t * p_config )

Set the UART Autonomous Packet Trigger configuration passed in parameters into the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_config – Pointer to a hal_uart_autonomous_mode_packet_trigger_config_t.

Return values :

  • HAL_OK – UART instance has been correctly configured.

  • HAL_INVALID_PARAM – p_config is NULL.

void HAL_UART_AM_GetConfigPacketTrigger ( const hal_uart_handle_t * huart , hal_uart_am_trig_config_t * p_config )

Get the UART Autonomous Packet Trigger configuration according to the handler instance registers.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_config – Pointer to a hal_uart_autonomous_mode_packet_trigger_config_t.

hal_status_t HAL_UART_AM_EnableIdle ( const hal_uart_handle_t * huart )

Enable the Autonomous Mode Idle Frame Sending into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_status_t HAL_UART_AM_DisableIdle ( const hal_uart_handle_t * huart )

Disable the Autonomous Mode Idle Frame Sending into the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – UART instance has been correctly configured.

hal_uart_am_idle_frame_status_t HAL_UART_AM_IsEnabledIdle ( const hal_uart_handle_t * huart )

Return the Autonomous Mode Idle Frame Sending status according to the handler instance registers.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_am_idle_frame_status_t – Current Autonomous Mode Idle Frame Sending status.

DMA Configuration functions

group UART_Exported_Functions_Group10

This subsection provides a set of functions allowing to link the HAL UART handle to a Tx and Rx DMA handler for the USARTx instance. A set of functions is provided to use the DMA feature:

Functions

hal_status_t HAL_UART_SetTxDMA ( hal_uart_handle_t * huart , hal_dma_handle_t * hdma_tx )

Set DMA channel for Transmission.

Parameters :
Return values :

  • HAL_OK – The channel has been correctly set.

  • HAL_INVALID_PARAM – hdma_tx is NULL.

hal_status_t HAL_UART_SetRxDMA ( hal_uart_handle_t * huart , hal_dma_handle_t * hdma_rx )

Set DMA channel for Reception.

Parameters :
Return values :

  • HAL_OK – The channel has been correctly set.

  • HAL_INVALID_PARAM – hdma_rx is NULL.

Callbacks Register functions

group UART_Exported_Functions_Group11

This subsection provides a set of functions allowing to configure the Callbacks for the USARTx instance. Prior to configure the Callbacks, one has to configure one’s instance in asynchronous mode with HAL_UART_SetConfig() . A set of functions is provided to configure the callbacks:

Functions

hal_status_t HAL_UART_RegisterTxHalfCpltCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Tx Half Complete Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Tx Half Complete Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterTxCpltCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Tx Complete Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Tx Complete Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterRxHalfCpltCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Rx Half Complete Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Rx Half Complete Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterRxCpltCallback ( hal_uart_handle_t * huart , hal_uart_rx_cplt_cb_t p_callback )

Register the UART Rx Complete Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Rx Complete Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterErrorCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Error Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Error Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterAbortCpltCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Abort Complete Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Abort Complete Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterAbortTransmitCpltCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Abort Transmit Complete Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Abort Transmit Complete Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterAbortReceiveCpltCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Abort Receive Complete Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Abort Receive Complete Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterRxFifoFullCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Rx Fifo Full Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Rx Fifo Full Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterTxFifoEmptyCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Tx Fifo Empty Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Tx Fifo Empty Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterClearToSendCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART Clear To Send Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the Clear To Send Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

hal_status_t HAL_UART_RegisterLINBreakCallback ( hal_uart_handle_t * huart , hal_uart_cb_t p_callback )

Register the UART LIN Break Callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_callback – pointer to the LIN Break Callback function

Return values :

  • HAL_OK – The function has been registered.

  • HAL_INVALID_PARAM – p_callback is NULL.

IO operation functions

group UART_Exported_Functions_Group12

This subsection provides a set of functions allowing to manage the UART asynchronous and Half Duplex data transfers.

There are two modes of transfer:

  • Blocking mode: The communication is performed in polling mode. The HAL status of all data processing is returned by the same function after finishing transfer.

  • Non-Blocking mode: The communication is performed using Interrupts or DMA. These API’s return the HAL status. The end of the data processing will be indicated through the dedicated UART IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_UART_TxCpltCallback() , HAL_UART_RxCpltCallback() user callbacks will be executed respectively at the end of the Transmit or Receive process The HAL_UART_ErrorCallback() user callback will be executed when a communication error is detected.

Blocking mode API’s are :

Non-Blocking mode API’s with Interrupt are :

Non-Blocking mode API’s with DMA are :

A set of Transfer Complete Callbacks are provided in Non_Blocking mode:

Non-Blocking mode transfers could be aborted using Abort API’s :

For Abort services based on interrupts (HAL_UART_Abortxxx_IT), a set of Abort Complete Callbacks are provided:

In Non-Blocking mode transfers, possible errors are split into 2 categories:

  • Error is considered as Recoverable and non blocking : Transfer could go till end, but error severity is to be evaluated by user : this concerns Frame Error, Parity Error or Noise Error in Interrupt mode reception . Received character is then retrieved and stored in Rx buffer, Error code is set to allow user to identify error type, and HAL_UART_ErrorCallback() user callback is executed. Transfer is kept ongoing on UART side. If user wants to abort it, Abort services must be called by user.

  • Error is considered as Blocking : Transfer could not be completed properly and is aborted. This concerns Overrun Error In Interrupt mode reception and all errors in DMA mode. Error code is set to allow user to identify error type, and HAL_UART_ErrorCallback() user callback is executed.

In the Half Duplex communication, it is forbidden to run the Transmit and Receive process in parallel.

Functions

hal_status_t HAL_UART_Transmit ( hal_uart_handle_t * huart , const void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Send an amount of data in blocking mode.

Warning

When UART parity is not enabled (PCE bit from register CR1 = 0), and Word Length is configured to 9 bits (M1-M0 from register CR1 = 01), the sent data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be sent.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_TIMEOUT – Operation exceeds user timeout.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_Receive ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Receive an amount of data in blocking mode.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be received.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_TIMEOUT – Operation exceeds user timeout.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_Transmit_IT ( hal_uart_handle_t * huart , const void * p_data , uint32_t size_byte )

Send an amount of data in interrupt mode.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the sent data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be sent.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_Transmit_IT_Opt ( hal_uart_handle_t * huart , const void * p_data , uint32_t size_byte , uint32_t interrupts )

Send an amount of data in interrupt mode, allow user to enable Optional Interrupts part of UART Optional Interrupts for Transmit interrupt process.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the sent data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be sent.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Transmit interrupt process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_Receive_IT ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte )

Receive an amount of data in interrupt mode.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be received.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_Receive_IT_Opt ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t interrupts )

Receive an amount of data in interrupt mode, allow user to enable Optional Interrupts part of UART Optional Interrupts for Receive interrupt process.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be received.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Receive interrupt process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_Transmit_DMA ( hal_uart_handle_t * huart , const void * p_data , uint32_t size_byte )

Send an amount of data in DMA mode.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the sent data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be sent.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – TX DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_Transmit_DMA_Opt ( hal_uart_handle_t * huart , const void * p_data , uint32_t size_byte , uint32_t interrupts )

Send an amount of data in DMA mode.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the sent data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be sent.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Transmit DMA process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – TX DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_Receive_DMA ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte )

Receive an amount of data in DMA mode.

Warning

When the UART parity is enabled (PCE bit from the CR1 register = 1), the received data contain the parity bit (MSB position).

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be received.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – RX DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_Receive_DMA_Opt ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t interrupts )

Receive an amount of data in DMA mode, allow user to enable Optional Interrupts part of UART Optional Interrupts for Receive DMA process.

Warning

When the UART parity is enabled (PCE bit from the CR1 register = 1), the received data contain the parity bit (MSB position).

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of u16.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes to be received.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Receive DMA process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – RX DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_Pause_DMA ( hal_uart_handle_t * huart )

Pause the DMA Transfer.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_PauseReceive_DMA ( hal_uart_handle_t * huart )

Pause the DMA Receive transfer.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_PauseTransmit_DMA ( hal_uart_handle_t * huart )

Pause the DMA Transmit transfer.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_Resume_DMA ( hal_uart_handle_t * huart )

Resume DMA Transfer.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_ResumeReceive_DMA ( hal_uart_handle_t * huart )

Resume the DMA Receive transfer.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_ResumeTransmit_DMA ( hal_uart_handle_t * huart )

Resume the DMA Transmit transfer.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_Abort ( hal_uart_handle_t * huart )

Abort ongoing transfers (blocking mode).

Note

This procedure could be used for aborting any ongoing transfer started in Interrupt or DMA mode. This procedure performs following operations :

  • Disable UART Interrupts (Tx and Rx)

  • Disable the DMA transfer in the peripheral register (if enabled)

  • Abort DMA transfer by calling HAL_DMA_Abort (in case of transfer in DMA mode)

  • Set handle rx_state to HAL_UART_RX_STATE_IDLE and tx_state to HAL_UART_TX_STATE_IDLE

Note

This procedure is executed in blocking mode : when exiting function, Abort is considered as completed.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_AbortTransmit ( hal_uart_handle_t * huart )

Abort ongoing Transmit transfer (blocking mode).

Note

This procedure could be used for aborting any ongoing Tx transfer started in Interrupt or DMA mode. This procedure performs following operations :

  • Disable UART Interrupts (Tx)

  • Disable the DMA transfer in the peripheral register (if enabled)

  • Abort DMA transfer by calling HAL_DMA_Abort (in case of transfer in DMA mode)

  • Set handle tx_state to HAL_UART_TX_STATE_IDLE

Note

This procedure is executed in blocking mode : when exiting function, Abort is considered as completed.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_AbortReceive ( hal_uart_handle_t * huart )

Abort ongoing Receive transfer (blocking mode).

Note

This procedure could be used for aborting any ongoing Rx transfer started in Interrupt or DMA mode. This procedure performs following operations :

  • Disable UART Interrupts (Rx)

  • Disable the DMA transfer in the peripheral register (if enabled)

  • Abort DMA transfer by calling HAL_DMA_Abort (in case of transfer in DMA mode)

  • Set handle rx_state to HAL_UART_RX_STATE_IDLE

Note

This procedure is executed in blocking mode : when exiting function, Abort is considered as completed.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_Abort_IT ( hal_uart_handle_t * huart )

Abort ongoing transfers (Interrupt mode).

Note

This procedure could be used for aborting any ongoing transfer started in Interrupt or DMA mode. This procedure performs following operations :

  • Disable UART Interrupts (Tx and Rx)

  • Disable the DMA transfer in the peripheral register (if enabled)

  • Abort DMA transfer by calling HAL_DMA_Abort_IT (in case of transfer in DMA mode)

  • Set handle rx_state to HAL_UART_RX_STATE_IDLE and tx_state to HAL_UART_TX_STATE_IDLE

  • At abort completion, call user abort complete callback

Note

This procedure is executed in Interrupt mode, meaning that abort procedure could be considered as completed only when user abort complete callback is executed (not when exiting function).

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_AbortTransmit_IT ( hal_uart_handle_t * huart )

Abort ongoing Transmit transfer (Interrupt mode).

Note

This procedure could be used for aborting any ongoing Tx transfer started in Interrupt or DMA mode. This procedure performs following operations :

  • Disable UART Interrupts (Tx)

  • Disable the DMA transfer in the peripheral register (if enabled)

  • Abort DMA transfer by calling HAL_DMA_Abort_IT (in case of transfer in DMA mode)

  • Set handle tx_state to HAL_UART_TX_STATE_IDLE

  • At abort completion, call user abort complete callback

Note

This procedure is executed in Interrupt mode, meaning that abort procedure could be considered as completed only when user abort complete callback is executed (not when exiting function).

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_UART_AbortReceive_IT ( hal_uart_handle_t * huart )

Abort ongoing Receive transfer (Interrupt mode).

Note

This procedure could be used for aborting any ongoing Rx transfer started in Interrupt or DMA mode. This procedure performs following operations :

  • Disable UART Interrupts (Rx)

  • Disable the DMA transfer in the peripheral register (if enabled)

  • Abort DMA transfer by calling HAL_DMA_Abort_IT (in case of transfer in DMA mode)

  • Set handle rx_state to HAL_UART_RX_STATE_IDLE

  • At abort completion, call user abort complete callback

Note

This procedure is executed in Interrupt mode, meaning that abort procedure could be considered as completed only when user abort complete callback is executed (not when exiting function).

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

HAL_OK – Operation completed successfully.

Advanced IO operation functions

group UART_Exported_Functions_Group13

This subsection provides a set of functions allowing to use advanced IO operation on the USARTx instance in asynchronous modes. Prior to use advanced IO operations, one has to configure one’s instance in asynchronous mode with HAL_UART_SetConfig() .

3 specific reception methods are provided:

To send break character in LIN mode:

To send specific request:

A set of Transfer Complete Callbacks are provided in Non_Blocking mode (IT and DMA):

Non-Blocking mode transfers could be aborted using Abort API’s :

For Abort services based on interrupts (HAL_UART_Abortxxx_IT), a set of Abort Complete Callbacks are provided:

In Non-Blocking mode transfers, possible errors are split into 2 categories:

  • Error is considered as Recoverable and non blocking : Transfer could go till end, but error severity is to be evaluated by user : this concerns Frame Error, Parity Error or Noise Error in Interrupt mode reception . Received character is then retrieved and stored in Rx buffer, Error code is set to allow user to identify error type, and HAL_UART_ErrorCallback() user callback is executed. Transfer is kept ongoing on UART side. If user wants to abort it, Abort services must be called by user.

  • Error is considered as Blocking : Transfer could not be completed properly and is aborted. This concerns Overrun Error In Interrupt mode reception and all errors in DMA mode. Error code is set to allow user to identify error type, and HAL_UART_ErrorCallback() user callback is executed.

In the Half Duplex communication, it is forbidden to run the Transmit and Receive process in parallel.

Functions

hal_status_t HAL_UART_SendLINBreak ( hal_uart_handle_t * huart )

Send Break Character on the line.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

  • HAL_OK – The Break has been sent.

  • HAL_BUSY – Concurrent process ongoing.

hal_status_t HAL_UART_SendRequest ( hal_uart_handle_t * huart , hal_uart_request_t request )

Send Specific UART Request.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • request – request type to process.

Return values :

  • HAL_OK – The request has been sent.

  • HAL_BUSY – Concurrent process ongoing.

hal_status_t HAL_UART_ReceiveToIdle ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t * p_rx_size_byte , uint32_t timeout_ms )

Receive an amount of data in blocking mode till either the expected number of data is received or an IDLE event occurs.

Note

OK is returned if reception is completed (expected number of data has been received) or if reception is stopped after IDLE event (less than the expected number of data has been received) In this case, p_rx_size_byte output parameter indicates number of data available in reception buffer.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t. In this case, size must indicate the number of uint16_t available through p_data.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer (uint8_t or uint16_t data elements).

  • size_byte – Amount of data elements (uint8_t or uint16_t) to be received.

  • p_rx_size_byte – Pointer to the number of data elements finally received (could be lower than size, in case reception ends on IDLE event).

  • timeout_ms – Timeout duration expressed in ms (covers the whole reception sequence).

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_TIMEOUT – Operation exceeds user timeout.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveToIdle_IT ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte )

Receive an amount of data in interrupt mode till either the expected number of data is received or an IDLE event occurs.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to UART interrupts raised by RXNE and IDLE events. Callback is called at end of reception indicating number of received data elements.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t. In this case, size must indicate the number of uint16_t available through p_data.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer (uint8_t or uint16_t data elements).

  • size_byte – Amount of data elements (uint8_t or uint16_t) to be received.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveToIdle_IT_Opt ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t interrupts )

Receive an amount of data in interrupt mode till either the expected number of data is received or an IDLE event occurs, with Optional interrupts selection. Allows the user to enable Optional Interrupts part of UART Optional Interrupts for Receive interrupt process.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to UART interrupts raised by RXNE and IDLE events. Callback is called at end of reception indicating number of received data elements.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t. In this case, size must indicate the number of uint16_t available through p_data.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer (uint8_t or uint16_t data elements).

  • size_byte – Amount of data elements (uint8_t or uint16_t) to be received.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Receive interrupt process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveToIdle_DMA ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte )

Receive an amount of data in DMA mode till either the expected number of data is received or an IDLE event occurs.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to DMA services, transferring automatically received data elements in user reception buffer and calling registered callbacks at half/end of reception. UART IDLE events are also used to consider reception phase as ended. In all cases, callback execution will indicate number of received data elements.

Warning

When the UART parity is enabled (PCE bit from the CR1 register = 1), the received data contain the parity bit (MSB position).

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t. In this case, size must indicate the number of uint16_t available through p_data.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer (uint8_t or uint16_t data elements).

  • size_byte – Amount of data elements (uint8_t or uint16_t) to be received.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_ReceiveToIdle_DMA_Opt ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t interrupts )

Receive an amount of data in DMA mode till either the expected number of data is received or an IDLE event occurs, with Optional interrupts selection. Allows the user to enable Optional Interrupts part of UART Optional Interrupts for Receive DMA process.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to DMA services, transferring automatically received data elements in user reception buffer and calling registered callbacks at half/end of reception. UART IDLE events are also used to consider reception phase as ended. In all cases, callback execution will indicate number of received data elements.

Warning

When the UART parity is enabled (PCE bit from the CR1 register = 1), the received data contain the parity bit (MSB position).

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t. In this case, size must indicate the number of uint16_t available through p_data.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer (uint8_t or uint16_t data elements).

  • size_byte – Amount of data elements (uint8_t or uint16_t) to be received.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Receive DMA process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilTMO ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t * p_rx_size_byte , uint32_t char_timeout_bit )

Receive an amount of data in blocking mode till the timeout(TMO) expires or an amount of data is received.

Note

HAL_OK is returned if the timeout expires.

Note

This feature is not available for LPUART instances. In this case, p_rx_size_byte output parameter indicates number of data available in reception buffer.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • p_rx_size_byte – Pointer to the number of data elements finally received (could be lower than size_byte, in case reception ends on IDLE event).

  • char_timeout_bit – Timeout duration expressed in bit.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilTMO_IT ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t char_timeout_bit )

Receive an amount of data in interrupt mode till the timeout(TMO) expires or an amount of data is received.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to UART interrupts raised by RXNE and IDLE events. Callback is called at end of reception indicating number of received data elements.

Note

This feature is not available for LPUART instances.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • char_timeout_bit – Timeout duration expressed in bit.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilTMO_IT_Opt ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t char_timeout_bit , uint32_t interrupts )

Receive an amount of data in interrupt mode till the timeout(TMO) expires or an amount of data is received, with Optional interrupts selection. Allows the user to enable Optional Interrupts part of UART Optional Interrupts for Receive interrupt process.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to UART interrupts raised by RXNE and IDLE events. Callback is called at end of reception indicating number of received data elements.

Note

This feature is not available for LPUART instances.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • char_timeout_bit – Timeout duration expressed in bit.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Receive interrupt process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilTMO_DMA ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t char_timeout_bit )

Receive an amount of data in DMA mode till the timeout(TMO) expires or an amount of data is received.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to DMA services, transferring automatically received data elements in user reception buffer and calling registered callbacks at half/end of reception. UART IDLE events are also used to consider reception phase as ended. In all cases, callback execution will indicate number of received data elements.

Note

This feature is not available for LPUART instances.

Warning

When the UART parity is enabled (PCE bit from the CR1 register = 1), the received data contain the parity bit (MSB position).

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • char_timeout_bit – Timeout duration expressed in bit.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilTMO_DMA_Opt ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint32_t char_timeout_bit , uint32_t interrupts )

Receive an amount of data in DMA mode till the timeout(TMO) expires or an amount of data is received, with Optional interrupts selection. Allows the user to enable Optional Interrupts part of UART Optional Interrupts for Receive DMA process.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to DMA services, transferring automatically received data elements in user reception buffer and calling registered callbacks at half/end of reception. UART IDLE events are also used to consider reception phase as ended. In all cases, callback execution will indicate number of received data elements.

Note

This feature is not available for LPUART instances.

Warning

When the UART parity is enabled (PCE bit from the CR1 register = 1), the received data contain the parity bit (MSB position).

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • char_timeout_bit – Timeout duration expressed in bit.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Receive DMA process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilCM ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint8_t character , uint32_t * p_rx_size_byte , uint32_t timeout_ms )

Receive an amount of data in blocking mode till the character passed in parameters match the received sequence or an amount of data is received. In this case, p_rx_size_byte output parameter indicates number of data available in reception buffer.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • character – Character to match in the received sequence.

  • p_rx_size_byte – Pointer to the number of data elements finally received.

  • timeout_ms – Timeout duration expressed in ms (covers the whole reception sequence).

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_TIMEOUT – Operation exceeds user timeout.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilCM_IT ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint8_t character )

Receive an amount of data in interrupt mode till the character passed in parameters match the received sequence or an amount of data is received.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to UART interrupts raised by RXNE and IDLE events. Callback is called at end of reception indicating number of received data elements.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • character – Character to match in the received sequence.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilCM_IT_Opt ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint8_t character , uint32_t interrupts )

Receive an amount of data in interrupt mode till the character passed in parameters match the received sequence or an amount of data is received, with Optional interrupts selection. Allows the user to enable Optional Interrupts part of UART Optional Interrupts for Receive interrupt process.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to UART interrupts raised by RXNE and IDLE events. Callback is called at end of reception indicating number of received data elements.

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • character – Character to match in the received sequence.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Receive interrupt process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilCM_DMA ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint8_t character )

Receive an amount of data in DMA mode till the character passed in parameters match the received sequence or an amount of data is received.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to DMA services, transferring automatically received data elements in user reception buffer and calling registered callbacks at half/end of reception. UART IDLE events are also used to consider reception phase as ended. In all cases, callback execution will indicate number of received data elements.

Warning

When the UART parity is enabled (PCE bit from the CR1 register = 1), the received data contain the parity bit (MSB position).

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • character – Character to match in the received sequence.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – DMA handler not set or Error during instance enabling.

hal_status_t HAL_UART_ReceiveUntilCM_DMA_Opt ( hal_uart_handle_t * huart , void * p_data , uint32_t size_byte , uint8_t character , uint32_t interrupts )

Receive an amount of data in DMA mode till the character passed in parameters match the received sequence or an amount of data is received, with Optional interrupts selection. Allows the user to enable Optional Interrupts part of UART Optional Interrupts for Receive DMA process.

Note

Reception is initiated by this function call. Further progress of reception is achieved thanks to DMA services, transferring automatically received data elements in user reception buffer and calling registered callbacks at half/end of reception. UART IDLE events are also used to consider reception phase as ended. In all cases, callback execution will indicate number of received data elements.

Warning

When the UART parity is enabled (PCE bit from the CR1 register = 1), the received data contain the parity bit (MSB position).

Warning

When UART parity is not enabled (PCE bit from the CR1 register = 0), and Word Length is configured to 9 bits (M1-M0 from the CR1 register = 01), the received data is handled as a set of uint16_t.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data elements to be received.

  • character – Character to match in the received sequence.

  • interrupts – Optional interrupts part of UART Optional Interrupts for Receive DMA process.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – DMA handler not set or Error during instance enabling.

Peripheral current frequency, state and error functions

group UART_Exported_Functions_Group14

This subsection provides functions allowing to read the current frequency, state and last occurred errors of USARTx in asynchronous mode :

Functions

uint32_t HAL_UART_GetClockFreq ( const hal_uart_handle_t * huart )

Return the peripheral clock frequency for UART.

Parameters :

huart – Pointer to a hal_uart_handle_t structure that contains the configuration information for UART module.

Return values :

  • uint32_t – Frequency in Hz.

  • 0 – source clock of the huart not configured or not ready.

hal_uart_state_t HAL_UART_GetState ( const hal_uart_handle_t * huart )

Return the UART handle state.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_state_t – UART state

hal_uart_tx_state_t HAL_UART_GetTxState ( const hal_uart_handle_t * huart )

Return the HAL UART Tx process state.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_tx_state_t – UART Tx process state

hal_uart_rx_state_t HAL_UART_GetRxState ( const hal_uart_handle_t * huart )

Return the HAL UART Rx process state.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

hal_uart_rx_state_t – UART Rx process state

uint32_t HAL_UART_GetLastErrorCodes ( const hal_uart_handle_t * huart )

Return the UART last errors.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

Current – Last Errors Codes

Bus Operation Function

group UART_Exported_Functions_Group15

This subsection provides functions allowing to control the bus of the USARTx instance:

For multi task application, it is strongly recommended to use the bus operation functions to avoid race concurrency.

Functions

hal_status_t HAL_UART_AcquireBus ( hal_uart_handle_t * huart , uint32_t timeout_ms )

Acquire the current instance bus.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • timeout_ms – Timeout in milliseconds for the Acquire to expire.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

hal_status_t HAL_UART_ReleaseBus ( hal_uart_handle_t * huart )

Release the current instance bus.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

User Data Function

group UART_Exported_Functions_Group16

This subsection provides functions allowing to set user specific data to a USARTx instance:

Functions

void HAL_UART_SetUserData ( hal_uart_handle_t * huart , const void * p_user_data )

Store User Data pointer into the handle.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • p_user_data – Pointer to the user data.

const void * HAL_UART_GetUserData ( const hal_uart_handle_t * huart )

Retrieve User Data pointer from the handle.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Return values :

Pointer – to the user data.

IRQ handling

group UART_Exported_Functions_Group17

This subsection provides the function handling the interruption of the USARTx in asynchronous mode.

HAL_UART_IRQHandler() is designed to process the different interruptions in the following order:

  • Error on Rx side (PE, FE, ORE, NE, RTOF)

  • Error on DMA side

  • Data on Rx side

  • Data on Tx side

Depending on the process function (_Opt included) one’s use, different callback might be triggered:

Process API

\

Callbacks

HAL_UART_Transmit_IT

HAL_UART_Receive_IT

HAL_UART_TxCpltCallback

x

HAL_UART_RxCpltCallback

x

HAL_UART_ErrorCallback

x

x

Process API

\

Callbacks

HAL_UART_Transmit_DMA

HAL_UART_Receive_DMA

HAL_UART_TxHalfCpltCallback*

x

HAL_UART_TxCpltCallback

x

HAL_UART_RxHalfCpltCallback*

x

HAL_UART_RxCpltCallback

x

HAL_UART_ErrorCallback**

x

x

Process API

\

Callbacks

HAL_UART_Abort_IT

HAL_UART_AbortTransmit_IT

HAL_UART_AbortReceive_IT

HAL_UART_AbortCpltCallback

x

HAL_UART_AbortTransmitCpltCallback

x

HAL_UART_AbortReceiveCpltCallback

x

HAL_UART_ErrorCallback

x

x

x

Process API

\

Callbacks

HAL_UART_ReceiveToIdle_IT

HAL_UART_ReceiveUntilTMO_IT

HAL_UART_RxCpltCallback

x

x

HAL_UART_ErrorCallback

x

x

Process API

\

Callbacks

HAL_UART_ReceiveUntilCM_IT

HAL_UART_RxCpltCallback

x

HAL_UART_ErrorCallback

x

Process API

\

Callbacks

HAL_UART_ReceiveToIdle_DMA

HAL_UART_ReceiveUntilTMO_DMA

HAL_UART_RxHalfCpltCallback

x

x

HAL_UART_RxCpltCallback

x

x

HAL_UART_ErrorCallback

x

x

Process API

\

Callbacks

HAL_UART_ReceiveUntilCM_DMA

HAL_UART_RxHalfCpltCallback

x

HAL_UART_RxCpltCallback

x

HAL_UART_ErrorCallback

x

Process API

\

Callbacks

HAL_UART_EnableLINMode

HAL_UART_LINBreakCallback

x

Note

* these callbacks might be called following DMA IRQ management, not USARTx IRQ management.

Note

** these callbacks might be called following DMA IRQ management, or USARTx IRQ management.

Functions

void HAL_UART_IRQHandler ( hal_uart_handle_t * huart )

Handle UART interrupt request.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

Default Callbacks

group UART_Exported_Functions_Group18

This subsection provides the default weak callbacks of the USARTx instance. Refer to HAL_UART_IRQHandler() documentation to get the details of which callback is triggered for each process functions. One can refer to the “How to use the UART HAL module driver” section to find the association between callbacks, registration function and default callback values.

Functions

void HAL_UART_TxCpltCallback ( hal_uart_handle_t * huart )

Tx Transfer completed callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_TxHalfCpltCallback ( hal_uart_handle_t * huart )

Tx Half Transfer completed callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_RxCpltCallback ( hal_uart_handle_t * huart , uint32_t size_byte , hal_uart_rx_event_types_t rx_event )

Rx Transfer completed callback.

Parameters :

  • huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

  • size_byte – number of bytes received

  • rx_event – event which triggered the callback

void HAL_UART_RxHalfCpltCallback ( hal_uart_handle_t * huart )

Rx Half Transfer completed callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_ErrorCallback ( hal_uart_handle_t * huart )

UART error callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_AbortCpltCallback ( hal_uart_handle_t * huart )

UART Abort Complete callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_AbortTransmitCpltCallback ( hal_uart_handle_t * huart )

UART Abort Transmit Complete callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_AbortReceiveCpltCallback ( hal_uart_handle_t * huart )

UART Abort Receive Complete callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_RxFifoFullCallback ( hal_uart_handle_t * huart )

UART Rx Fifo full callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_TxFifoEmptyCallback ( hal_uart_handle_t * huart )

UART Tx Fifo empty callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_LINBreakCallback ( hal_uart_handle_t * huart )

UART LIN break callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.

void HAL_UART_ClearToSendCallback ( hal_uart_handle_t * huart )

UART Clear to send callback.

Parameters :

huart – Pointer to a hal_uart_handle_t structure which contains the UART instance.