HAL USART Functions

Initialization and de-initialization functions

group USART_Exported_Functions_Group1

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

  • Call the function HAL_USART_Init() to initialize the selected USART handle and associate an instance.

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

Functions

hal_status_t HAL_USART_Init ( hal_usart_handle_t * husart , hal_usart_t instance )

Initialize the USART handler for the associated instance.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which will contains the USART instance.

  • instance – USART instance.

Return values :

  • HAL_OK – USART instance has been correctly initialized

  • HAL_INVALID_PARAM – USART instance is NULL

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

void HAL_USART_DeInit ( hal_usart_handle_t * husart )

Deinitialize the USART handler, reset the flags, states and counters.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Basic configuration functions

group USART_Exported_Functions_Group2

This subsection provides a set of functions allowing to configure the USART in synchronous mode.

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

USART frame format.
  +-----------------------------------------------------------------------+
  |  M1 bit |  M0 bit |  PCE bit  |             USART 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 |     |
  +-----------------------------------------------------------------------+
Acronym definition :
- STB (Stop Bit)
- SB (Start Bit)
- PB (Parity Bit)

Warning

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

Warning

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

Functions

hal_status_t HAL_USART_SetConfig ( hal_usart_handle_t * husart , const hal_usart_config_t * p_config )

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

Parameters :
Return values :

  • HAL_OK – USART instance has been correctly configured.

  • HAL_INVALID_PARAM – p_config is NULL.

  • HAL_ERROR – Error during instance enabling or kernel clock not enabled.

void HAL_USART_GetConfig ( const hal_usart_handle_t * husart , hal_usart_config_t * p_config )

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

Parameters :
hal_status_t HAL_USART_SetWordLength ( const hal_usart_handle_t * husart , hal_usart_word_length_t word_length )

Set the Word Length configuration set as parameter into the handler instance registers.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • word_length – Word length to be applied.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_word_length_t HAL_USART_GetWordLength ( const hal_usart_handle_t * husart )

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_word_length_t – Current Word length configuration.

hal_status_t HAL_USART_SetParity ( const hal_usart_handle_t * husart , hal_usart_parity_t parity )

Set the Parity configuration set as parameter into the handler instance registers.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • parity – Parity to be applied.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_parity_t HAL_USART_GetParity ( const hal_usart_handle_t * husart )

Get the Parity configuration according to the handler instance registers.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_parity_t – Current Parity configuration.

hal_status_t HAL_USART_SetStopBits ( const hal_usart_handle_t * husart , hal_usart_stop_bits_t stop_bits )

Set the Stop Bits configuration set as parameter into the handler instance registers.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • stop_bits – Stop Bits to be applied.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_stop_bits_t HAL_USART_GetStopBits ( const hal_usart_handle_t * husart )

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_stop_bits_t – Current Stop Bits configuration.

hal_status_t HAL_USART_SetXferDirection ( const hal_usart_handle_t * husart , hal_usart_direction_t xfer_direction )

Set the XFer Direction configuration set as parameter into the handler instance registers.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • xfer_direction – XFer Direction to be applied.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_direction_t HAL_USART_GetXferDirection ( const hal_usart_handle_t * husart )

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_direction_t – Current XFer Direction configuration.

hal_status_t HAL_USART_SetClockPolarity ( const hal_usart_handle_t * husart , hal_usart_clock_polarity_t clock_polarity )

Set the Clock polarity configuration set as parameter into the handler instance registers.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • clock_polarity – Clock polarity to be applied.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_clock_polarity_t HAL_USART_GetClockPolarity ( const hal_usart_handle_t * husart )

Get the Clock polarity configuration according to the handler instance registers.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_clock_polarity_t – Current Clock polarity configuration.

hal_status_t HAL_USART_SetClockPhase ( const hal_usart_handle_t * husart , hal_usart_clock_phase_t clock_phase )

Set the Clock phase configuration set as parameter into the handler instance registers.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • clock_phase – Clock phase to be applied.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_clock_phase_t HAL_USART_GetClockPhase ( const hal_usart_handle_t * husart )

Get the Clock phase configuration according to the handler instance registers.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_clock_phase_t – Current Clock phase configuration.

hal_status_t HAL_USART_SetLastBitClockPulse ( const hal_usart_handle_t * husart , hal_usart_clock_last_bit_state_t clock_last_bit )

Set the last bit clock pulse configuration set as parameter into the handler instance registers (used in USART Synchronous SPI master mode only).

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • clock_last_bit – Last bit clock pulse configuration to be applied.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_clock_last_bit_state_t HAL_USART_GetLastBitClockPulse ( const hal_usart_handle_t * husart )

Get the last bit clock pulse configuration according to the handler instance registers.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_clock_last_bit_state_t – Current last bit clock pulse configuration.

hal_status_t HAL_USART_SetBaudRate ( const hal_usart_handle_t * husart , uint32_t baud_rate )

Set the Baud Rate configuration set as parameter into the handler instance registers.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • baud_rate – Baud rate value to set.

Return values :

  • HAL_OK – USART instance has been correctly configured.

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

uint32_t HAL_USART_GetBaudRate ( const hal_usart_handle_t * husart )

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

uint32_t – Current baud rate value.

hal_status_t HAL_USART_SetMode ( hal_usart_handle_t * husart , hal_usart_mode_t mode )

Set the Mode configuration set as parameter into the handler instance registers.

Warning

When the USART operates in SPI slave mode, it handles data flow using the serial interface clock derived from the external SCLK signal provided by the external master SPI device.

Warning

In SPI slave mode, the USART must be enabled before starting the master communications (or between frames while the clock is stable). Otherwise, if the USART slave is enabled while the master is in the middle of a frame, it will become desynchronized with the master.

Warning

The data register of the slave needs to be ready before the first edge of the communication clock or before the end of the ongoing communication, otherwise the SPI slave will transmit zeros.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • mode – Mode value to set.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_mode_t HAL_USART_GetMode ( const hal_usart_handle_t * husart )

Get the Mode configuration according to the handler instance registers.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_mode_t – Current mode value.

Autonomous Mode functions

group USART_Exported_Functions_Group4

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 synchronous mode with HAL_USART_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_USART_AM_EnablePacketTrigger ( const hal_usart_handle_t * husart )

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

Warning

When using this API, Transmit Enable (TE) bit in register USART_CR1 will be reset to let the autonomous mode controlling it.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_status_t HAL_USART_AM_DisablePacketTrigger ( const hal_usart_handle_t * husart )

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

Warning

When using this API, Transmit Enable (TE) bit in register USART_CR1 be set back for the standard mode to be functional.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_am_packet_trig_status_t HAL_USART_AM_IsEnabledPacketTrigger ( const hal_usart_handle_t * husart )

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

Current – Autonomous Mode Packet Trigger status.

hal_status_t HAL_USART_AM_SetConfigPacketTrigger ( const hal_usart_handle_t * husart , const hal_usart_am_config_t * p_config )

Set the USART Autonomous Packet Trigger configuration set as parameter into the handler instance registers.

Parameters :
Return values :

  • HAL_OK – USART instance has been correctly configured.

  • HAL_INVALID_PARAM – p_config is NULL.

void HAL_USART_AM_GetConfigPacketTrigger ( const hal_usart_handle_t * husart , hal_usart_am_config_t * p_config )

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

Parameters :
hal_status_t HAL_USART_AM_EnableIdle ( const hal_usart_handle_t * husart )

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_status_t HAL_USART_AM_DisableIdle ( const hal_usart_handle_t * husart )

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_am_idle_frame_status_t HAL_USART_AM_IsEnabledIdle ( const hal_usart_handle_t * husart )

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_am_idle_frame_status_t – Current Autonomous Mode Idle Frame Sending status.

Advanced configuration functions

group USART_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 synchronous mode with HAL_USART_SetConfig() .

One can configure some features by calling the associated functions:

Functions

hal_status_t HAL_USART_SetSlaveSelect ( const hal_usart_handle_t * husart , hal_usart_slave_select_config_t slave_select )

Set the Slave select configuration set as parameter into the handler instance registers.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • slave_select – Slave select to be applied.

Return values :

HAL_OK – USART instance has been correctly configured.

hal_usart_slave_select_config_t HAL_USART_GetSlaveSelect ( const hal_usart_handle_t * husart )

Get the Slave select configuration according to the handler instance registers.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_slave_select_config_t – Current Slave select configuration.

DMA Configuration functions

group USART_Exported_Functions_Group6

This subsection provides a set of functions allowing to link the HAL USART 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_USART_SetTxDMA ( hal_usart_handle_t * husart , 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_USART_SetRxDMA ( hal_usart_handle_t * husart , 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 USART_Exported_Functions_Group7

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 synchronous mode with HAL_USART_SetConfig() . A set of functions is provided to configure the callbacks:

Functions

hal_status_t HAL_USART_RegisterTxHalfCpltCallback ( hal_usart_handle_t * husart , hal_usart_cb_t p_callback )

Register the USART Tx Half Complete Callback.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_RegisterTxCpltCallback ( hal_usart_handle_t * husart , hal_usart_cb_t p_callback )

Register the USART Tx Complete Callback.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_RegisterRxHalfCpltCallback ( hal_usart_handle_t * husart , hal_usart_cb_t p_callback )

Register the USART Rx Half Complete Callback.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_RegisterRxCpltCallback ( hal_usart_handle_t * husart , hal_usart_cb_t p_callback )

Register the USART Rx Complete Callback.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_RegisterTxRxCpltCallback ( hal_usart_handle_t * husart , hal_usart_cb_t p_callback )

Register the USART Tx/Rx Complete Callback.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_RegisterErrorCallback ( hal_usart_handle_t * husart , hal_usart_cb_t p_callback )

Register the USART Error Callback.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_RegisterAbortCpltCallback ( hal_usart_handle_t * husart , hal_usart_cb_t p_callback )

Register the USART Abort Complete Callback.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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.

IO operation functions

group USART_Exported_Functions_Group8

This subsection provides a set of functions allowing to manage the USART synchronous data transfers.

The USART Synchronous SPI supports master and slave modes. In Master mode, SCLK is always an output, and is generated by transmission. This means that in order to achieve a reception in Master mode, a transmission (0x0F) must be performed simultaneously (full duplex). In Slave mode, SCLK is an input.

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.

  • No-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 USART IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_USART_TxCpltCallback() , HAL_USART_RxCpltCallback() and HAL_USART_TxRxCpltCallback() user callbacks will be executed respectively at the end of the Transmit or Receive process The HAL_USART_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 :

No-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_USART_Abort_IT() ), an Abort Complete Callbacks is 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 :

    • If Parity Error flag is detected in interrupt mode reception: Received character is then retrieved and stored in Rx buffer, Error code is set to allow the user to identify the error type, HAL_USART_ErrorCallback() user callback is then executed.

  • Error is considered as Blocking : Transfer could not be completed properly and is aborted.

    • If global state is HAL_USART_STATE_RX_ACTIVE: This concerns Overrun Error in Interrupt mode and all errors in DMA mode.

    • If global state is HAL_USART_STATE_TX_ACTIVE: This concerns Underrun Error in Interrupt mode and in DMA mode.

    • If global state is HAL_USART_STATE_TX_RX_ACTIVE: This concerns Overrun Error in Interrupt mode and in DMA mode. In all cases, HAL_USART_ErrorCallback() user callback is executed and error code is set to allow user to identify error type if USE_HAL_USART_GET_LAST_ERRORS=1.

Functions

hal_status_t HAL_USART_Transmit ( hal_usart_handle_t * husart , const void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Send an amount of data in blocking mode.

Warning

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

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_Receive ( hal_usart_handle_t * husart , void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Receive an amount of data in blocking mode.

Warning

If USART is configured in Master mode, to receive synchronous data, dummy data are simultaneously transmitted.

Warning

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

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_TransmitReceive ( hal_usart_handle_t * husart , const void * p_tx_data , void * p_rx_data , uint32_t size_byte , uint32_t timeout_ms )

Full-duplex send and receive an amount of data in blocking mode.

Warning

When USART parity is not enabled (PCE bit in register USART_CR1 = 0), and Word Length is configured to 9 bits (M1-M0 = 01), the sent data and the received data are handled as sets of u16.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_tx_data – Pointer to TX data buffer.

  • p_rx_data – Pointer to RX data buffer.

  • size_byte – Amount of bytes to be sent (same amount 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_USART_Transmit_IT ( hal_usart_handle_t * husart , const void * p_data , uint32_t size_byte )

Send an amount of data in interrupt mode.

Warning

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

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_Receive_IT ( hal_usart_handle_t * husart , void * p_data , uint32_t size_byte )

Receive an amount of data in interrupt mode.

Warning

If USART is configured in Master mode, to receive synchronous data, dummy data are simultaneously transmitted.

Warning

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

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_TransmitReceive_IT ( hal_usart_handle_t * husart , const void * p_tx_data , void * p_rx_data , uint32_t size_byte )

Full-duplex send and receive an amount of data in interrupt mode.

Warning

When USART parity is not enabled (PCE bit in register USART_CR1 = 0), and Word Length is configured to 9 bits (M1-M0 = 01), the sent data and the received data are handled as sets of u16.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_tx_data – Pointer to TX data buffer.

  • p_rx_data – Pointer to RX data buffer.

  • size_byte – Amount of bytes to be sent (same amount 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_USART_Transmit_DMA ( hal_usart_handle_t * husart , const void * p_data , uint32_t size_byte )

Send an amount of data in DMA mode.

Warning

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

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes.

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_USART_Transmit_DMA_Opt ( hal_usart_handle_t * husart , const void * p_data , uint32_t size_byte , uint32_t interrupts )

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

Warning

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

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of bytes.

  • interrupts – Optional interrupts part of USART 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 – Error during instance enabling.

hal_status_t HAL_USART_Receive_DMA ( hal_usart_handle_t * husart , void * p_data , uint32_t size_byte )

Receive an amount of data in DMA mode.

Warning

When the USART parity is enabled (PCE bit in register USART_CR1 = 1), the received data contains the parity bit (MSB position).

Warning

If USART is configured in Master mode, the USART DMA transmit channel must be configured in order to generate the clock for the slave.

Warning

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

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_data – Pointer to RX 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 or missing Tx DMA handle when acting as master.

hal_status_t HAL_USART_Receive_DMA_Opt ( hal_usart_handle_t * husart , 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 USART Optional Interrupts for Receive DMA process.

Warning

When the USART parity is enabled (PCE bit in register USART_CR1 = 1), the received data contains the parity bit (MSB position).

Warning

If USART is configured in Master mode, the USART DMA transmit channel must be configured in order to generate the clock for the slave.

Warning

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

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_data – Pointer to RX data buffer.

  • size_byte – Amount of bytes to be received.

  • interrupts – Optional interrupts part of USART 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 – Error during instance enabling or missing Tx DMA handle when acting as master.

hal_status_t HAL_USART_TransmitReceive_DMA ( hal_usart_handle_t * husart , const void * p_tx_data , void * p_rx_data , uint32_t size_byte )

Full-duplex transmit and receive an amount of data in non-blocking mode.

Warning

When the USART parity is enabled (PCE bit in register USART_CR1 = 1) the data received contains the parity bit.

Warning

When USART parity is not enabled (PCE bit in register USART_CR1 = 0), and Word Length is configured to 9 bits (M1-M0 = 01), the sent data and the received data are handled as sets of u16.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_tx_data – Pointer to TX data buffer.

  • p_rx_data – Pointer to RX data buffer.

  • size_byte – Amount of bytes to be sent (same amount 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_USART_TransmitReceive_DMA_Opt ( hal_usart_handle_t * husart , const void * p_tx_data , void * p_rx_data , uint32_t size_byte , uint32_t interrupts )

Full-duplex transmit and receive an amount of data in non-blocking mode, allow user to enable Optional Interrupts part of USART Optional Interrupts for TransmitReceive DMA process.

Warning

When the USART parity is enabled (PCE bit in register USART_CR1 = 1) the data received contains the parity bit.

Warning

When USART parity is not enabled (PCE bit in register USART_CR1 = 0), and Word Length is configured to 9 bits (M1-M0 = 01), the sent data and the received data are handled as sets of u16.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_tx_data – Pointer to TX data buffer.

  • p_rx_data – Pointer to RX data buffer.

  • size_byte – Amount of bytes to be sent (same amount to be received).

  • interrupts – Optional interrupts part of USART Optional Interrupts for TransmitReceive DMA 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_USART_Pause_DMA ( hal_usart_handle_t * husart )

Pause ongoing DMA transfers (Tx, Rx or both).

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_USART_Resume_DMA ( hal_usart_handle_t * husart )

Resume ongoing DMA transfers (Tx, Rx or both).

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_USART_Abort ( hal_usart_handle_t * husart )

Abort ongoing transfers (blocking mode).

Note

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

Warning

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

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_USART_Abort_IT ( hal_usart_handle_t * husart )

Abort ongoing transfers (Interrupt mode).

Note

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

Warning

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 :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_USART_SendRequest ( hal_usart_handle_t * husart , hal_usart_request_t request )

Send Specific USART Request.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • request – Request to process.

Return values :

HAL_OK – The request has been sent.

Peripheral State and Error functions

group USART_Exported_Functions_Group9

A set of functions is provided to control the states and errors:

Functions

hal_usart_state_t HAL_USART_GetState ( const hal_usart_handle_t * husart )

Return the USART handle state.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

hal_usart_state_t – USART state

uint32_t HAL_USART_GetClockFreq ( const hal_usart_handle_t * husart )

Return the peripheral clock frequency.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

  • uint32_t – Frequency in Hz.

  • 0 – source clock of the USART instance not configured or not ready

uint32_t HAL_USART_GetLastErrorCodes ( const hal_usart_handle_t * husart )

Return the USART last errors.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

Current – Last Errors Codes

Bus Operation Function

group USART_Exported_Functions_Group10

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_USART_AcquireBus ( hal_usart_handle_t * husart , uint32_t timeout_ms )

Acquire the current instance bus.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART 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_USART_ReleaseBus ( hal_usart_handle_t * husart )

Release the current instance bus.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

User Data Function

group USART_Exported_Functions_Group11

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

Functions

void HAL_USART_SetUserData ( hal_usart_handle_t * husart , const void * p_user_data )

Store User Data pointer into the handle.

Parameters :

  • husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

  • p_user_data – Pointer to the user data.

const void * HAL_USART_GetUserData ( const hal_usart_handle_t * husart )

Retrieve User Data pointer from the handle.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Return values :

Pointer – to the user data.

IRQ handling

group USART_Exported_Functions_Group12

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

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

  • Error on Rx side (PE, ORE, RTOF, UDR)

  • Error on DMA side

  • Data on Rx side

  • Data on Tx side

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

Process API

\

Callbacks

HAL_USART_Transmit_IT

HAL_USART_Receive_IT

HAL_USART_TransmitReceive_IT

HAL_USART_TxCpltCallback

x

HAL_USART_RxCpltCallback

x

HAL_USART_ErrorCallback

x

x

x

HAL_USART_TxRxCpltCallback

x

Process API

\

Callbacks

HAL_USART_Transmit_IT_Opt

HAL_USART_Receive_IT_Opt

HAL_USART_TxCpltCallback

x

HAL_USART_RxCpltCallback

x

HAL_USART_ErrorCallback

x

x

HAL_USART_TxFifoEmptyCallback*

x

HAL_USART_RxFifoFullCallback**

x

Process API

\

Callbacks

HAL_USART_TransmitReceive_IT_Opt

HAL_USART_TxRxCpltCallback

x

HAL_USART_ErrorCallback

x

HAL_USART_TxFifoEmptyCallback*

x

HAL_USART_RxFifoFullCallback**

x

Process API

\

Callbacks

HAL_USART_Transmit_DMA

HAL_USART_Receive_DMA

HAL_USART_TransmitReceive_DMA

HAL_USART_TxHalfCpltCallback*

x

x

HAL_USART_TxCpltCallback

x

HAL_USART_RxHalfCpltCallback*

x

x

HAL_USART_RxCpltCallback

x

HAL_USART_ErrorCallback**

x

x

x

HAL_USART_TxRxCpltCallback

x

Process API

\

Callbacks

HAL_USART_Transmit_DMA_Opt()

HAL_USART_Receive_DMA_Opt()

HAL_USART_TxCpltCallback

x

HAL_USART_RxCpltCallback

x

HAL_USART_ErrorCallback

x

x

HAL_USART_TxFifoEmptyCallback*

x

HAL_USART_RxFifoFullCallback**

x

HAL_USART_TxHalfCpltCallback***

x

HAL_USART_RxHalfCpltCallback****

x

Process API

\

Callbacks

HAL_USART_TransmitReceive_DMA_Opt()

HAL_USART_TxRxCpltCallback

x

HAL_USART_ErrorCallback

x

HAL_USART_TxFifoEmptyCallback*

x

HAL_USART_RxFifoFullCallback**

x

HAL_USART_TxHalfCpltCallback***

x

HAL_USART_RxHalfCpltCallback****

x

Process API

\

Callbacks

HAL_USART_Abort_IT

HAL_USART_AbortCpltCallback

x

Note

* with HAL_USART_OPT_TX_IT_FIFO_EMPTY arguments value for interrupts parameter

Note

** with HAL_USART_OPT_RX_IT_FIFO_FULL arguments value for interrupts parameter

Note

* with HAL_USART_OPT_TXRX_TX_IT_FIFO_EMPTY argument value for interrupts parameter

Note

** with HAL_USART_OPT_TXRX_RX_IT_FIFO_FULL argument value for interrupts parameter

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.

Note

* with HAL_USART_OPT_TX_IT_FIFO_EMPTY arguments value for interrupts parameter

Note

** with HAL_USART_OPT_RX_IT_FIFO_FULL arguments value for interrupts parameter

Note

*** with HAL_USART_OPT_DMA_TX_IT_HT arguments value for interrupts parameter

Note

**** with HAL_USART_OPT_DMA_RX_IT_HT arguments value for interrupts parameter

Note

* with HAL_USART_OPT_TXRX_TX_IT_FIFO_EMPTY arguments value for interrupts parameter

Note

** with HAL_USART_OPT_TXRX_RX_IT_FIFO_FULL arguments value for interrupts parameter

Note

*** with HAL_USART_OPT_DMA_TXRX_TX_IT_HT arguments value for interrupts parameter

Note

**** with HAL_USART_OPT_DMA_TXRX_RX_IT_HT arguments value for interrupts parameter

Functions

void HAL_USART_IRQHandler ( hal_usart_handle_t * husart )

Handle USART interrupt request.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

Default Callbacks

group USART_Exported_Functions_Group13

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

Callback name

Default value

TxHalfCpltCallback

HAL_USART_TxHalfCpltCallback()

TxCpltCallback

HAL_USART_TxCpltCallback()

RxHalfCpltCallback

HAL_USART_RxHalfCpltCallback()

RxCpltCallback

HAL_USART_RxCpltCallback()

ErrorCallback

HAL_USART_ErrorCallback()

AbortCpltCallback

HAL_USART_AbortCpltCallback()

TxRxCpltCallback

HAL_USART_TxRxCpltCallback()

RxFifoFullCallback

HAL_USART_RxFifoFullCallback()

TxFifoEmptyCallback

HAL_USART_TxFifoEmptyCallback()

Functions

void HAL_USART_TxCpltCallback ( hal_usart_handle_t * husart )

Tx Transfer completed callback.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

void HAL_USART_TxHalfCpltCallback ( hal_usart_handle_t * husart )

Tx Half Transfer completed callback.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

void HAL_USART_RxCpltCallback ( hal_usart_handle_t * husart )

Rx Transfer completed callback.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

void HAL_USART_RxHalfCpltCallback ( hal_usart_handle_t * husart )

Rx Half Transfer completed callback.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

void HAL_USART_TxRxCpltCallback ( hal_usart_handle_t * husart )

Tx/Rx Transfers completed callback for the non-blocking process.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

void HAL_USART_ErrorCallback ( hal_usart_handle_t * husart )

USART error callback.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.

void HAL_USART_AbortCpltCallback ( hal_usart_handle_t * husart )

USART Abort Complete callback.

Parameters :

husart – Pointer to a hal_usart_handle_t structure which contains the USART instance.