STM8S/A Standard Peripherals Drivers: I2C_Public_Functions

STM8S/A

STM8S/A Standard Peripherals Drivers
I2C_Public_Functions

Functions

void I2C_AcknowledgeConfig (I2C_Ack_TypeDef Ack)
 Enable or Disable the I2C acknowledge and position acknowledge feature.
ErrorStatus I2C_CheckEvent (I2C_Event_TypeDef I2C_Event)
 I2C State Monitoring Functions.
void I2C_ClearFlag (I2C_Flag_TypeDef I2C_FLAG)
 Clear flags.
void I2C_ClearITPendingBit (I2C_ITPendingBit_TypeDef I2C_ITPendingBit)
 Clear IT pending bit.
void I2C_Cmd (FunctionalState NewState)
 Enables or disables the I2C peripheral.
void I2C_DeInit (void)
 Deinitializes the I2C peripheral registers to their default reset values.
void I2C_FastModeDutyCycleConfig (I2C_DutyCycle_TypeDef I2C_DutyCycle)
 Selects the specified I2C fast mode duty cycle.
void I2C_GeneralCallCmd (FunctionalState NewState)
 Enables or disables the I2C General Call feature.
void I2C_GenerateSTART (FunctionalState NewState)
 Generates I2C communication START condition.
void I2C_GenerateSTOP (FunctionalState NewState)
 Generates I2C communication STOP condition.
FlagStatus I2C_GetFlagStatus (I2C_Flag_TypeDef I2C_Flag)
 3) Flag-based state monitoring
ITStatus I2C_GetITStatus (I2C_ITPendingBit_TypeDef I2C_ITPendingBit)
 Checks whether the specified I2C interrupt has occurred or not.
I2C_Event_TypeDef I2C_GetLastEvent (void)
 2) Advanced state monitoring
void I2C_Init (uint32_t OutputClockFrequencyHz, uint16_t OwnAddress, I2C_DutyCycle_TypeDef I2C_DutyCycle, I2C_Ack_TypeDef Ack, I2C_AddMode_TypeDef AddMode, uint8_t InputClockFrequencyMHz)
 Initializes the I2C according to the specified parameters in standard or fast mode.
void I2C_ITConfig (I2C_IT_TypeDef I2C_IT, FunctionalState NewState)
 Enables or disables the specified I2C interrupt.
uint8_t I2C_ReceiveData (void)
 Returns the most recent received data.
void I2C_Send7bitAddress (uint8_t Address, I2C_Direction_TypeDef Direction)
 Transmits the 7-bit address (to select the) slave device.
void I2C_SendData (uint8_t Data)
 Send a byte by writing in the DR register.
void I2C_SoftwareResetCmd (FunctionalState NewState)
 Enables or disables I2C software reset.
void I2C_StretchClockCmd (FunctionalState NewState)
 Enables or disables the I2C clock stretching.

Function Documentation

void I2C_AcknowledgeConfig ( I2C_Ack_TypeDef  Ack)

Enable or Disable the I2C acknowledge and position acknowledge feature.

Note:
This function must be called before data reception start
Parameters:
Ack: Specifies the acknowledge mode to apply. This parameter can be any of the I2C_Ack_TypeDef enumeration.
Return values:
None

Definition at line 345 of file stm8s_i2c.c.

References I2C, I2C_ACK_CURR, I2C_ACK_NONE, I2C_CR2_ACK, I2C_CR2_POS, and IS_I2C_ACK_OK.

Referenced by I2C_Init().

ErrorStatus I2C_CheckEvent ( I2C_Event_TypeDef  I2C_Event)

I2C State Monitoring Functions.

This I2C driver provides three different ways for I2C state monitoring depending on the application requirements and constraints:

1) Basic state monitoring: Using I2C_CheckEvent() function: It compares the status registers (SR1, SR2 and SR3) content to a given event (can be the combination of one or more flags). It returns SUCCESS if the current status includes the given flags and returns ERROR if one or more flags are missing in the current status.

  • When to use:
    • This function is suitable for most applications as well as for startup activity since the events are fully described in the product reference manual (RM0016).
    • It is also suitable for users who need to define their own events.
  • Limitations:
    • If an error occurs (ie. error flags are set besides to the monitored flags), the I2C_CheckEvent() function may return SUCCESS despite the communication hold or corrupted real state. In this case, it is advised to use error interrupts to monitor the error events and handle them in the interrupt IRQ handler.
Note:
For error management, it is advised to use the following functions:

2) Advanced state monitoring: Using the function I2C_GetLastEvent() which returns the image of both SR1 & SR3 status registers in a single word (uint16_t) (Status Register 3 value is shifted left by 8 bits and concatenated to Status Register 1).

  • When to use:
    • This function is suitable for the same applications above but it allows to overcome the limitations of I2C_GetFlagStatus() function (see below). The returned value could be compared to events already defined in the library (stm8s_i2c.h) or to custom values defined by user.
    • This function is suitable when multiple flags are monitored at the same time.
    • At the opposite of I2C_CheckEvent() function, this function allows user to choose when an event is accepted (when all events flags are set and no other flags are set or just when the needed flags are set like I2C_CheckEvent() function).
  • Limitations:
    • User may need to define his own events.
    • Same remark concerning the error management is applicable for this function if user decides to check only regular communication flags (and ignores error flags).

3) Flag-based state monitoring: Using the function I2C_GetFlagStatus() which simply returns the status of one single flag (ie. I2C_FLAG_RXNE ...).

  • When to use:
    • This function could be used for specific applications or in debug phase.
    • It is suitable when only one flag checking is needed (most I2C events are monitored through multiple flags).
  • Limitations:
    • When calling this function, the Status register is accessed. Some flags are cleared when the status register is accessed. So checking the status of one Flag, may clear other ones.
    • Function may need to be called twice or more in order to monitor one single event.

For detailed description of Events, please refer to section I2C_Events in stm8s_i2c.h file.

1) Basic state monitoring Checks whether the last I2C Event is equal to the one passed as parameter.

Parameters:
I2C_Event,:specifies the event to be checked. This parameter can be one of the following values:
  • I2C_EVENT_SLAVE_TRANSMITTER_ADDRESS_MATCHED : EV1
  • I2C_EVENT_SLAVE_RECEIVER_ADDRESS_MATCHED : EV1
  • I2C_EVENT_SLAVE_GENERALCALLADDRESS_MATCHED : EV1
  • I2C_EVENT_SLAVE_BYTE_RECEIVED : EV2
  • (I2C_EVENT_SLAVE_BYTE_RECEIVED | I2C_FLAG_GENCALL) : EV2
  • I2C_EVENT_SLAVE_BYTE_TRANSMITTED : EV3
  • (I2C_EVENT_SLAVE_BYTE_TRANSMITTED | I2C_FLAG_GENCALL) : EV3
  • I2C_EVENT_SLAVE_ACK_FAILURE : EV3_2
  • I2C_EVENT_SLAVE_STOP_DETECTED : EV4
  • I2C_EVENT_MASTER_MODE_SELECT : EV5
  • I2C_EVENT_MASTER_TRANSMITTER_MODE_SELECTED : EV6
  • I2C_EVENT_MASTER_RECEIVER_MODE_SELECTED : EV6
  • I2C_EVENT_MASTER_BYTE_RECEIVED : EV7
  • I2C_EVENT_MASTER_BYTE_TRANSMITTING : EV8
  • I2C_EVENT_MASTER_BYTE_TRANSMITTED : EV8_2
  • I2C_EVENT_MASTER_MODE_ADDRESS10 : EV9
Note:
: For detailed description of Events, please refer to section I2C_Events in stm8s_i2c.h file.
Return values:
AnErrorStatus enumeration value:
  • SUCCESS: Last event is equal to the I2C_EVENT
  • ERROR: Last event is different from the I2C_EVENT

Definition at line 578 of file stm8s_i2c.c.

References __IO, ERROR, I2C, I2C_EVENT_SLAVE_ACK_FAILURE, I2C_SR2_AF, IS_I2C_EVENT_OK, and SUCCESS.

void I2C_ClearFlag ( I2C_Flag_TypeDef  I2C_FLAG)

Clear flags.

Parameters:
I2C_FLAG: Specifies the flag to clear This parameter can be any combination of the following values:
  • I2C_FLAG_WAKEUPFROMHALT: Wakeup from Halt
  • I2C_FLAG_OVERRUNUNDERRUN: Overrun/Underrun flag (Slave mode)
  • I2C_FLAG_ACKNOWLEDGEFAILURE: Acknowledge failure flag
  • I2C_FLAG_ARBITRATIONLOSS: Arbitration lost flag (Master mode)
  • I2C_FLAG_BUSERROR: Bus error flag.
Note:
Notes:
  • STOPF (STOP detection) is cleared by software sequence: a read operation to I2C_SR1 register (I2C_GetFlagStatus()) followed by a write operation to I2C_CR2 register.
  • ADD10 (10-bit header sent) is cleared by software sequence: a read operation to I2C_SR1 (I2C_GetFlagStatus()) followed by writing the second byte of the address in DR register.
  • BTF (Byte Transfer Finished) is cleared by software sequence: a read operation to I2C_SR1 register (I2C_GetFlagStatus()) followed by a read/write to I2C_DR register (I2C_SendData()).
  • ADDR (Address sent) is cleared by software sequence: a read operation to I2C_SR1 register (I2C_GetFlagStatus()) followed by a read operation to I2C_SR3 register ((void)(I2C->SR3)).
  • SB (Start Bit) is cleared software sequence: a read operation to I2C_SR1 register (I2C_GetFlagStatus()) followed by a write operation to I2C_DR register (I2C_SendData()).
Return values:
None

Definition at line 759 of file stm8s_i2c.c.

References FLAG_Mask, I2C, and IS_I2C_CLEAR_FLAG_OK.

void I2C_ClearITPendingBit ( I2C_ITPendingBit_TypeDef  I2C_ITPendingBit)

Clear IT pending bit.

Parameters:
I2C_ITPendingBit: specifies the interrupt pending bit to clear. This parameter can be any combination of the following values:
  • I2C_ITPENDINGBIT_WAKEUPFROMHALT: Wakeup from Halt
  • I2C_ITPENDINGBIT_OVERRUNUNDERRUN: Overrun/Underrun interrupt (Slave mode)
  • I2C_ITPENDINGBIT_ACKNOWLEDGEFAILURE: Acknowledge failure interrupt
  • I2C_ITPENDINGBIT_ARBITRATIONLOSS: Arbitration lost interrupt (Master mode)
  • I2C_ITPENDINGBIT_BUSERROR: Bus error interrupt

Notes:

  • STOPF (STOP detection) is cleared by software sequence: a read operation to I2C_SR1 register (I2C_GetITStatus()) followed by a write operation to I2C_CR2 register (I2C_AcknowledgeConfig() to configure the I2C peripheral Acknowledge).
  • ADD10 (10-bit header sent) is cleared by software sequence: a read operation to I2C_SR1 (I2C_GetITStatus()) followed by writing the second byte of the address in I2C_DR register.
  • BTF (Byte Transfer Finished) is cleared by software sequence: a read operation to I2C_SR1 register (I2C_GetITStatus()) followed by a read/write to I2C_DR register (I2C_SendData()).
  • ADDR (Address sent) is cleared by software sequence: a read operation to I2C_SR1 register (I2C_GetITStatus()) followed by a read operation to I2C_SR3 register ((void)(I2C->SR3)).
  • SB (Start Bit) is cleared by software sequence: a read operation to I2C_SR1 register (I2C_GetITStatus()) followed by a write operation to I2C_DR register (I2C_SendData()).
    Return values:
    None

Definition at line 871 of file stm8s_i2c.c.

References FLAG_Mask, I2C, and IS_I2C_CLEAR_ITPENDINGBIT_OK.

void I2C_Cmd ( FunctionalState  NewState)

Enables or disables the I2C peripheral.

Parameters:
NewState: Indicate the new I2C peripheral state. This parameter can be any of the FunctionalState enumeration.
Return values:
None

Definition at line 202 of file stm8s_i2c.c.

References DISABLE, I2C, I2C_CR1_PE, and IS_FUNCTIONALSTATE_OK.

void I2C_DeInit ( void  )

Deinitializes the I2C peripheral registers to their default reset values.

Parameters:
None
Return values:
None

Definition at line 67 of file stm8s_i2c.c.

References I2C, I2C_CCRH_RESET_VALUE, I2C_CCRL_RESET_VALUE, I2C_CR1_RESET_VALUE, I2C_CR2_RESET_VALUE, I2C_FREQR_RESET_VALUE, I2C_ITR_RESET_VALUE, I2C_OARH_RESET_VALUE, I2C_OARL_RESET_VALUE, and I2C_TRISER_RESET_VALUE.

void I2C_FastModeDutyCycleConfig ( I2C_DutyCycle_TypeDef  I2C_DutyCycle)

Selects the specified I2C fast mode duty cycle.

Parameters:
I2C_DutyCycle: Specifies the duty cycle to apply. This parameter can be any of the I2C_DutyCycle_TypeDef enumeration.
Return values:
None

Definition at line 405 of file stm8s_i2c.c.

References I2C, I2C_CCRH_DUTY, I2C_DUTYCYCLE_16_9, and IS_I2C_DUTYCYCLE_OK.

void I2C_GeneralCallCmd ( FunctionalState  NewState)

Enables or disables the I2C General Call feature.

Parameters:
NewState: State of the General Call feature. This parameter can be any of the FunctionalState enumeration.
Return values:
None

Definition at line 225 of file stm8s_i2c.c.

References DISABLE, I2C, I2C_CR1_ENGC, and IS_FUNCTIONALSTATE_OK.

void I2C_GenerateSTART ( FunctionalState  NewState)

Generates I2C communication START condition.

Note:
CCR must be programmed, i.e. I2C_Init function must have been called with a valid I2C_ClockSpeed
Parameters:
NewState: Enable or disable the start condition. This parameter can be any of the FunctionalState enumeration.
Return values:
None

Definition at line 250 of file stm8s_i2c.c.

References DISABLE, I2C, I2C_CR2_START, and IS_FUNCTIONALSTATE_OK.

void I2C_GenerateSTOP ( FunctionalState  NewState)

Generates I2C communication STOP condition.

Parameters:
NewState: Enable or disable the stop condition. This parameter can be any of the FunctionalState enumeration.
Return values:
None

Definition at line 273 of file stm8s_i2c.c.

References DISABLE, I2C, I2C_CR2_STOP, and IS_FUNCTIONALSTATE_OK.

FlagStatus I2C_GetFlagStatus ( I2C_Flag_TypeDef  I2C_Flag)

3) Flag-based state monitoring

Checks whether the specified I2C flag is set or not.

Parameters:
I2C_Flag,:specifies the flag to check. This parameter can be one of the following values:
  • I2C_FLAG_GENERALCALL: General call header flag (Slave mode)
  • I2C_FLAG_TRANSMITTERRECEIVER: Transmitter/Receiver flag
  • I2C_FLAG_BUSBUSY: Bus busy flag
  • I2C_FLAG_MASTERSLAVE: Master/Slave flag
  • I2C_FLAG_WAKEUPFROMHALT: Wake up from HALT flag
  • I2C_FLAG_OVERRUNUNDERRUN: Overrun/Underrun flag (Slave mode)
  • I2C_FLAG_ACKNOWLEDGEFAILURE: Acknowledge failure flag
  • I2C_FLAG_ARBITRATIONLOSS: Arbitration lost flag (Master mode)
  • I2C_FLAG_BUSERROR: Bus error flag
  • I2C_FLAG_TXEMPTY: Data register empty flag (Transmitter)
  • I2C_FLAG_RXNOTEMPTY: Data register not empty (Receiver) flag
  • I2C_FLAG_STOPDETECTION: Stop detection flag (Slave mode)
  • I2C_FLAG_HEADERSENT: 10-bit header sent flag (Master mode)
  • I2C_FLAG_TRANSFERFINISHED: Byte transfer finished flag
  • I2C_FLAG_ADDRESSSENTMATCHED: Address sent flag (Master mode) �ADSL� Address matched flag (Slave mode)�ENDAD�
  • I2C_FLAG_STARTDETECTION: Start bit flag (Master mode)
Return values:
Thenew state of I2C_FLAG (SET or RESET).

Definition at line 679 of file stm8s_i2c.c.

References I2C, IS_I2C_FLAG_OK, RESET, and SET.

ITStatus I2C_GetITStatus ( I2C_ITPendingBit_TypeDef  I2C_ITPendingBit)

Checks whether the specified I2C interrupt has occurred or not.

Parameters:
I2C_ITPendingBit,:specifies the interrupt source to check. This parameter can be one of the following values:
  • I2C_ITPENDINGBIT_WAKEUPFROMHALT: Wakeup from Halt
  • I2C_ITPENDINGBIT_OVERRUNUNDERRUN: Overrun/Underrun flag (Slave mode)
  • I2C_ITPENDINGBIT_ACKNOWLEDGEFAILURE: Acknowledge failure flag
  • I2C_ITPENDINGBIT_ARBITRATIONLOSS: Arbitration lost flag (Master mode)
  • I2C_ITPENDINGBIT_BUSERROR: Bus error flag
  • I2C_ITPENDINGBIT_TXEMPTY: Data register empty flag (Transmitter)
  • I2C_ITPENDINGBIT_RXNOTEMPTY: Data register not empty (Receiver) flag
  • I2C_ITPENDINGBIT_STOPDETECTION: Stop detection flag (Slave mode)
  • I2C_ITPENDINGBIT_HEADERSENT: 10-bit header sent flag (Master mode)
  • I2C_ITPENDINGBIT_TRANSFERFINISHED: Byte transfer finished flag
  • I2C_ITPENDINGBIT_ADDRESSSENTMATCHED: Address sent flag (Master mode) �ADSL� Address matched flag (Slave mode)�ENDAD�
  • I2C_ITPENDINGBIT_STARTDETECTION: Start bit flag (Master mode)
Return values:
Thenew state of I2C_ITPendingBit This parameter can be any of the ITStatus enumeration.

Definition at line 791 of file stm8s_i2c.c.

References __IO, I2C, IS_I2C_ITPENDINGBIT_OK, ITEN_Mask, REGISTER_Mask, REGISTER_SR1_Index, RESET, and SET.

I2C_Event_TypeDef I2C_GetLastEvent ( void  )

2) Advanced state monitoring

Returns the last I2C Event.

Note:
: For detailed description of Events, please refer to section I2C_Events in stm8s_i2c.h file.
Return values:
Thelast event This parameter can be any of the I2C_Event_TypeDef enumeration.

Definition at line 628 of file stm8s_i2c.c.

References __IO, I2C, I2C_EVENT_SLAVE_ACK_FAILURE, and I2C_SR2_AF.

void I2C_Init ( uint32_t  OutputClockFrequencyHz,
uint16_t  OwnAddress,
I2C_DutyCycle_TypeDef  I2C_DutyCycle,
I2C_Ack_TypeDef  Ack,
I2C_AddMode_TypeDef  AddMode,
uint8_t  InputClockFrequencyMHz 
)

Initializes the I2C according to the specified parameters in standard or fast mode.

Parameters:
OutputClockFrequencyHz: Specifies the output clock frequency in Hz.
OwnAddress: Specifies the own address.
I2C_DutyCycle: Specifies the duty cycle to apply in fast mode. This parameter can be any of the I2C_DutyCycle_TypeDef enumeration.
Note:
This parameter don't have impact when the OutputClockFrequency lower than 100KHz.
Parameters:
Ack: Specifies the acknowledge mode to apply. This parameter can be any of the I2C_Ack_TypeDef enumeration.
AddMode: Specifies the acknowledge address to apply. This parameter can be any of the I2C_AddMode_TypeDef enumeration.
InputClockFrequencyMHz: Specifies the input clock frequency in MHz.
Return values:
None

Definition at line 96 of file stm8s_i2c.c.

References I2C, I2C_AcknowledgeConfig(), I2C_CCRH_CCR, I2C_CCRH_DUTY, I2C_CCRH_FS, I2C_CCRL_CCR, I2C_CR1_PE, I2C_DUTYCYCLE_2, I2C_FREQR_FREQ, I2C_MAX_STANDARD_FREQ, I2C_OARH_ADDCONF, IS_I2C_ACK_OK, IS_I2C_ADDMODE_OK, IS_I2C_DUTYCYCLE_OK, IS_I2C_INPUT_CLOCK_FREQ_OK, IS_I2C_OUTPUT_CLOCK_FREQ_OK, and IS_I2C_OWN_ADDRESS_OK.

void I2C_ITConfig ( I2C_IT_TypeDef  I2C_IT,
FunctionalState  NewState 
)

Enables or disables the specified I2C interrupt.

Parameters:
I2C_IT: Name of the interrupt to enable or disable. This parameter can be any of the I2C_IT_TypeDef enumeration.
NewState: State of the interrupt to apply. This parameter can be any of the FunctionalState enumeration.
Return values:
None

Definition at line 381 of file stm8s_i2c.c.

References DISABLE, I2C, IS_FUNCTIONALSTATE_OK, and IS_I2C_INTERRUPT_OK.

uint8_t I2C_ReceiveData ( void  )

Returns the most recent received data.

Parameters:
None
Return values:
uint8_t: The value of the received byte data.

Definition at line 427 of file stm8s_i2c.c.

References I2C.

void I2C_Send7bitAddress ( uint8_t  Address,
I2C_Direction_TypeDef  Direction 
)

Transmits the 7-bit address (to select the) slave device.

Parameters:
Address: Specifies the slave address which will be transmitted.
Direction: Specifies whether the I2C device will be a Transmitter or a Receiver. This parameter can be any of the I2C_Direction_TypeDef enumeration.
Return values:
None

Definition at line 440 of file stm8s_i2c.c.

References I2C, IS_I2C_ADDRESS_OK, and IS_I2C_DIRECTION_OK.

void I2C_SendData ( uint8_t  Data)

Send a byte by writing in the DR register.

Parameters:
Data: Byte to be sent.
Return values:
None

Definition at line 458 of file stm8s_i2c.c.

References I2C.

void I2C_SoftwareResetCmd ( FunctionalState  NewState)

Enables or disables I2C software reset.

Parameters:
NewState: Specifies the new state of the I2C software reset. This parameter can be any of the FunctionalState enumeration.
Return values:
None

Definition at line 296 of file stm8s_i2c.c.

References DISABLE, I2C, I2C_CR2_SWRST, and IS_FUNCTIONALSTATE_OK.

void I2C_StretchClockCmd ( FunctionalState  NewState)

Enables or disables the I2C clock stretching.

Parameters:
NewState: Specifies the new state of the I2C Clock stretching. This parameter can be any of the FunctionalState enumeration.
Return values:
None

Definition at line 320 of file stm8s_i2c.c.

References DISABLE, I2C, I2C_CR1_NOSTRETCH, and IS_FUNCTIONALSTATE_OK.

STM8 Standard Peripherals Library: Footer

 

 

 

      For complete documentation on STM8 8-bit Microcontrollers platform visit www.st.com