HAL SMARTCARD How to Use ¶

group SMARTCARD_How_To_Use

How to use the SMARTCARD HAL module driver ¶

The SMARTCARD HAL driver can be used as follows:

Declare a hal_smartcard_handle_t handle structure, for example: hal_smartcard_handle_t hsmartcard;
Initialize the SMARTCARDx driver with a USART HW instance by calling the HAL_SMARTCARD_Init(). The SMARTCARDx clock is enabled inside the HAL_SMARTCARD_Init() if USE_HAL_SMARTCARD_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO.
Configure the low-level hardware (GPIO, CLOCK, NVIC, etc.):
- Enable the SMARTCARDx interface clock when USE_HAL_SMARTCARD_CLK_ENABLE_MODEL is set to HAL_CLK_ENABLE_NO.
- Configure SMARTCARDx pins:
  - Enable the clock for the SMARTCARDx GPIOs
  - Configure SMARTCARDx pins as alternate-function open-drain
- Configure the NVIC for interrupt processing:
  - Configure the SMARTCARDx interrupt priority
  - Enable the NVIC SMARTCARDx IRQ Channel
Configure the communication baud rate, stop bit, first bit, parity mode, NACK, smartcard clock prescaler, source clock prescaler, clock polarity, clock phase, clock output enabling, guard time and auto retry count by calling HAL_SMARTCARD_SetConfig().

Configure or enable advanced features:
- HAL_SMARTCARD_EnableIOInvert() to invert the IO pin active level logic
- HAL_SMARTCARD_EnableDataInvert() to invert the binary data logic
- HAL_SMARTCARD_EnableTxRxSwap() to change the GPIO used (USART Tx by default)
- HAL_SMARTCARD_EnableRxOverRunDetection() to detect Rx Overrun errors
- HAL_SMARTCARD_EnableDMAStopOnRxError() to stop DMA on Rx error
- HAL_SMARTCARD_SetReceiverTimeout() to set the Rx timeout value
- HAL_SMARTCARD_EnableReceiverTimeout() to detect Rx timeout
- HAL_SMARTCARD_SetTxCpltIndication() to change the Tx complete indication
- HAL_SMARTCARD_EnableFifoMode() to change the FIFO mode status
- HAL_SMARTCARD_SetTxFifoThreshold() to set the Tx FIFO threshold
- HAL_SMARTCARD_SetRxFifoThreshold() to set the Rx FIFO threshold
- HAL_SMARTCARD_SetBlockLength() to set the block length (in bytes)
All these advanced configurations are optional. If not called, default values apply.
For SMARTCARDx I/O operations, polling, interrupt, and DMA are available in this driver.
- Polling-mode I/O operation
  - Send an amount of data in blocking mode using HAL_SMARTCARD_Transmit()
  - Receive an amount of data in blocking mode using HAL_SMARTCARD_Receive()
  - The communication is performed in polling mode. The HAL status of all data processing is returned by the same function after finishing transfer.
- Interrupt-mode I/O operation
  - Send an amount of data in non-blocking mode using HAL_SMARTCARD_Transmit_IT()
  - At the end of transmission, execute HAL_SMARTCARD_TxCpltCallback(). Customize the associated function pointer to add application-specific code.
  - Receive an amount of data in non-blocking mode using HAL_SMARTCARD_Receive_IT()
  - At the end of reception, execute HAL_SMARTCARD_RxCpltCallback(). Customize the associated function pointer to add application-specific code.
  - On transfer error, execute HAL_SMARTCARD_ErrorCallback(). Customize the associated function pointer to add application-specific code.
- DMA-mode I/O operation
  - Send an amount of data in non-blocking mode (DMA) using HAL_SMARTCARD_Transmit_DMA()
  - At the half-transfer point, execute HAL_SMARTCARD_TxHalfCpltCallback(). Customize the associated function pointer to add application-specific code.
  - At the end of transmission, execute HAL_SMARTCARD_TxCpltCallback(). Customize the associated function pointer to add application-specific code.
  - Receive an amount of data in non-blocking mode (DMA) using HAL_SMARTCARD_Receive_DMA()
  - At the half-transfer point, execute HAL_SMARTCARD_RxHalfCpltCallback(). Customize the associated function pointer to add application-specific code.
  - At the end of reception, execute HAL_SMARTCARD_RxCpltCallback(). Customize the associated function pointer to add application-specific code.
  - On transfer error, execute HAL_SMARTCARD_ErrorCallback(). Customize the associated function pointer to add application-specific code.
- The following sequential SMARTCARD interfaces are available:
  - Abort a polling SMARTCARD communication process using HAL_SMARTCARD_Abort().
  - Abort an IT SMARTCARD communication process using interrupts with HAL_SMARTCARD_Abort_IT().
  - At the end of the abort IT process, execute HAL_SMARTCARD_AbortCpltCallback(). Customize the associated function pointer to add application-specific code.
Callback registration
- When the compilation flag USE_HAL_SMARTCARD_REGISTER_CALLBACKS is set to 1, it allows the user to configure the driver callbacks dynamically via its own method:

Callback name	Default value	Callback registration function
TxHalfCpltCallback	HAL_SMARTCARD_TxHalfCpltCallback()	HAL_SMARTCARD_RegisterTxHalfCpltCallback()
TxCpltCallback	HAL_SMARTCARD_TxCpltCallback()	HAL_SMARTCARD_RegisterTxCpltCallback()
RxHalfCpltCallback	HAL_SMARTCARD_RxHalfCpltCallback()	HAL_SMARTCARD_RegisterRxHalfCpltCallback()
RxCpltCallback	HAL_SMARTCARD_RxCpltCallback()	HAL_SMARTCARD_RegisterRxCpltCallback()
ErrorCallback	HAL_SMARTCARD_ErrorCallback()	HAL_SMARTCARD_RegisterErrorCallback()
AbortCpltCallback	HAL_SMARTCARD_AbortCpltCallback()	HAL_SMARTCARD_RegisterAbortCpltCallback()
RxFifoFullCallback	HAL_SMARTCARD_RxFifoFullCallback()	HAL_SMARTCARD_RegisterRxFifoFullCallback()
TxFifoEmptyCallback	HAL_SMARTCARD_TxFifoEmptyCallback()	HAL_SMARTCARD_RegisterTxFifoEmptyCallback()

To unregister a callback, register the default callback via the registration function.
By default, after the HAL_SMARTCARD_Init() and when the state is HAL_SMARTCARD_STATE_INIT, all callbacks are set to the corresponding default weak functions.
Callbacks can be registered in the handle global_state HAL_SMARTCARD_STATE_INIT and HAL_SMARTCARD_STATE_CONFIGURED.
When the compilation flag USE_HAL_SMARTCARD_REGISTER_CALLBACKS is set to 0 or not defined, the callback registration feature is not available and all callbacks are set to the corresponding weak functions.

Acquire/Release the HAL SMARTCARD handle

When the compilation flag USE_HAL_MUTEX is set to 1, a multi-threaded user application is allowed to acquire the SMARTCARD HAL handle to execute a transmit or receive process, or a sequence of transmit/receive operations. Release the SMARTCARD HAL handle when the process or sequence ends.
HAL acquire/release operations are based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal):
- HAL_SMARTCARD_AcquireBus() allows acquiring the HAL SMARTCARD handle.
- HAL_SMARTCARD_ReleaseBus() allows releasing the HAL SMARTCARD handle.
When the compilation flag USE_HAL_MUTEX is set to 0 or not defined, HAL_SMARTCARD_AcquireBus() and HAL_SMARTCARD_ReleaseBus() are not available.

Note

In SMARTCARD mode, ETU (Elementary Time Unit) is equivalent to the baud period duration