Low-level I2C peripheral driver. More...

Detailed Description

Low-level I2C peripheral driver.

This is a simple I2C interface to allow platform independent access to a MCU's I2C bus and peripherals. This interface is intentionally designed as simple as possible, to allow for easy implementation and maximal portability.

Note
The current version of this interface only supports the 7-bit addressing mode.
This interface is due for remodeling, hence API changes are to be expected for upcoming releases.

A note on pull-up resistors for SDA/SCL

The I2C signal lines SDA/SCL need external pull-up resistors which connect the lines to the positive voltage supply VCC. The I2C driver implementation should enable the pin's internal pull-up resistors. There are however some use cases for which the internal pull resistors are not strong enough and the I2C bus will show faulty behavior. This can for example happen when connecting a logic analyzer which will raise the capacitance of the bus. In this case you should make sure you connect external pull-up resistors to both I2C bus lines.

The minimum and maximum resistances are computed by:

\begin{eqnarray*} R_{min} &=& \frac{V_{DD} - V_{OL(max)}} {I_{OL}}\\ R_{max} &=& \frac{t_r} {(0.8473 \cdot C_b)} \end{eqnarray*}


where:
$ V_{DD} =$ Supply voltage, $ V_{OL(max)} =$ Low level voltage, $ I_{OL} =$ Low level output current, $ t_r =$ Signal rise time, $ C_b =$ Bus capacitance

The pull-up resistors depend on the bus speed. Some typical values are:
Normal mode: 10kΩ
Fast mode: 2kΩ
Fast plus mode: 2kΩ

For more details refer to section 7.1 in:
http://www.nxp.com/documents/user_manual/UM10204.pdf

Files

file  i2c.h
 Low-level I2C peripheral driver interface definition.
 

Macros

#define I2C_FLAG_WRITE   0
 Flag signaling a write operation on the bus. More...
 
#define I2C_FLAG_READ   1
 Flag signaling a read operation on the bus.
 
#define I2C_DEV(x)   (x)
 Default I2C device access macro.
 
#define I2C_UNDEF   (UINT_MAX)
 Default I2C undefined value.
 

Typedefs

typedef unsigned int i2c_t
 Default i2c_t type definition.
 

Enumerations

enum  i2c_speed_t {
  I2C_SPEED_LOW = 0x01, I2C_SPEED_NORMAL = TWI_FREQUENCY_FREQUENCY_K100, I2C_SPEED_FAST = TWI_FREQUENCY_FREQUENCY_K400, I2C_SPEED_FAST_PLUS = 0x02,
  I2C_SPEED_HIGH = 0x03, I2C_SPEED_LOW = 0, I2C_SPEED_NORMAL, I2C_SPEED_FAST,
  I2C_SPEED_FAST_PLUS, I2C_SPEED_HIGH
}
 Default mapping of I2C bus speed values. More...
 

Functions

int i2c_init_master (i2c_t dev, i2c_speed_t speed)
 Initialize an I2C device to run as bus master. More...
 
int i2c_acquire (i2c_t dev)
 Get mutually exclusive access to the given I2C bus. More...
 
int i2c_release (i2c_t dev)
 Release the given I2C device to be used by others. More...
 
int i2c_read_byte (i2c_t dev, uint8_t address, void *data)
 Read one byte from an I2C device with the given address. More...
 
int i2c_read_bytes (i2c_t dev, uint8_t address, void *data, int length)
 Read multiple bytes from an I2C device with the given address. More...
 
int i2c_read_reg (i2c_t dev, uint8_t address, uint8_t reg, void *data)
 Read one byte from a register at the I2C slave with the given address. More...
 
int i2c_read_regs (i2c_t dev, uint8_t address, uint8_t reg, void *data, int length)
 Read multiple bytes from a register at the I2C slave with the given address. More...
 
int i2c_write_byte (i2c_t dev, uint8_t address, uint8_t data)
 Write one byte to an I2C device with the given address. More...
 
int i2c_write_bytes (i2c_t dev, uint8_t address, const void *data, int length)
 Write multiple bytes to an I2C device with the given address. More...
 
int i2c_write_reg (i2c_t dev, uint8_t address, uint8_t reg, uint8_t data)
 Write one byte to a register at the I2C slave with the given address. More...
 
int i2c_write_regs (i2c_t dev, uint8_t address, uint8_t reg, const void *data, int length)
 Write multiple bytes to a register at the I2C slave with the given address. More...
 
void i2c_poweron (i2c_t dev)
 Power on the given I2C peripheral. More...
 
void i2c_poweroff (i2c_t dev)
 Power off the given I2C peripheral. More...
 

Macro Definition Documentation

◆ I2C_FLAG_WRITE

#define I2C_FLAG_WRITE   0

Flag signaling a write operation on the bus.

Todo:
Remove dev_enums.h include once all platforms are ported to the updated periph interface

Definition at line 83 of file i2c.h.

Enumeration Type Documentation

◆ i2c_speed_t

Default mapping of I2C bus speed values.

Enumerator
I2C_SPEED_LOW 

not supported

I2C_SPEED_NORMAL 

100kbit/s

I2C_SPEED_FAST 

400kbit/s

I2C_SPEED_FAST_PLUS 

not supported

I2C_SPEED_HIGH 

not supported

I2C_SPEED_LOW 

low speed mode: ~10kbit/s

I2C_SPEED_NORMAL 

normal mode: ~100kbit/s

I2C_SPEED_FAST 

fast mode: ~400kbit/sj

I2C_SPEED_FAST_PLUS 

fast plus mode: ~1Mbit/s

I2C_SPEED_HIGH 

high speed mode: ~3.4Mbit/s

Definition at line 115 of file i2c.h.

Function Documentation

◆ i2c_acquire()

int i2c_acquire ( i2c_t  dev)

Get mutually exclusive access to the given I2C bus.

In case the I2C device is busy, this function will block until the bus is free again.

Parameters
[in]devI2C device to access
Returns
0 on success
-1 on error

◆ i2c_init_master()

int i2c_init_master ( i2c_t  dev,
i2c_speed_t  speed 
)

Initialize an I2C device to run as bus master.

Parameters
[in]devthe device to initialize
[in]speedthe selected bus speed
Returns
0 on successful initialization
-1 on undefined device given
-2 on unsupported speed value

◆ i2c_poweroff()

void i2c_poweroff ( i2c_t  dev)

Power off the given I2C peripheral.

Parameters
[in]devthe I2C device to power off

◆ i2c_poweron()

void i2c_poweron ( i2c_t  dev)

Power on the given I2C peripheral.

Parameters
[in]devthe I2C device to power on

◆ i2c_read_byte()

int i2c_read_byte ( i2c_t  dev,
uint8_t  address,
void *  data 
)

Read one byte from an I2C device with the given address.

Parameters
[in]devI2C peripheral device
[in]addressbus address of the target device
[out]datathe result that was read
Returns
the number of bytes that were read
-1 on undefined device given
-2 on invalid address

◆ i2c_read_bytes()

int i2c_read_bytes ( i2c_t  dev,
uint8_t  address,
void *  data,
int  length 
)

Read multiple bytes from an I2C device with the given address.

Parameters
[in]devI2C peripheral device
[in]addressbus address of the target device
[out]dataarray holding the received bytes
[in]lengththe number of bytes to read into data
Returns
the number of bytes that were read
-1 on undefined device given

◆ i2c_read_reg()

int i2c_read_reg ( i2c_t  dev,
uint8_t  address,
uint8_t  reg,
void *  data 
)

Read one byte from a register at the I2C slave with the given address.

Parameters
[in]devI2C peripheral device
[in]addressbus address of the target device
[in]regthe register address on the targeted I2C device
[out]datathe result that was read
Returns
the number of bytes that were read
-1 on undefined device given

◆ i2c_read_regs()

int i2c_read_regs ( i2c_t  dev,
uint8_t  address,
uint8_t  reg,
void *  data,
int  length 
)

Read multiple bytes from a register at the I2C slave with the given address.

Parameters
[in]devI2C peripheral device
[in]addressbus address of the target device
[in]regthe register address on the targeted I2C device
[out]dataarray holding the received bytes
[in]lengththe number of bytes to read into data
Returns
the number of bytes that were read
-1 on undefined device given

◆ i2c_release()

int i2c_release ( i2c_t  dev)

Release the given I2C device to be used by others.

Parameters
[in]devI2C device to release
Returns
0 on success
-1 on error

◆ i2c_write_byte()

int i2c_write_byte ( i2c_t  dev,
uint8_t  address,
uint8_t  data 
)

Write one byte to an I2C device with the given address.

Parameters
[in]devI2C peripheral device
[in]addressbus address of the target device
[in]databyte to write to the device
Returns
the number of bytes that were written
-1 on undefined device given

◆ i2c_write_bytes()

int i2c_write_bytes ( i2c_t  dev,
uint8_t  address,
const void *  data,
int  length 
)

Write multiple bytes to an I2C device with the given address.

Parameters
[in]devI2C peripheral device
[in]addressbus address of the target device
[in]dataarray with bytes to write to the target device
[in]lengthnumber of bytes to write to the target device
Returns
the number of bytes that were written
-1 on undefined device given

◆ i2c_write_reg()

int i2c_write_reg ( i2c_t  dev,
uint8_t  address,
uint8_t  reg,
uint8_t  data 
)

Write one byte to a register at the I2C slave with the given address.

Parameters
[in]devI2C peripheral device
[in]addressbus address of the target device
[in]regthe register address on the targeted I2C device
[in]databyte to write to the device
Returns
the number of bytes that were written
-1 on undefined device given

◆ i2c_write_regs()

int i2c_write_regs ( i2c_t  dev,
uint8_t  address,
uint8_t  reg,
const void *  data,
int  length 
)

Write multiple bytes to a register at the I2C slave with the given address.

Parameters
[in]devI2C peripheral device
[in]addressbus address of the target device
[in]regthe register address on the targeted I2C device
[in]dataarray with bytes to write to the target device
[in]lengthnumber of bytes to write to the target device
Returns
the number of bytes that were written
-1 on undefined device given