HAL SMBUS How to Use ¶

group SMBUS_How_To_Use

How to use the SMBUS HAL module driver ¶

Declare a hal_smbus_handle_t handle structure and initialize the SMBUSx driver with an I2C HW instance by calling the HAL_SMBUS_Init(). The SMBUSx clock is enabled inside the HAL_SMBUS_Init() if USE_HAL_SMBUS_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO.
Configure the low level hardware (GPIO, CLOCK, NVIC…etc):
- Enable the SMBUSx clock if USE_HAL_SMBUS_CLK_ENABLE_MODEL = HAL_CLK_ENABLE_NO
- SMBUSx pins configuration :
  - Enable the clock for the SMBUSx GPIOs
    - Configure SMBUSx pins as alternate function open-drain
  - NVIC configuration if you need to use interrupt process
    - Configure the SMBUSx interrupt priority
    - Enable the NVIC SMBUSx IRQ Channel
Configure the Communication Clock Timing (same calculation as I2C), Own Address1, Device mode by calling HAL_SMBUS_SetConfig.
Configure and/or enable advanced features. For instance, HAL_SMBUS_EnableAnalogFilter(), HAL_SMBUS_SetDigitalFilter(), HAL_SMBUS_SetConfigOwnAddress2(), HAL_SMBUS_EnableOwnAddress2(), …APIs. All these advanced configurations are optional (not mandatory).
For SMBUSx IO operations modes, only interrupt is available within this driver as the SMBUS protocol requires the application to perform exchange with a byte granularity within the slave device.
- Interrupt mode IO sequential operation. These interfaces allow to manage a sequential transfer with a repeated start condition when a direction change during transfer. A specific option field manages the different steps of a sequential transfer through hal_smbus_xfer_opt_t and are listed below
  - XXXXXXXX_WITH_PEC suffix: Those options are activated by enabling Packet Error Check with HAL_SMBUS_EnablePacketErrorCheck() and allows for the Hardware PEC comparison to happen
  - XXXXXXXX_NO_PEC suffix: Those options are activated by default or by disabling Packet Error Check using HAL_SMBUS_DisablePacketErrorCheck() and avoid the Hardware PEC comparison to happen
  - HAL_SMBUS_XFER_FIRST_AND_LAST_FRAME: No sequential, means that a stop condition is automatically generated at the end of the single sequence.
  - HAL_SMBUS_XFER_FIRST_FRAME: Sequential, this option allows to manage a sequence with start condition, address and data to transfer without a final stop condition.
  - HAL_SMBUS_XFER_FIRST_AND_NEXT_FRAME: Sequential (Master only), this option allows to manage a sequence with start condition, address and data to transfer without a final stop condition. This allows a call to the same master sequential interface several times (HAL_SMBUS_MASTER_SEQ_Transmit_IT() followed by another call to HAL_SMBUS_MASTER_SEQ_Transmit_IT())
  - HAL_SMBUS_XFER_NEXT_FRAME: Sequential, this option allows to manage a sequence with a restart condition, address and with new data to transfer if the direction change or manage only the new data to transfer if no direction change and without a final stop condition in both cases.
  - HAL_SMBUS_XFER_LAST_FRAME: Sequential, same as HAL_SMBUS_XFER_NEXT_FRAME but with a final stop condition in both cases.
  - HAL_SMBUS_XFER_OTHER_FRAME: Sequential (Master only), this option allows to manage a restart condition after each call of the same master sequential interface. User can transfer several bytes one by one with a restart with slave address between each byte using
    - HAL_SMBUS_MASTER_SEQ_Transmit_IT()
    - HAL_SMBUS_MASTER_SEQ_Receive_IT() Then usage of this option HAL_SMBUS_XFER_OTHER_AND_LAST_FRAME at the last frame to help automatic generation of STOP condition.
- Different sequential SMBUS interfaces are listed below:
  - Sequential transmit in master mode an amount of data in non-blocking mode using HAL_SMBUS_MASTER_SEQ_Transmit_IT()
  - At transmission end of current frame transfer, HAL_SMBUS_MASTER_TxCpltCallback() is executed and users can add their own code by customization of function pointer HAL_SMBUS_MASTER_TxCpltCallback()
  - Sequential receive in master SMBUS mode an amount of data in non-blocking mode using HAL_SMBUS_MASTER_SEQ_Receive_IT()
  - At reception end of current frame transfer, HAL_SMBUS_MASTER_RxCpltCallback() is executed and users can add their own code by customization of function pointer HAL_SMBUS_MASTER_RxCpltCallback()
  - Abort a master IT SMBUS process communication with Interrupt using HAL_SMBUS_MASTER_Abort_IT()
  - End of abort process, HAL_SMBUS_AbortCpltCallback() is executed and users can add their own code by customization of function pointer HAL_SMBUS_AbortCpltCallback()
  - Enable/disable the Address listen mode in slave SMBUS mode with HAL_SMBUS_SLAVE_EnableListen_IT() and HAL_SMBUS_SLAVE_DisableListen_IT()
  - When address slave SMBUS match, HAL_SMBUS_SLAVE_AddrCallback() is executed and users can add their own code to check the address Match Code and the transmission direction request by master(Write/Read).
  - At Listen mode end HAL_SMBUS_SLAVE_ListenCpltCallback() is executed and users can add their own code by customization of function pointer HAL_SMBUS_SLAVE_ListenCpltCallback()
  - Sequential transmit in slave SMBUS mode an amount of data in non-blocking mode using HAL_SMBUS_SLAVE_SEQ_Transmit_IT()
  - At transmission end of current frame transfer, HAL_SMBUS_SLAVE_TxCpltCallback() is executed and users can add their own code by customization of function pointer HAL_SMBUS_SLAVE_TxCpltCallback()
  - Sequential receive in slave SMBUS mode an amount of data in non-blocking mode using HAL_SMBUS_SLAVE_SEQ_Receive_IT()
  - At reception end of current frame transfer, HAL_SMBUS_SLAVE_RxCpltCallback() is executed and users can add their own code by customization of function pointer HAL_SMBUS_SLAVE_RxCpltCallback()
  - In case of transfer Error, HAL_SMBUS_ErrorCallback() function is executed and users can add their own code by customization of function pointer HAL_SMBUS_ErrorCallback()
  - Discard a slave SMBUS process communication using HAL_SMBUS_SLAVE_Abort_IT() macro. This action informs the Master to generate a Stop condition to discard the communication.
Callbacks definition in Interrupt
- When the compilation define USE_HAL_SMBUS_REGISTER_CALLBACKS is set to 1, the user can configure dynamically the driver callbacks, via its own method:

Callback name	Default value	Callback registration function
MASTER_TxCpltCallback	HAL_SMBUS_MASTER_TxCpltCallback()	HAL_SMBUS_MASTER_RegisterTxCpltCallback()
MASTER_RxCpltCallback	HAL_SMBUS_MASTER_RxCpltCallback()	HAL_SMBUS_MASTER_RegisterRxCpltCallback()
SLAVE_TxCpltCallback	HAL_SMBUS_SLAVE_TxCpltCallback()	HAL_SMBUS_SLAVE_RegisterTxCpltCallback()
SLAVE_RxCpltCallback	HAL_SMBUS_SLAVE_RxCpltCallback()	HAL_SMBUS_SLAVE_RegisterRxCpltCallback()
AddrMatchCallback	HAL_SMBUS_SLAVE_AddrCallback()	HAL_SMBUS_SLAVE_RegisterAddrMatchCallback()
ListenCpltCallback	HAL_SMBUS_SLAVE_ListenCpltCallback()	HAL_SMBUS_SLAVE_RegisterListenCpltCallback()
AbortCpltCallback	HAL_SMBUS_AbortCpltCallback()	HAL_SMBUS_RegisterAbortCpltCallback()
ErrorCallback	HAL_SMBUS_ErrorCallback()	HAL_SMBUS_RegisterErrorCallback()

If one needs to unregister a callback, register the default callback via the registration function.

By default, after the HAL_SMBUS_Init() and when the state is HAL_SMBUS_STATE_INIT, all callbacks are set to the corresponding default weak functions.

Callbacks can be registered in handle global_state HAL_SMBUS_STATE_INIT and HAL_SMBUS_STATE_IDLE.

When the compilation define USE_HAL_SMBUS_REGISTER_CALLBACKS is set to 0 or not defined, the callback registration feature is not available and weak callbacks are used, represented by the default value in the table above.

Acquire/Release the SMBUS bus
- When the compilation flag USE_HAL_MUTEX is set to 1, it allows the user to acquire/reserve the whole I2C bus for executing process . The HAL Acquire/Release are based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal) :
  - HAL_SMBUS_AcquireBus() for acquire the bus or wait for it.
  - HAL_SMBUS_ReleaseBus() for releasing the bus.
- When the compilation flag USE_HAL_MUTEX is set to 0 or not defined, HAL_SMBUS_AcquireBus() and HAL_SMBUS_ReleaseBus() are not available.