HAL SMARTCARD How to Use ¶

group SMARTCARD_How_To_Use

How to use the SMARTCARD HAL driver : ¶

Declare a hal_smartcard_handle_t handle structure ¶

• For example: hal_smartcard_handle_t hsmartcard;

Configure the low level hardware (GPIO, CLOCK, NVIC…etc): ¶

• Enable the SMARTCARDx interface clock if you have set USE_HAL_SMARTCARD_CLK_ENABLE_MODEL to HAL_CLK_ENABLE_NO (in other cases HAL_SMARTCARD_Init() will enable the clock).

• SMARTCARDx pins configuration :

  • Enable the clock for the SMARTCARDx GPIOs

    • Configure SMARTCARDx pins as alternate function open-drain

  • NVIC configuration if you need to use interrupt process

    • Configure the SMARTCARDx interrupt priority

    • Enable the NVIC SMARTCARDx IRQ Channel

Initialize the SMARTCARDx driver with an USART HW instance ¶

• Call HAL_SMARTCARD_Init() function with the selected instance

• The SMARTCARDx clock is enabled inside the HAL_SMARTCARD_Init() if USE_HAL_SMARTCARD_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO.

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 and/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 BlockLength (in bytes)

  All these advanced configurations are optional (not mandatory) if not called, default values will apply.

For SMARTCARDx IO operations modes, polling, interrupt and DMA are available ¶

within this driver.

• Polling mode IO 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 IO operation

  • Send an amount of data in non-blocking mode using HAL_SMARTCARD_Transmit_IT()

  • At transmission end of transfer HAL_SMARTCARD_TxCpltCallback() is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_TxCpltCallback()

  • Receive an amount of data in non-blocking mode using HAL_SMARTCARD_Receive_IT()

  • At reception end of transfer HAL_SMARTCARD_RxCpltCallback() is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_RxCpltCallback()

  • In case of transfer Error, HAL_SMARTCARD_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_ErrorCallback()

• DMA mode IO operation

  • Send an amount of data in non-blocking mode (DMA) using HAL_SMARTCARD_Transmit_DMA()

  • At transmission half of transfer HAL_SMARTCARD_TxHalfCpltCallback() is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_TxHalfCpltCallback()

  • At transmission end of transfer HAL_SMARTCARD_TxCpltCallback() is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_TxCpltCallback()

  • Receive an amount of data in non-blocking mode (DMA) using HAL_SMARTCARD_Receive_DMA()

  • At reception half of transfer HAL_SMARTCARD_RxHalfCpltCallback() is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_RxHalfCpltCallback()

  • At reception end of transfer HAL_SMARTCARD_RxCpltCallback() is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_RxCpltCallback()

  • In case of transfer Error, HAL_SMARTCARD_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_ErrorCallback()

• Different sequential SMARTCARD interfaces are listed below:

  • Abort a polling SMARTCARD process communication using HAL_SMARTCARD_Abort()

  • Abort a IT SMARTCARD process communication with Interrupt using HAL_SMARTCARD_Abort_IT()

  • End of abort IT process, HAL_SMARTCARD_AbortCpltCallback() is executed and users can add their own code by customization of function pointer HAL_SMARTCARD_AbortCpltCallback()

Callback registration ¶

• When the compilation flag USE_HAL_SMARTCARD_REGISTER_CALLBACKS is set to 1, it allows the user to configure dynamically the driver callbacks 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()

• If one needs 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 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 SMARTCARD bus ¶

• When the compilation flag USE_HAL_MUTEX is set to 1, it allows the user to acquire/reserve the whole SMARTCARD Interface for executing process. The HAL Acquire/Release are based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal) :

  • HAL_SMARTCARD_AcquireBus() for acquire the bus or wait for it.

  • HAL_SMARTCARD_ReleaseBus() for releasing the bus.

• 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 case, etu (Elementary Time Unit) is equivalent to the baud period duration