I2C - Inter-Integrated Circuit#

I2C_ClockHLR_TypeDef#

I2C_ClockHLR_TypeDef

Clock low to high ratio settings.

I2C_TransferReturn_TypeDef#

I2C_TransferReturn_TypeDef

Return codes for single Controller mode transfer function.

I2C_BusFreqGet#

uint32_t I2C_BusFreqGet (I2C_TypeDef *i2c)

Get the current configured I2C bus frequency.

This frequency is only relevant when acting as master.

Note

• The actual frequency is a real number, this function returns a rounded down (truncated) integer value.

Returns

• The current I2C frequency in Hz.

I2C_BusFreqSet#

void I2C_BusFreqSet (I2C_TypeDef *i2c, uint32_t freqRef, uint32_t freqScl, I2C_ClockHLR_TypeDef i2cMode)

Set the I2C bus frequency.

The bus frequency is only relevant when acting as master. The bus frequency should not be set higher than the maximum frequency accepted by the slowest device on the bus.

Notice that, due to asymmetric requirements on low and high I2C clock cycles in the I2C specification, the maximum frequency allowed to comply with the specification may be somewhat lower than expected.

See the reference manual, details on I2C clock generation, for maximum allowed theoretical frequencies for different modes.

I2C_Enable#

void I2C_Enable (I2C_TypeDef *i2c, bool enable)

Enable/disable I2C.

Note

• After enabling the I2C (from being disabled), the I2C is in BUSY state.

I2C_Init#

void I2C_Init (I2C_TypeDef *i2c, const I2C_Init_TypeDef *init)

Initialize I2C.

I2C_Reset#

void I2C_Reset (I2C_TypeDef *i2c)

Reset I2C to the same state that it was in after a hardware reset.

Note

• The ROUTE register is NOT reset by this function to allow for centralized setup of this feature.

I2C_Transfer#

I2C_TransferReturn_TypeDef I2C_Transfer (I2C_TypeDef *i2c)

Continue an initiated I2C transfer (single master mode only).

This function is used repeatedly after a I2C_TransferInit() to complete a transfer. It may be used in polled mode as the below example shows:

I2C_TransferReturn_TypeDef ret;

// Do a polled transfer
ret = I2C_TransferInit(I2C0, seq);
while (ret == i2cTransferInProgress)
{
  ret = I2C_Transfer(I2C0);
}

It may also be used in interrupt driven mode, where this function is invoked from the interrupt handler. Notice that, if used in interrupt mode, NVIC interrupts must be configured and enabled for the I2C bus used. I2C peripheral specific interrupts are managed by this software.

Note

• Only single master mode is supported.

Returns

• Returns status for an ongoing transfer.

  • i2cTransferInProgress - indicates that transfer not finished.

  • i2cTransferDone - transfer completed successfully.

  • otherwise some sort of error has occurred.

I2C_TransferInit#

I2C_TransferReturn_TypeDef I2C_TransferInit (I2C_TypeDef *i2c, I2C_TransferSeq_TypeDef *seq)

Prepare and start an I2C transfer (single master mode only).

This function must be invoked to start an I2C transfer sequence. To complete the transfer, I2C_Transfer() must be used either in polled mode or by adding a small driver wrapper using interrupts.

Note

• Only single master mode is supported.

Returns

• Returns the status for an ongoing transfer:

  • i2cTransferInProgress - indicates that the transfer is not finished.

  • Otherwise, an error has occurred.

I2C_IntClear#

void I2C_IntClear (I2C_TypeDef *i2c, uint32_t flags)

Clear one or more pending I2C interrupts.

I2C_IntDisable#

void I2C_IntDisable (I2C_TypeDef *i2c, uint32_t flags)

Disable one or more I2C interrupts.

I2C_IntEnable#

void I2C_IntEnable (I2C_TypeDef *i2c, uint32_t flags)

Enable one or more I2C interrupts.

Note

• Depending on the use, a pending interrupt may already be set prior to enabling the interrupt. To ignore a pending interrupt, consider using I2C_IntClear() prior to enabling the interrupt.

I2C_IntGet#

uint32_t I2C_IntGet (I2C_TypeDef *i2c)

Get pending I2C interrupt flags.

Note

• Event bits are not cleared by the use of this function.

Returns

• I2C interrupt sources pending. A bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn).

I2C_IntGetEnabled#

uint32_t I2C_IntGetEnabled (I2C_TypeDef *i2c)

Get enabled and pending I2C interrupt flags.

Useful for handling more interrupt sources in the same interrupt handler.

Note

• Interrupt flags are not cleared by the use of this function.

Returns

• Pending and enabled I2C interrupt sources Return value is the bitwise AND of

  • the enabled interrupt sources in I2Cn_IEN and

  • the pending interrupt flags I2Cn_IF

I2C_IntSet#

void I2C_IntSet (I2C_TypeDef *i2c, uint32_t flags)

Set one or more pending I2C interrupts from SW.

I2C_SlaveAddressGet#

uint8_t I2C_SlaveAddressGet (I2C_TypeDef *i2c)

Get Target address used for I2C peripheral (when operating in Target mode).

For 10-bit addressing mode, the address is split in two bytes, and only the first byte setting is fetched, effectively only controlling the 2 most significant bits of the 10-bit address. Full handling of 10-bit addressing in Target mode requires additional SW handling.

Returns

• I2C Target address in use. The 7 most significant bits define the actual address, the least significant bit is reserved and always returned as 0.

I2C_SlaveAddressSet#

void I2C_SlaveAddressSet (I2C_TypeDef *i2c, uint8_t addr)

Set Target address to use for I2C peripheral (when operating in Target mode).

For 10- bit addressing mode, the address is split in two bytes, and only the first byte is set, effectively only controlling the 2 most significant bits of the 10-bit address. Full handling of 10-bit addressing in Target mode requires additional SW handling.

I2C_SlaveAddressMaskGet#

uint8_t I2C_SlaveAddressMaskGet (I2C_TypeDef *i2c)

Get Target address mask used for I2C peripheral (when operating in Target mode).

The address mask defines how the comparator works. A bit position with value 0 means that the corresponding Target address bit is ignored during comparison (don't care). A bit position with value 1 means that the corresponding Target address bit must match.

For 10-bit addressing mode, the address is split in two bytes, and only the mask for the first address byte is fetched, effectively only controlling the 2 most significant bits of the 10-bit address.

Returns

• I2C Target address mask in use. The 7 most significant bits define the actual address mask, the least significant bit is reserved and always returned as 0.

I2C_SlaveAddressMaskSet#

void I2C_SlaveAddressMaskSet (I2C_TypeDef *i2c, uint8_t mask)

Set Target address mask used for I2C peripheral (when operating in Target mode).

The address mask defines how the comparator works. A bit position with value 0 means that the corresponding Target address bit is ignored during comparison (don't care). A bit position with value 1 means that the corresponding Target address bit must match.

For 10-bit addressing mode, the address is split in two bytes, and only the mask for the first address byte is set, effectively only controlling the 2 most significant bits of the 10-bit address.

I2C_FREQ_STANDARD_MAX#

#define I2C_FREQ_STANDARD_MAX

100000

Standard mode max frequency assuming using 4:4 ratio for Nlow:Nhigh.

From I2C specification: Min Tlow = 4.7us, min Thigh = 4.0us, max Trise=1.0us, max Tfall=0.3us. Since ratio is 4:4, have to use worst case value of Tlow or Thigh as base.

1/(Tlow + Thigh + 1us + 0.3us) = 1/(4.7 + 4.7 + 1.3)us = 93458Hz Note

• Due to chip characteristics, max value is somewhat reduced.

I2C_FREQ_FAST_MAX#

#define I2C_FREQ_FAST_MAX

392157

Fast mode max frequency assuming using 6:3 ratio for Nlow:Nhigh.

From I2C specification: Min Tlow = 1.3us, min Thigh = 0.6us, max Trise=0.3us, max Tfall=0.3us. Since ratio is 6:3, have to use worst case value of Tlow or 2xThigh as base.

1/(Tlow + Thigh + 0.3us + 0.3us) = 1/(1.3 + 0.65 + 0.6)us = 392157Hz

I2C_FREQ_FASTPLUS_MAX#

#define I2C_FREQ_FASTPLUS_MAX

987167

Fast mode+ max frequency assuming using 11:6 ratio for Nlow:Nhigh.

From I2C specification: Min Tlow = 0.5us, min Thigh = 0.26us, max Trise=0.12us, max Tfall=0.12us. Since ratio is 11:6, have to use worst case value of Tlow or (11/6)xThigh as base.

1/(Tlow + Thigh + 0.12us + 0.12us) = 1/(0.5 + 0.273 + 0.24)us = 987167Hz

I2C_FLAG_WRITE#

#define I2C_FLAG_WRITE

0x0001

Indicate plain write sequence: S+ADDR(W)+DATA0+P.

• S - Start

• ADDR(W) - address with W/R bit cleared

• DATA0 - Data taken from buffer with index 0

• P - Stop

I2C_FLAG_READ#

#define I2C_FLAG_READ

0x0002

Indicate plain read sequence: S+ADDR(R)+DATA0+P.

• S - Start

• ADDR(R) - Address with W/R bit set

• DATA0 - Data read into buffer with index 0

• P - Stop

I2C_FLAG_WRITE_READ#

#define I2C_FLAG_WRITE_READ

0x0004

Indicate combined write/read sequence: S+ADDR(W)+DATA0+Sr+ADDR(R)+DATA1+P.

• S - Start

• Sr - Repeated start

• ADDR(W) - Address with W/R bit cleared

• ADDR(R) - Address with W/R bit set

• DATAn - Data written from/read into buffer with index n

• P - Stop

I2C_FLAG_WRITE_WRITE#

#define I2C_FLAG_WRITE_WRITE

0x0008

Indicate write sequence using two buffers: S+ADDR(W)+DATA0+DATA1+P.

• S - Start

• ADDR(W) - Address with W/R bit cleared

• DATAn - Data written from buffer with index n

• P - Stop

I2C_FLAG_10BIT_ADDR#

#define I2C_FLAG_10BIT_ADDR

0x0010

Use 10 bit address.

I2C_INIT_DEFAULT#

#define I2C_INIT_DEFAULT

Suggested default configuration for I2C initialization structure.