C I2C API

Defines

I2C_MASTER

IOCTL master role value.

I2C_SLAVE

IOCTL slave role value.

Enums

enum KI2CStatus

I2C function status.

Values:

enumerator I2C_OK
enumerator I2C_ERROR
enumerator I2C_ERROR_AF
enumerator I2C_ERROR_ADDR_TIMEOUT
enumerator I2C_ERROR_TIMEOUT
enumerator I2C_ERROR_NACK
enumerator I2C_ERROR_TXE_TIMEOUT
enumerator I2C_ERROR_BTF_TIMEOUT
enumerator I2C_ERROR_NULL_HANDLE
enumerator I2C_ERROR_CONFIG

Functions

KI2CStatus k_i2c_init(char *device, int *fp)

Configures and enables an I2C bus.

This function is used to configure and enable I2C buses for further usage (reading/writing). It is always the first required step before using any I2C peripheral. The k_i2c_init function takes an I2C device name and a pointer to where the returned file descriptor should be stored After correctly calling k_i2c_init, the returned file descriptor may be used with the k_i2c_read/k_i2c_write/k_i2c_terminate functions.

Example usage: 

int bus = 0;
k_i2c_init("/dev/i2c-1", &bus);

Parameters

  • device – I2C device name to initialize

  • fp – Pointer to storage for file descriptor of I2C bus

Returns

KI2CStatus I2C_OK on success, otherwise return I2C_ERROR_*

void k_i2c_terminate(int *fp)

Terminates an I2C bus.

This fuction is used to terminate an active I2C bus connection. It takes a pointer to the file descriptor to be closed. After calling this function the device will not be available for usage in the reading/writing functions.

Example usage: 

// initialize bus
int bus = 0;
k_i2c_init("/dev/i2c-1", &bus);
// read some data
k_i2c_read(bus, addr, buffer, 10);
// shut down bus
k_i2C_terminate(bus);

Parameters

fp – Pointer to file descriptor of I2C bus which should be closed

KI2CStatus k_i2c_write(int i2c, uint16_t addr, uint8_t *ptr, int len)

Write data over the I2C bus to specified address.

This function writes data over the specified I2C bus to the specified slave address. The actual low-level I2C writing is delegated to the hardware specific kprv_i2c_*_write functions. This function is intended to be used on an I2C bus which has already been initialized.

Example usage: 

int bus = 0;
k_i2c_init("/dev/i2c-1", &bus);
uint8_t cmd = 0x40;
uint16_t slave_addr = 0x80;
KI2CStatus write_status;
write_status = k_i2c_write(bus, slave_addr, &cmd, 1);

In order to ensure safe I2C sharing, this function is semaphore locked. There is one semaphore per bus. This function will block indefinitely while waiting for the semaphore.

Parameters

  • i2c – I2C bus to transmit over

  • addr – address of target I2C device

  • ptr – pointer to data buffer

  • len – length of data in buffer

Returns

KI2CStatus I2C_OK on success, I2C_ERROR on error

KI2CStatus k_i2c_read(int i2c, uint16_t addr, uint8_t *ptr, int len)

Read data over the I2C bus from specified address.

This function reads data from the specified I2C bus from the specified slave address. The actual low-level I2C reading is delegated to the hardware specific kprv_i2c_*_read functions. This function is intended to be used on an I2C bus which has already been initialized.

Example usage: 

int bus = 0;
k_i2c_init("/dev/i2c-1", &bus);
uint8_t buffer[10];
int read_len = 10;
uint16_t slave_addr = 0x80;
KI2CStatus read_status;
read_status = k_i2c_read(bus, slave_addr, buffer, read_len);

In order to ensure safe I2C sharing, this function is semaphore locked. There is one semaphore per bus. This function will block indefinitely while waiting for the semaphore.

Parameters

  • i2c – I2C bus to read from

  • addr – address of target I2C device

  • ptr – pointer to data buffer

  • len – length of data to read

Returns

KI2CStatus I2C_OK on success, I2C_ERROR on error