i2c.h

Low-level I2C peripheral driver interface definition.

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
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.

See also

https://www.i2c-bus.org/addressing/10-bit-addressing/

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