I2C

Low-level I2C peripheral driver.

This interface provides a simple abstraction to use the MCUs I2C peripherals. It provides support for 7-bit and 10-bit addressing and can be used for different kind of register addressing schemes.

Usage

Example for reading a 8-bit register on a device, using a 10-bit device address and 8-bit register addresses and using a RESTART condition (CAUTION: this example does not check any return values…):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// initialize the bus (this is normally done during boot time)
i2c_init(dev);
...
// before accessing the bus, we need to acquire it
i2c_acquire(dev);
// next we write the register address, but create no STOP condition when done
i2c_write_byte(dev, device_addr, reg_addr, (I2C_NOSTOP | I2C_ADDR10));
// and now we read the register value
i2c_read_byte(dev, device_addr, &reg_value, I2C_ADDR10);
// finally we have to release the bus
i2c_release(dev);

Example for writing a 16-bit register with 16-bit register addressing and 7-bit device addressing:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// initialize the bus
i2c_init(dev);
...
// first, acquire the shared bus again
i2c_acquire(dev);
// write the 16-bit register address to the device and prevent STOP condition
i2c_write_byte(dev, device_addr, reg_addr, I2C_NOSTOP);
// and write the data after a REPEATED START
i2c_write_bytes(dev, device_addr, reg_data, 2, 0);
// and finally free the bus again
i2c_release(dev);

Pull Resistors

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: where: Supply voltage, Low level voltage, Low level output current, Signal rise time, 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

(Low-) power implications

The I2C interface realizes a transaction-based access scheme to the bus. From a power management perspective, we can leverage this by only powering on the I2C peripheral while it is actually used, that is inside an i2c.h::i2c_acquire() - i2c.h::i2c_release() block.

After initialization, the I2C peripheral should be powered off (e.g. through peripheral clock gating). It should only be powered on once a transaction on the I2C bus starts, namely in the i2c.h::i2c_acquire() function. Once the transaction is finished, the corresponding I2C peripheral should be powered off again in the i2c.h::i2c_release() function.

If the implementation puts the active thread to sleep while a transfer is in progress (e.g. when using DMA), the implementation might need to block certain power states.

I2C_DEV( x)

Default I2C device access macro.

1
(x)

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

I2C_UNDEF

Default I2C undefined value.

1
(UINT_MAX)
unsigned int i2c_t

Default i2c_t type definition.

enum i2c_speed_t
I2C_SPEED_LOW = 0x01
not supported
I2C_SPEED_NORMAL = 100000U
normal mode: ~100kbit/s
I2C_SPEED_FAST = 400000U
fast mode: ~400kbit/s
I2C_SPEED_FAST_PLUS = 0x02
not supported
I2C_SPEED_HIGH = 0x03
not supported
enum i2c_flags_t
I2C_ADDR10 = 0x01
use 10-bit device addressing
I2C_REG16 = 0x02
use 16-bit register addressing
I2C_NOSTOP = 0x04
do not issue a STOP condition after transfer
I2C_NOSTART = 0x08
skip START sequence, ignores address field
void i2c_init(i2c.h::i2c_t dev)

Initialize the given I2C bus.

The given I2C device will be initialized with the parameters as specified in the boards periph_conf.h, using the pins and the speed value given there.

The bus MUST not be acquired before initializing it, as this is handled internally by the i2c_init function!

Parameters

dev:the device to initialize

int i2c_acquire(i2c.h::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

dev:I2C device to access

Return values

  • 0 on success, -1 on error
int i2c_release(i2c.h::i2c_t dev)

Release the given I2C device to be used by others.

Parameters

dev:I2C device to release

Return values

  • 0 on success, -1 on error
int i2c_read_reg(i2c.h::i2c_t dev, uint16_t addr, uint16_t reg, void * data, uint8_t flags)

Convenience function for reading one byte from a given register address.

Note

This function is using a repeated start sequence for reading from the specified register address.

Parameters

dev:I2C peripheral device
reg:register address to read from (8- or 16-bit, right-aligned)
addr:7-bit or 10-bit device address (right-aligned)
data:memory location to store received data
flags:optional flags (see i2c.h::i2c_flags_t)

Return values

  • 0 When success
  • -EIO When slave device doesn’t ACK the byte
  • -ENXIO When no devices respond on the address sent on the bus
  • -ETIMEDOUT When timeout occurs before device’s response
  • -EINVAL When an invalid argument is given
  • -EOPNOTSUPP When MCU driver doesn’t support the flag operation
  • -EAGAIN When a lost bus arbitration occurs
int i2c_read_regs(i2c.h::i2c_t dev, uint16_t addr, uint16_t reg, void * data, msp430_types.h::size_t len, uint8_t flags)

Convenience function for reading several bytes from a given register address.

Note

This function is using a repeated start sequence for reading from the specified register address.

Parameters

dev:I2C peripheral device
reg:register address to read from (8- or 16-bit, right-aligned)
addr:7-bit or 10-bit device address (right-aligned)
data:memory location to store received data
len:the number of bytes to read into data
flags:optional flags (see i2c.h::i2c_flags_t)

Return values

  • 0 When success
  • -EIO When slave device doesn’t ACK the byte
  • -ENXIO When no devices respond on the address sent on the bus
  • -ETIMEDOUT When timeout occurs before device’s response
  • -EINVAL When an invalid argument is given
  • -EOPNOTSUPP When MCU driver doesn’t support the flag operation
  • -EAGAIN When a lost bus arbitration occurs
int i2c_read_byte(i2c.h::i2c_t dev, uint16_t addr, void * data, uint8_t flags)

Convenience function for reading one byte from a device.

Note

This function is using a repeated start sequence for reading from the specified register address.

Parameters

dev:I2C peripheral device
addr:7-bit or 10-bit device address (right-aligned)
data:memory location to store received data
flags:optional flags (see i2c.h::i2c_flags_t)

Return values

  • 0 When success
  • -EIO When slave device doesn’t ACK the byte
  • -ENXIO When no devices respond on the address sent on the bus
  • -ETIMEDOUT When timeout occurs before device’s response
  • -EINVAL When an invalid argument is given
  • -EOPNOTSUPP When MCU driver doesn’t support the flag operation
  • -EAGAIN When a lost bus arbitration occurs
int i2c_read_bytes(i2c.h::i2c_t dev, uint16_t addr, void * data, msp430_types.h::size_t len, uint8_t flags)

Convenience function for reading bytes from a device.

Note

This function is using a repeated start sequence for reading from the specified register address.

Parameters

dev:I2C peripheral device
addr:7-bit or 10-bit device address (right-aligned)
data:memory location to store received data
len:the number of bytes to read into data
flags:optional flags (see i2c.h::i2c_flags_t)

Return values

  • 0 When success
  • -EIO When slave device doesn’t ACK the byte
  • -ENXIO When no devices respond on the address sent on the bus
  • -ETIMEDOUT When timeout occurs before device’s response
  • -EINVAL When an invalid argument is given
  • -EOPNOTSUPP When MCU driver doesn’t support the flag operation
  • -EAGAIN When a lost bus arbitration occurs
int i2c_write_byte(i2c.h::i2c_t dev, uint16_t addr, uint8_t data, uint8_t flags)

Convenience function for writing a single byte onto the bus.

Parameters

dev:I2C peripheral device
addr:7-bit or 10-bit device address (right-aligned)
data:byte to write to the device
flags:optional flags (see i2c.h::i2c_flags_t)

Return values

  • 0 When success
  • -EIO When slave device doesn’t ACK the byte
  • -ENXIO When no devices respond on the address sent on the bus
  • -ETIMEDOUT When timeout occurs before device’s response
  • -EINVAL When an invalid argument is given
  • -EOPNOTSUPP When MCU driver doesn’t support the flag operation
  • -EAGAIN When a lost bus arbitration occurs
int i2c_write_bytes(i2c.h::i2c_t dev, uint16_t addr, const void * data, msp430_types.h::size_t len, uint8_t flags)

Convenience function for writing several bytes onto the bus.

Parameters

dev:I2C peripheral device
addr:7-bit or 10-bit device address (right-aligned)
data:array holding the bytes to write to the device
len:the number of bytes to write
flags:optional flags (see i2c.h::i2c_flags_t)

Return values

  • 0 When success
  • -EIO When slave device doesn’t ACK the byte
  • -ENXIO When no devices respond on the address sent on the bus
  • -ETIMEDOUT When timeout occurs before device’s response
  • -EINVAL When an invalid argument is given
  • -EOPNOTSUPP When MCU driver doesn’t support the flag operation
  • -EAGAIN When a lost bus arbitration occurs
int i2c_write_reg(i2c.h::i2c_t dev, uint16_t addr, uint16_t reg, uint8_t data, uint8_t flags)

Convenience function for writing one byte to a given register address.

Note

This function is using a repeated start sequence for writing to the specified register address.

Parameters

dev:I2C peripheral device
reg:register address to read from (8- or 16-bit, right-aligned)
addr:7-bit or 10-bit device address (right-aligned)
data:byte to write
flags:optional flags (see i2c.h::i2c_flags_t)

Return values

  • 0 When success
  • -EIO When slave device doesn’t ACK the byte
  • -ENXIO When no devices respond on the address sent on the bus
  • -ETIMEDOUT When timeout occurs before device’s response
  • -EINVAL When an invalid argument is given
  • -EOPNOTSUPP When MCU driver doesn’t support the flag operation
  • -EAGAIN When a lost bus arbitration occurs
int i2c_write_regs(i2c.h::i2c_t dev, uint16_t addr, uint16_t reg, const void * data, msp430_types.h::size_t len, uint8_t flags)

Convenience function for writing data to a given register address.

Note

This function is using a repeated start sequence for writing to the specified register address.

Parameters

dev:I2C peripheral device
reg:register address to read from (8- or 16-bit, right-aligned)
addr:7-bit or 10-bit device address (right-aligned)
data:memory location to store received data
len:the number of bytes to write
flags:optional flags (see i2c.h::i2c_flags_t)

Return values

  • 0 When success
  • -EIO When slave device doesn’t ACK the byte
  • -ENXIO When no devices respond on the address sent on the bus
  • -ETIMEDOUT When timeout occurs before device’s response
  • -EINVAL When an invalid argument is given
  • -EOPNOTSUPP When MCU driver doesn’t support the flag operation
  • -EAGAIN When a lost bus arbitration occurs
I2C_READ

Read bit needs to be set when reading.

1
(0x0001)
I2C_10BIT_MAGIC

Special bit pattern indicating a 10 bit address is used.

1
(0xF0u)

Should only be used internally in CPU driver implementations, this is not intended to be used by applications.