HAL I2C functions

Initialization and de-initialization functions

group I2C_Exported_Functions_Group1

A set of functions allowing to initialize and deinitialize the I2Cx peripheral :

Functions

hal_status_t HAL_I2C_Init ( hal_i2c_handle_t * hi2c , hal_i2c_t instance )

Initialize the I2C according to the associated handle.

Parameters :
Return values :

  • HAL_OK – HAL I2C instance has been correctly initialized.

  • HAL_INVALID_PARAM – HAL I2C instance is NULL

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

void HAL_I2C_DeInit ( hal_i2c_handle_t * hi2c )

Deinitialize the HAL I2C driver for the given handle and disable the peripheral.

Parameters :

hi2c – pointer to a hal_i2c_handle_t structure.

Configuration functions

group I2C_Exported_Functions_Group2

A set of functions allowing to configure the I2Cx peripheral:

Functions

hal_status_t HAL_I2C_SetConfig ( hal_i2c_handle_t * hi2c , const hal_i2c_config_t * p_config )

Configure the I2C according to the user parameters.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_config – Pointer to the configuration structure

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

void HAL_I2C_GetConfig ( const hal_i2c_handle_t * hi2c , hal_i2c_config_t * p_config )

Retrieve the I2C configuration.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_config – Pointer to the configuration structure

hal_status_t HAL_I2C_SetTiming ( hal_i2c_handle_t * hi2c , uint32_t value )

Set the I2C Timing.

Parameters :
Return values :

HAL_OK – Operation completed successfully

uint32_t HAL_I2C_GetTiming ( const hal_i2c_handle_t * hi2c )

Get the I2C Timing.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

uint32_t – I2C timing value

hal_status_t HAL_I2C_EnableAnalogFilter ( hal_i2c_handle_t * hi2c )

Enable I2C Analog noise filter.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I2C_DisableAnalogFilter ( hal_i2c_handle_t * hi2c )

Disable I2C Analog noise filter.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i2c_analog_filter_status_t HAL_I2C_IsEnabledAnalogFilter ( const hal_i2c_handle_t * hi2c )

Check I2C analog noise filter status.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_I2C_ANALOG_FILTER_ENABLED – Analog Filter is enabled

  • HAL_I2C_ANALOG_FILTER_DISABLED – Analog Filter is disabled

hal_status_t HAL_I2C_SetDigitalFilter ( hal_i2c_handle_t * hi2c , uint32_t value )

Set the I2C Digital noise filter.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • value – Coefficient of digital noise filter between Min_Data=0x00 and Max_Data=0x0F.

Return values :

HAL_OK – Operation completed successfully

uint32_t HAL_I2C_GetDigitalFilter ( const hal_i2c_handle_t * hi2c )

Get the I2C Digital noise filter.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

uint32_t – Coefficient of digital noise filter between Min_Data=0x00 and Max_Data=0x0F.

hal_status_t HAL_I2C_SLAVE_EnableWakeUp ( hal_i2c_handle_t * hi2c )

Enable I2C slave wakeup from Stop mode(s).

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I2C_SLAVE_DisableWakeUp ( hal_i2c_handle_t * hi2c )

Disable slave I2C wakeup from Stop mode(s).

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i2c_slave_wake_up_status_t HAL_I2C_SLAVE_IsEnabledWakeUp ( const hal_i2c_handle_t * hi2c )

Check slave I2C wake up feature status.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_I2C_SLAVE_WAKE_UP_ENABLED – Slave Wake Up is enabled

  • HAL_I2C_SLAVE_WAKE_UP_DISABLED – Slave Wake Up is disabled

hal_status_t HAL_I2C_EnableFastModePlus ( hal_i2c_handle_t * hi2c )

Enable I2C fast mode plus.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I2C_DisableFastModePlus ( hal_i2c_handle_t * hi2c )

Disable I2C fast mode plus.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i2c_fast_mode_plus_status_t HAL_I2C_IsEnabledFastModePlus ( const hal_i2c_handle_t * hi2c )

Check I2C fast mode plus feature status.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_I2C_FAST_MODE_PLUS_ENABLED – Fast mode plus enabled

  • HAL_I2C_FAST_MODE_PLUS_DISABLED – Fast mode plus disabled

hal_status_t HAL_I2C_AM_SetConfigTrigger ( hal_i2c_handle_t * hi2c , const hal_i2c_am_trigger_config_t * p_config )

Set the I2C autonomous mode trigger configuration.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

void HAL_I2C_AM_GetConfigTrigger ( const hal_i2c_handle_t * hi2c , hal_i2c_am_trigger_config_t * p_config )

Get the I2C autonomous mode trigger configuration.

Parameters :
hal_status_t HAL_I2C_AM_EnableTrigger ( hal_i2c_handle_t * hi2c )

Enable the I2C autonomous mode.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I2C_AM_DisableTrigger ( hal_i2c_handle_t * hi2c )

Disable the I2C autonomous mode.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i2c_am_trigger_status_t HAL_I2C_AM_IsEnabledTrigger ( const hal_i2c_handle_t * hi2c )

Get autonomous mode status.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_I2C_AM_TRIGGER_ENABLED – Autonomous mode trigger enabled

  • HAL_I2C_AM_TRIGGER_DISABLED – Autonomous mode trigger disabled

hal_status_t HAL_I2C_SLAVE_EnableClockStretching ( hal_i2c_handle_t * hi2c )

Enable slave I2C clock Stretching.

Note

The stretching mode is already enabled after a I2C HW reset

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I2C_SLAVE_DisableClockStretching ( hal_i2c_handle_t * hi2c )

Disable slave I2C clock Stretching.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i2c_slave_stretch_mode_status_t HAL_I2C_SLAVE_IsEnabledClockStretching ( const hal_i2c_handle_t * hi2c )

Check slave clock Stretching status.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_I2C_SLAVE_STRETCH_ENABLED – Slave stretch mode enabled

  • HAL_I2C_SLAVE_STRETCH_DISABLED – Slave stretch mode disabled

hal_status_t HAL_I2C_SLAVE_EnableAckGeneralCall ( hal_i2c_handle_t * hi2c )

Enable slave I2C Acknowledge General Call.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I2C_SLAVE_DisableAckGeneralCall ( hal_i2c_handle_t * hi2c )

Disable I2C slave Acknowledge General Call.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i2c_slave_ack_general_call_status_t HAL_I2C_SLAVE_IsEnabledAckGeneralCall ( const hal_i2c_handle_t * hi2c )

Check slave Acknowledge General Call status.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_I2C_SLAVE_ACK_GENERAL_CALL_ENABLED – Slave Acknowledge General Call is enabled

  • HAL_I2C_SLAVE_ACK_GENERAL_CALL_DISABLED – Slave Acknowledge General Call is disabled

hal_status_t HAL_I2C_SetConfigOwnAddress2 ( hal_i2c_handle_t * hi2c , uint32_t addr , hal_i2c_own_addr2_mask_t mask )

Set the I2C own address2 configuration.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t .

  • addr – The second device own address. It is a 7-bit address but the value must be shifted left by 1 bit. In other words, an 8-bit value is required and the bit 0 is not considered.

  • mask – Acknowledge mask address second device own address.

Return values :

HAL_OK – Operation completed successfully

void HAL_I2C_GetConfigOwnAddress2 ( const hal_i2c_handle_t * hi2c , uint32_t * addr , hal_i2c_own_addr2_mask_t * mask )

Get the I2C own address2 configuration.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t .

  • addr – The second device own address. It is a 7-bit address but the value must is shifted left by 1 bit. In other words, an 8-bit value is returned and the bit 0 is not considered.

  • mask – Acknowledge mask address second device own address.

hal_status_t HAL_I2C_EnableOwnAddress2 ( hal_i2c_handle_t * hi2c )

Enable I2C Own Address2.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I2C_DisableOwnAddress2 ( hal_i2c_handle_t * hi2c )

Disable I2C Own Address2.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i2c_own_addr2_status_t HAL_I2C_IsEnabledOwnAddress2 ( const hal_i2c_handle_t * hi2c )

Check own address 2 status.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_I2C_OWN_ADDR2_ENABLED – Dual addressing is enabled

  • HAL_I2C_OWN_ADDR2_DISABLED – Dual addressing is disabled

hal_status_t HAL_I2C_MASTER_RegisterTxCpltCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C master Tx transfer completed callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the master Tx transfer completed callback function

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_RegisterRxCpltCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C master Rx transfer completed callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the master Rx transfer completed callback function

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_RegisterTxCpltCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C slave Tx transfer completed callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the slave Tx transfer completed callback function

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_RegisterRxCpltCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C slave Rx transfer completed callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the slave Rx transfer completed callback function

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_RegisterListenCpltCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C Listen Complete callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the I2C Listen Complete callback

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_RegisterMemTxCpltCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C Memory Tx transfer completed callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the I2C Memory Tx transfer completed callback

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_RegisterMemRxCpltCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C Memory Rx transfer completed callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the I2C Memory Rx transfer completed callback

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_RegisterAbortCpltCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C Abort completed callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the I2C Abort completed callback

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_RegisterAddrMatchCallback ( hal_i2c_handle_t * hi2c , hal_i2c_slave_addr_cb_t p_callback )

Register the I2C slave Address Match callback.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_callback – pointer to the I2C slave Address Match callback

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_RegisterErrorCallback ( hal_i2c_handle_t * hi2c , hal_i2c_cb_t p_callback )

Register the I2C Error callback.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SetTxDMA ( hal_i2c_handle_t * hi2c , hal_dma_handle_t * hdma )

Link the Transmit DMA handle to the I2C handle.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SetRxDMA ( hal_i2c_handle_t * hi2c , hal_dma_handle_t * hdma )

Link the Receive DMA handle to the I2C handle.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

Input and Output operation functions

group I2C_Exported_Functions_Group3

A set of functions allowing to manage the I2C data transfers.

Functions

hal_status_t HAL_I2C_MASTER_Transmit ( hal_i2c_handle_t * hi2c , uint32_t device_addr , const void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Transmit in master mode an amount of data in blocking mode.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • timeout_ms – Timeout duration in millisecond

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_ERROR – Operation completed with error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

  • HAL_TIMEOUT – Operation exceeds user timeout

hal_status_t HAL_I2C_MASTER_Receive ( hal_i2c_handle_t * hi2c , uint32_t device_addr , void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Receive in master mode an amount of data in blocking mode.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • timeout_ms – Timeout duration in millisecond

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_ERROR – Operation completed with error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

  • HAL_TIMEOUT – Operation exceeds user timeout

hal_status_t HAL_I2C_SLAVE_Transmit ( hal_i2c_handle_t * hi2c , const void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Transmit in slave mode an amount of data in blocking mode.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • timeout_ms – Timeout duration in millisecond

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_ERROR – Operation completed with error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

  • HAL_TIMEOUT – Operation exceeds user timeout

hal_status_t HAL_I2C_SLAVE_Receive ( hal_i2c_handle_t * hi2c , void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Receive in slave mode an amount of data in blocking mode.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • timeout_ms – Timeout duration in millisecond

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_ERROR – Operation completed with error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

  • HAL_TIMEOUT – Operation exceeds user timeout

hal_status_t HAL_I2C_MASTER_Transmit_IT ( hal_i2c_handle_t * hi2c , uint32_t device_addr , const void * p_data , uint32_t size_byte )

Transmit in master mode an amount of data in non-blocking mode with interrupt.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_Receive_IT ( hal_i2c_handle_t * hi2c , uint32_t device_addr , void * p_data , uint32_t size_byte )

Receive in master mode an amount of data in non-blocking mode with interrupt.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_Transmit_IT ( hal_i2c_handle_t * hi2c , const void * p_data , uint32_t size_byte )

Transmit in slave mode an amount of data in non-blocking mode with interrupt.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_Receive_IT ( hal_i2c_handle_t * hi2c , void * p_data , uint32_t size_byte )

Receive in slave mode an amount of data in non-blocking mode with interrupt.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_Transmit_DMA ( hal_i2c_handle_t * hi2c , uint32_t device_addr , const void * p_data , uint32_t size_byte )

Transmit in master mode an amount of data in non-blocking mode with DMA.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_Receive_DMA ( hal_i2c_handle_t * hi2c , uint32_t device_addr , void * p_data , uint32_t size_byte )

Receive in master mode an amount of data in non-blocking mode with DMA.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_Transmit_DMA ( hal_i2c_handle_t * hi2c , const void * p_data , uint32_t size_byte )

Transmit in slave mode an amount of data in non-blocking mode with DMA.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_Receive_DMA ( hal_i2c_handle_t * hi2c , void * p_data , uint32_t size_byte )

Receive in slave mode an amount of data in non-blocking mode with DMA.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_MemWrite ( hal_i2c_handle_t * hi2c , uint32_t device_addr , uint32_t memory_addr , hal_i2c_mem_addr_size_t memory_addr_size , const void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Write an amount of data in blocking mode to a specific memory address.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • memory_addr – Internal memory address

  • memory_addr_size – Size of internal memory address

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • timeout_ms – Timeout duration in millisecond

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_ERROR – Operation completed with error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

  • HAL_TIMEOUT – Operation exceeds user timeout

hal_status_t HAL_I2C_MASTER_MemRead ( hal_i2c_handle_t * hi2c , uint32_t device_addr , uint32_t memory_addr , hal_i2c_mem_addr_size_t memory_addr_size , void * p_data , uint32_t size_byte , uint32_t timeout_ms )

Read an amount of data in blocking mode from a specific memory address.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • memory_addr – Internal memory address

  • memory_addr_size – Size of internal memory address

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • timeout_ms – Timeout duration in millisecond

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_ERROR – Operation completed with error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

  • HAL_TIMEOUT – Operation exceeds user timeout

hal_status_t HAL_I2C_MASTER_MemWrite_IT ( hal_i2c_handle_t * hi2c , uint32_t device_addr , uint32_t memory_addr , hal_i2c_mem_addr_size_t memory_addr_size , const void * p_data , uint32_t size_byte )

Write an amount of data in non-blocking mode with interrupt to a specific memory address.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • memory_addr – Internal memory address

  • memory_addr_size – Size of internal memory address

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_MemRead_IT ( hal_i2c_handle_t * hi2c , uint32_t device_addr , uint32_t memory_addr , hal_i2c_mem_addr_size_t memory_addr_size , void * p_data , uint32_t size_byte )

Read an amount of data in non-blocking mode with interrupt from a specific memory address.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • memory_addr – Internal memory address

  • memory_addr_size – Size of internal memory address

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_MemWrite_DMA ( hal_i2c_handle_t * hi2c , uint32_t device_addr , uint32_t memory_addr , hal_i2c_mem_addr_size_t memory_addr_size , const void * p_data , uint32_t size_byte )

Write an amount of data in non-blocking mode with DMA to a specific memory address.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • memory_addr – Internal memory address

  • memory_addr_size – Size of internal memory address

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_MemRead_DMA ( hal_i2c_handle_t * hi2c , uint32_t device_addr , uint32_t memory_addr , hal_i2c_mem_addr_size_t memory_addr_size , void * p_data , uint32_t size_byte )

Read an amount of data in non-blocking mode with DMA from a specific memory address.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • memory_addr – Internal memory address

  • memory_addr_size – Size of internal memory address

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be read in bytes

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_IsSlaveReady ( hal_i2c_handle_t * hi2c , uint32_t device_addr , uint32_t trials , uint32_t timeout_ms )

Check if target device is ready for communication.

Note

This function is used with Memory devices

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • trials – Number of trials which must greater than or equal to 1

  • timeout_ms – Timeout duration in millisecond

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_BUSY – Concurrent process ongoing or bus is busy

  • HAL_INVALID_PARAM – Invalid parameter

  • HAL_TIMEOUT – Operation exceeds user timeout

hal_status_t HAL_I2C_MASTER_SEQ_Transmit_IT ( hal_i2c_handle_t * hi2c , uint32_t device_addr , const void * p_data , uint32_t size_byte , hal_i2c_xfer_opt_t xfer_opt )

Sequential transmit in master I2C mode an amount of data in non-blocking mode with interrupt.

Note

This interface allows to manage repeated start condition when a direction change during transfer

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • xfer_opt – Options of transfer

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_SEQ_Transmit_DMA ( hal_i2c_handle_t * hi2c , uint32_t device_addr , const void * p_data , uint32_t size_byte , hal_i2c_xfer_opt_t xfer_opt )

Sequential transmit in master I2C mode an amount of data in non-blocking mode with DMA.

Note

This interface allows to manage repeated start condition when a direction change during transfer

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • xfer_opt – Options of transfer

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_SEQ_Receive_IT ( hal_i2c_handle_t * hi2c , uint32_t device_addr , void * p_data , uint32_t size_byte , hal_i2c_xfer_opt_t xfer_opt )

Sequential receive in master I2C mode an amount of data in non-blocking mode with interrupt.

Note

This interface allows to manage repeated start condition when a direction change during transfer

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • xfer_opt – Options of transfer

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_MASTER_SEQ_Receive_DMA ( hal_i2c_handle_t * hi2c , uint32_t device_addr , void * p_data , uint32_t size_byte , hal_i2c_xfer_opt_t xfer_opt )

Sequential receive in master I2C mode an amount of data in non-blocking mode with DMA.

Note

This interface allows to manage repeated start condition when a direction change during transfer

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • xfer_opt – Options of transfer

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_SEQ_Transmit_IT ( hal_i2c_handle_t * hi2c , const void * p_data , uint32_t size_byte , hal_i2c_xfer_opt_t xfer_opt )

Sequential transmit in slave/device I2C mode an amount of data in non-blocking mode with interrupt.

Note

This interface allows to manage repeated start condition when a direction change during transfer

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • xfer_opt – Options of transfer

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_SEQ_Transmit_DMA ( hal_i2c_handle_t * hi2c , const void * p_data , uint32_t size_byte , hal_i2c_xfer_opt_t xfer_opt )

Sequential transmit in slave/device I2C mode an amount of data in non-blocking mode with DMA.

Note

This interface allows to manage repeated start condition when a direction change during transfer

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • xfer_opt – Options of transfer

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_SEQ_Receive_IT ( hal_i2c_handle_t * hi2c , void * p_data , uint32_t size_byte , hal_i2c_xfer_opt_t xfer_opt )

Sequential receive in slave/device I2C mode an amount of data in non-blocking mode with interrupt.

Note

This interface allows to manage repeated start condition when a direction change during transfer

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • xfer_opt – Options of transfer

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_SEQ_Receive_DMA ( hal_i2c_handle_t * hi2c , void * p_data , uint32_t size_byte , hal_i2c_xfer_opt_t xfer_opt )

Sequential receive in slave/device I2C mode an amount of data in non-blocking mode with DMA.

Note

This interface allows to manage repeated start condition when a direction change during transfer

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • p_data – Pointer to data buffer

  • size_byte – Amount of data to be sent in bytes

  • xfer_opt – Options of transfer

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Dma error

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I2C_SLAVE_EnableListen_IT ( hal_i2c_handle_t * hi2c )

Enable the Address listen mode with interrupt.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

hal_status_t HAL_I2C_SLAVE_DisableListen_IT ( hal_i2c_handle_t * hi2c )

Disable the Address listen mode with interrupt.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

hal_status_t HAL_I2C_MASTER_Abort_IT ( hal_i2c_handle_t * hi2c , uint32_t device_addr )

Abort a master I2C IT or DMA process communication with interrupt.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • device_addr – Target device address: The device 7 bits address value in datasheet must be shifted to the left before calling the interface

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – Mode is not master

  • HAL_BUSY – No process ongoing

hal_status_t HAL_I2C_SLAVE_Abort_IT ( hal_i2c_handle_t * hi2c )

Abort a slave I2C IT or DMA process communication with interrupt.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

HAL_OK – Operation completed successfully

IRQ Handlers

group I2C_Exported_Functions_Group4

A set of function to handle the I2C interruptions :

  • I2C Event IRQ Handler : HAL_I2C_EV_IRQHandler

  • I2C Error IRQ Handler : HAL_I2C_ER_IRQHandler

Functions

void HAL_I2C_EV_IRQHandler ( hal_i2c_handle_t * hi2c )

This function handles I2C event interrupt request.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_ER_IRQHandler ( hal_i2c_handle_t * hi2c )

This function handles I2C error interrupt request.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Weak Callback Functions

group I2C_Exported_Functions_Group5

A set of Weak functions (or default Callbacks functions if USE_HAL_I2C_REGISTER_CALLBACKS is set to 1) which are used to asynchronously informed the application in non blocking modes (nterrupt and DMA) :

Functions

void HAL_I2C_MASTER_TxCpltCallback ( hal_i2c_handle_t * hi2c )

Master Tx transfer completed callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_MASTER_RxCpltCallback ( hal_i2c_handle_t * hi2c )

Master Rx transfer completed callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_SLAVE_TxCpltCallback ( hal_i2c_handle_t * hi2c )

Slave Tx transfer completed callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_SLAVE_RxCpltCallback ( hal_i2c_handle_t * hi2c )

Slave Rx transfer completed callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_SLAVE_AddrCallback ( hal_i2c_handle_t * hi2c , hal_i2c_slave_xfer_direction_t xfer_direction , uint32_t addr_match_code )

Slave Address Match callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

  • hi2c – Pointer to a hal_i2c_handle_t

  • xfer_direction – Master request transfer Direction (Write/Read)

  • addr_match_code – Address Match Code

void HAL_I2C_SLAVE_ListenCpltCallback ( hal_i2c_handle_t * hi2c )

Listen Complete callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_MASTER_MemTxCpltCallback ( hal_i2c_handle_t * hi2c )

Memory Tx transfer completed callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_MASTER_MemRxCpltCallback ( hal_i2c_handle_t * hi2c )

Memory Rx transfer completed callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_ErrorCallback ( hal_i2c_handle_t * hi2c )

I2C error callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

void HAL_I2C_AbortCpltCallback ( hal_i2c_handle_t * hi2c )

I2C abort callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Peripheral State, Mode and Error functions, Kernel Clock Frequency

group I2C_Exported_Functions_Group6

A set of functions allowing to retrieve peripheral state, mode and last process errors.

Functions

hal_i2c_state_t HAL_I2C_GetState ( const hal_i2c_handle_t * hi2c )

Return the I2C handle state.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

hal_i2c_state_t – HAL I2C state

hal_i2c_mode_t HAL_I2C_GetMode ( const hal_i2c_handle_t * hi2c )

Returns the functional I2C mode. master, slave, memory or no mode.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

hal_i2c_mode_t – HAL I2C mode

uint32_t HAL_I2C_GetLastErrorCodes ( const hal_i2c_handle_t * hi2c )

Returns errors limited to the last process.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

uint32_t – last error code. It can be HAL_I2C_ERROR_NONE or a combinaison of the following values: HAL_I2C_ERROR_BERR HAL_I2C_ERROR_ARLO HAL_I2C_ERROR_AF HAL_I2C_ERROR_OVR HAL_I2C_ERROR_DMA HAL_I2C_ERROR_SIZE

uint32_t HAL_I2C_GetClockFreq ( const hal_i2c_handle_t * hi2c )

Return the peripheral clock frequency for I2C.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

uint32_t – Frequency in Hz. 0 if the source clock of the I2C is not configured or not ready.

Acquire/Release/Free the bus

group I2C_Exported_Functions_Group7

A set of functions allowing to Acquire/Release the bus based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal):

Functions

hal_status_t HAL_I2C_AcquireBus ( hal_i2c_handle_t * hi2c , uint32_t timeout_ms )

Acquire the I2C bus thanks to the the HAL OS abstraction layer (stm32_hal_os.c/.h osal).

Note

The HAL_I2C_AcquireBus must be called from thread mode only (not from handler mode i.e from ISR).

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_ERROR – Operation completed with error

hal_status_t HAL_I2C_ReleaseBus ( hal_i2c_handle_t * hi2c )

Release the I2C bus thanks to the the HAL OS abstraction layer (stm32_hal_os.c/.h osal).

Note

The HAL_I2C_ReleaseBus can be called from thread mode or from handler mode i.e from ISR.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_ERROR – Operation completed with error

Set/Get user data

group I2C_Exported_Functions_Group8

A set of functions allowing to manage a user data pointer stored to the I2C handle:

Functions

void HAL_I2C_SetUserData ( hal_i2c_handle_t * hi2c , const void * p_user_data )

Set the user data pointer into the handle.

Parameters :
const void * HAL_I2C_GetUserData ( const hal_i2c_handle_t * hi2c )

Get the user data pointer from the handle.

Parameters :

hi2c – Pointer to a hal_i2c_handle_t

Return values :

void* – Pointer to the user data.