I2C - Inter-Integrated Circuit#
Inter-integrated Circuit (I2C) Peripheral API.
This module contains functions to control the I2C peripheral of Silicon Labs 32-bit MCUs and SoCs. The I2C interface allows communication on I2C buses with the lowest energy consumption possible.
Modules#
Enumerations#
Clock low to high ratio settings.
Return codes for single Controller mode transfer function.
Functions#
Get the current configured I2C bus frequency.
Set the I2C bus frequency.
Enable/disable I2C.
Initialize I2C.
Clear one or more pending I2C interrupts.
Disable one or more I2C interrupts.
Enable one or more I2C interrupts.
Get pending I2C interrupt flags.
Get enabled and pending I2C interrupt flags.
Set one or more pending I2C interrupts from SW.
Reset I2C to the same state that it was in after a hardware reset.
Get Target address used for I2C peripheral (when operating in Target mode).
Set Target address to use for I2C peripheral (when operating in Target mode).
Get Target address mask used for I2C peripheral (when operating in Target mode).
Set Target address mask used for I2C peripheral (when operating in Target mode).
Continue an initiated I2C transfer (single master mode only).
Prepare and start an I2C transfer (single master mode only).
Macros#
Standard mode max frequency assuming using 4:4 ratio for Nlow:Nhigh.
Fast mode max frequency assuming using 6:3 ratio for Nlow:Nhigh.
Fast mode+ max frequency assuming using 11:6 ratio for Nlow:Nhigh.
Indicate plain write sequence: S+ADDR(W)+DATA0+P.
Indicate plain read sequence: S+ADDR(R)+DATA0+P.
Indicate combined write/read sequence: S+ADDR(W)+DATA0+Sr+ADDR(R)+DATA1+P.
Indicate write sequence using two buffers: S+ADDR(W)+DATA0+DATA1+P.
Use 10 bit address.
Suggested default configuration for I2C initialization structure.
Enumeration Documentation#
I2C_ClockHLR_TypeDef#
I2C_ClockHLR_TypeDef
Clock low to high ratio settings.
Enumerator | |
---|---|
i2cClockHLRStandard | Ratio is 4:4. |
i2cClockHLRAsymetric | Ratio is 6:3. |
i2cClockHLRFast | Ratio is 11:3. |
162
of file platform/emlib/inc/em_i2c.h
I2C_TransferReturn_TypeDef#
I2C_TransferReturn_TypeDef
Return codes for single Controller mode transfer function.
Enumerator | |
---|---|
i2cTransferInProgress | Transfer in progress. |
i2cTransferDone | Transfer completed successfully. |
i2cTransferNack | NACK received during transfer. |
i2cTransferBusErr | Bus error during transfer (misplaced START/STOP). |
i2cTransferArbLost | Arbitration lost during transfer. |
i2cTransferUsageFault | Usage fault. |
i2cTransferSwFault | SW fault. |
169
of file platform/emlib/inc/em_i2c.h
Function Documentation#
I2C_BusFreqGet#
uint32_t I2C_BusFreqGet (I2C_TypeDef * i2c)
Get the current configured I2C bus frequency.
[in] | i2c | A pointer to the I2C peripheral register block. |
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.
203
of file platform/emlib/src/em_i2c.c
I2C_BusFreqSet#
void I2C_BusFreqSet (I2C_TypeDef * i2c, uint32_t freqRef, uint32_t freqScl, I2C_ClockHLR_TypeDef i2cMode)
Set the I2C bus frequency.
[in] | i2c | A pointer to the I2C peripheral register block. |
[in] | freqRef | An I2C reference clock frequency in Hz that will be used. If set to 0, HFPERCLK / HFPERCCLK clock is used. Setting it to a higher than actual configured value has the consequence of reducing the real I2C frequency. |
[in] | freqScl | A bus frequency to set (bus speed may be lower due to integer prescaling). Safe (according to the I2C specification) maximum frequencies for standard fast and fast+ modes are available using I2C_FREQ_ defines. (Using I2C_FREQ_ defines requires corresponding setting of |
[in] | i2cMode | A clock low-to-high ratio type to use. If not using i2cClockHLRStandard, make sure all devices on the bus support the specified mode. Using a non-standard ratio is useful to achieve a higher bus clock in fast and fast+ modes. |
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.
268
of file platform/emlib/src/em_i2c.c
I2C_Enable#
void I2C_Enable (I2C_TypeDef * i2c, bool enable)
Enable/disable I2C.
[in] | i2c | A pointer to the I2C peripheral register block. |
[in] | enable | True to enable counting, false to disable. |
Note
After enabling the I2C (from being disabled), the I2C is in BUSY state.
403
of file platform/emlib/src/em_i2c.c
I2C_Init#
void I2C_Init (I2C_TypeDef * i2c, const I2C_Init_TypeDef * init)
Initialize I2C.
[in] | i2c | A pointer to the I2C peripheral register block. |
[in] | init | A pointer to the I2C initialization structure. |
424
of file platform/emlib/src/em_i2c.c
I2C_IntClear#
void I2C_IntClear (I2C_TypeDef * i2c, uint32_t flags)
Clear one or more pending I2C interrupts.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | flags | Pending I2C interrupt source to clear. Use a bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn). |
294
of file platform/emlib/inc/em_i2c.h
I2C_IntDisable#
void I2C_IntDisable (I2C_TypeDef * i2c, uint32_t flags)
Disable one or more I2C interrupts.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | flags | I2C interrupt sources to disable. Use a bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn). |
314
of file platform/emlib/inc/em_i2c.h
I2C_IntEnable#
void I2C_IntEnable (I2C_TypeDef * i2c, uint32_t flags)
Enable one or more I2C interrupts.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | flags | I2C interrupt sources to enable. Use a bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn). |
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.
339
of file platform/emlib/inc/em_i2c.h
I2C_IntGet#
uint32_t I2C_IntGet (I2C_TypeDef * i2c)
Get pending I2C interrupt flags.
[in] | i2c | Pointer to I2C peripheral register block. |
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).
362
of file platform/emlib/inc/em_i2c.h
I2C_IntGetEnabled#
uint32_t I2C_IntGetEnabled (I2C_TypeDef * i2c)
Get enabled and pending I2C interrupt flags.
[in] | i2c | Pointer to I2C peripheral register block. |
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
384
of file platform/emlib/inc/em_i2c.h
I2C_IntSet#
void I2C_IntSet (I2C_TypeDef * i2c, uint32_t flags)
Set one or more pending I2C interrupts from SW.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | flags | I2C interrupt sources to set to pending. Use a bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn). |
403
of file platform/emlib/inc/em_i2c.h
I2C_Reset#
void I2C_Reset (I2C_TypeDef * i2c)
Reset I2C to the same state that it was in after a hardware reset.
[in] | i2c | A pointer to the I2C peripheral register block. |
Note
The ROUTE register is NOT reset by this function to allow for centralized setup of this feature.
450
of file platform/emlib/src/em_i2c.c
I2C_SlaveAddressGet#
uint8_t I2C_SlaveAddressGet (I2C_TypeDef * i2c)
Get Target address used for I2C peripheral (when operating in Target mode).
[in] | i2c | Pointer to I2C peripheral register block. |
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.
431
of file platform/emlib/inc/em_i2c.h
I2C_SlaveAddressSet#
void I2C_SlaveAddressSet (I2C_TypeDef * i2c, uint8_t addr)
Set Target address to use for I2C peripheral (when operating in Target mode).
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | addr | I2C Target address to use. The 7 most significant bits define the actual address, the least significant bit is reserved and always set to 0. |
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.
453
of file platform/emlib/inc/em_i2c.h
I2C_SlaveAddressMaskGet#
uint8_t I2C_SlaveAddressMaskGet (I2C_TypeDef * i2c)
Get Target address mask used for I2C peripheral (when operating in Target mode).
[in] | i2c | Pointer to I2C peripheral register block. |
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.
481
of file platform/emlib/inc/em_i2c.h
I2C_SlaveAddressMaskSet#
void I2C_SlaveAddressMaskSet (I2C_TypeDef * i2c, uint8_t mask)
Set Target address mask used for I2C peripheral (when operating in Target mode).
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | mask | I2C Target address mask to use. The 7 most significant bits define the actual address mask, the least significant bit is reserved and should be 0. |
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.
509
of file platform/emlib/inc/em_i2c.h
I2C_Transfer#
I2C_TransferReturn_TypeDef I2C_Transfer (I2C_TypeDef * i2c)
Continue an initiated I2C transfer (single master mode only).
[in] | i2c | A pointer to the I2C peripheral register block. |
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.
505
of file platform/emlib/src/em_i2c.c
I2C_TransferInit#
I2C_TransferReturn_TypeDef I2C_TransferInit (I2C_TypeDef * i2c, I2C_TransferSeq_TypeDef * seq)
Prepare and start an I2C transfer (single master mode only).
[in] | i2c | A pointer to the I2C peripheral register block. |
[in] | seq | A pointer to the sequence structure defining the I2C transfer to take place. The referenced structure must exist until the transfer has fully completed. |
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.
868
of file platform/emlib/src/em_i2c.c
Macro Definition Documentation#
I2C_FREQ_STANDARD_MAX#
#define I2C_FREQ_STANDARD_MAXValue:
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.
79
of file platform/emlib/inc/em_i2c.h
I2C_FREQ_FAST_MAX#
#define I2C_FREQ_FAST_MAXValue:
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
94
of file platform/emlib/inc/em_i2c.h
I2C_FREQ_FASTPLUS_MAX#
#define I2C_FREQ_FASTPLUS_MAXValue:
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
106
of file platform/emlib/inc/em_i2c.h
I2C_FLAG_WRITE#
#define I2C_FLAG_WRITEValue:
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
117
of file platform/emlib/inc/em_i2c.h
I2C_FLAG_READ#
#define I2C_FLAG_READValue:
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
128
of file platform/emlib/inc/em_i2c.h
I2C_FLAG_WRITE_READ#
#define I2C_FLAG_WRITE_READValue:
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
141
of file platform/emlib/inc/em_i2c.h
I2C_FLAG_WRITE_WRITE#
#define I2C_FLAG_WRITE_WRITEValue:
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
152
of file platform/emlib/inc/em_i2c.h
I2C_FLAG_10BIT_ADDR#
#define I2C_FLAG_10BIT_ADDRValue:
0x0010
Use 10 bit address.
155
of file platform/emlib/inc/em_i2c.h
I2C_INIT_DEFAULT#
#define I2C_INIT_DEFAULTValue:
Suggested default configuration for I2C initialization structure.
214
of file platform/emlib/inc/em_i2c.h