C I2C API

Defines

K_NUM_I2CS

Number of I2C buses available.

Derived from value in target.json

"config": {
  "hardware": {
    "i2c": {
      "count": 2
    }
  }
}

DEFAULT_I2C

Default I2C bus.

Derived from value in target.json

"config": {
  "hardware": {
    "i2c": {
      "defaults": {
        "bus": "K_I2C1"
      }
    }
  }
}

Enums

enum KI2CNum

Available I2C buses.

Values:

K_I2C_NO_BUS = 0
enum I2CAddressingMode

Expected addressing mode of I2C bus.

Values:

K_ADDRESSINGMODE_7BIT = 0
K_ADDRESSINGMODE_10BIT
enum I2CRole

Expected role of I2C bus.

Warning
Only the Master role is available as of v0.0.4

Values:

K_MASTER = 0
K_SLAVE
enum KI2CStatus

I2C function status.

Values:

I2C_OK = 0
I2C_ERROR
I2C_ERROR_AF
I2C_ERROR_ADDR_TIMEOUT
I2C_ERROR_TIMEOUT
I2C_ERROR_NACK
I2C_ERROR_TXE_TIMEOUT
I2C_ERROR_BTF_TIMEOUT
I2C_ERROR_NULL_HANDLE
I2C_ERROR_CONFIG

Functions

KI2CStatus k_i2c_init(KI2CNum i2c, KI2CConf *conf)

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 bus number (KI2CNum) and I2C configuration structure (KI2CConf). The I2C bus number must be a valid value of the KI2CNum enum. The configuration can either be manually created or k_i2c_conf_defaults can be used to retreive the default configuration.

After correctly calling k_i2c_init, the bus number used may be used with the k_i2c_read/k_i2c_write/k_i2c_terminate functions.

Example usage:

KI2CConf conf = {
    .addressing_mode = K_ADDRESSING_MODE_7BIT,
    .role = K_MASTER,
    .clock_speed = 100000
};
k_i2c_init(K_I2C1, &conf);

Note
The functions k_i2c_default_init or k_i2c_default_dev_init can also be used to initialize an I2C device. They provide nice convience wrappers around k_i2c_init.
Return
KI2CStatus I2C_OK on success, otherwise return I2C_ERROR_*
Parameters
  • i2c: I2C bus to initialize
  • conf: config values to initialize with

void k_i2c_terminate(KI2CNum i2c)

Terminates an I2C bus.

This fuction is used to terminate an active I2C bus. It takes the bus number of an active I2C bus. After calling this function the bus number used will not be available for usage in the reading/writing functions.

Example usage:

// initialize bus
k_i2c_init(K_I2C1, &conf);
// read some data
k_i2c_read(K_I2C1, addr, buffer, 10);
// shut down bus
k_i2C_terminate(K_I2C1);
Parameters
  • i2c: I2C bus to terminate

KI2CConf k_i2c_conf_defaults(void)

Generate KI2CConf with default I2C values.

This function returns a KI2CConf structure with the default I2C values already set. These default values are derived from the target.json file of the selected hardware target. New default values can easily be set by creating a config.json file in the project directory.

Example contents of config.json overriding defaults:

"hardware": {
  "i2c": {
    "defaults": {
      "addressingmode": "K_ADDRESSING_MODE_7BIT",
      "role": "K_MASTER",
      "clockspeed": 50000
    }
  }
}
Return
KI2CConf

void k_i2c_default_init()

Initialize default I2C configuration.

This function initializes the default I2C bus using the preset default I2C configuration. The default I2C bus and configuration are set in the target.json file and can be overriden in a project’s config.json.

Calling this function is equivalent to the following code:

KI2CConf default_conf = k_i2c_conf_defaults();
k_i2c_init(DEFAULT_I2C, &default_conf);
The DEFAULT_I2C define is derived from the json default values.

Example contents of config.json overriding defaults:

"hardware": {
  "i2c": {
    "defaults": {
      "addressingmode": "K_ADDRESSING_MODE_7BIT",
      "role": "K_MASTER",
      "clockspeed": 50000
      "bus": "K_I2C1"
    }
  }
}

void k_i2c_default_dev_init(KI2CNum i2c)

Initialize specified I2C bus with default values.

This function initializes a specified I2C bus with the preset default I2C configuration. The default I2C configuration is derived from the target.json file and can be overriden in a project’s config.json.

Calling this function is equivalent to the following code (K_I2C3 could be any I2C bus number):

KI2CConf default_conf = k_i2c_conf_defaults();
k_i2c_init(K_I2C3, &default_conf);

Parameters
  • i2c: I2C bus num to initialize

KI2CStatus k_i2c_write(KI2CNum 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:

uint8_t cmd = 0x40;
uint16_t slave_addr = 0x80;
KI2CStatus write_status;
write_status = k_i2c_write(K_I2C1, 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.

Return
KI2CStatus I2C_OK on success, I2C_ERROR on error
Parameters
  • i2c: I2C bus to transmit over
  • addr: address of target I2C device
  • ptr: pointer to data buffer
  • len: length of data in buffer

KI2CStatus k_i2c_read(KI2CNum 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:

uint8_t buffer[10];
int read_len = 10;
uint16_t slave_addr = 0x80;
KI2CStatus read_status;
read_status = k_i2c_read(K_I2C1, 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.

Return
KI2CStatus I2C_OK on success, I2C_ERROR on error
Parameters
  • i2c: I2C bus to read from
  • addr: address of target I2C device
  • ptr: pointer to data buffer
  • len: length of data to read

KI2C *kprv_i2c_get(KI2CNum i2c)

Fetches I2C bus data structure.

Return
KI2C* pointer to data structure
Parameters
  • i2c: number of I2C bus to fetch

KI2CStatus kprv_i2c_dev_init(KI2CNum i2c)

Low-level HAL device initialization This is implemented by the device specific HAL.

Return
KI2CStatus I2C_OK if success, otherwise specific error
Parameters
  • i2c: I2C bus to initialize

KI2CStatus kprv_i2c_dev_terminate(KI2CNum i2c)

Low-level HAL I2C termination This is implemented by the device specific HAL.

Return
KI2CStatus I2C_OK if success, otherwise specific error
Parameters
  • i2c: I2C bus to terminate

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

Low-level HAL I2C write (as master)

This function is called by k_i2c_write and is intended to perform the neccesary low-level actions for an I2C write (as a master).

** This function must be implemented for each platform specific HAL. **

Return
KI2CStatus I2C_OK on success, I2C_ERROR on error
Parameters
  • i2c: I2C bus to write from
  • addr: I2C addr to write to
  • ptr: data buffer
  • len: length of data in buffer

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

Low-level HAL I2C read (as master)

This function is called by k_i2c_read and is intended to perform the neccesary low-level actions for an I2C read (as a master).

** This function must be implemented for each platform specific HAL. **

Return
KI2CStatus I2C_OK on success, I2C_ERROR on error
Parameters
  • i2c: I2C bus to read from
  • addr: I2C addr to read from
  • ptr: data buffer
  • len: length of data expected to read

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

Low-level HAL I2C write (as slave)

This function will be called by k_i2c_write and is intended to perform the neccesary low-level actions for an I2C write (as a slave).

** This function must be implemented for each platform specific HAL. **

Warning
I2C slave functionality is not implemented as of v0.0.4
Return
KI2CStatus I2C_OK on success, I2C_ERROR on error
Parameters
  • i2c: I2C bus to write from
  • addr: I2C addr to write to
  • ptr: data buffer
  • len: length of data in buffer

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

Low-level HAL I2C read (as slave)

This function will be called by k_i2c_read and is intended to perform the neccesary low-level actions for an I2C read (as a slave).

** This function must be implemented for each platform specific HAL. **

Warning
I2C slave functionality is not implemented as of v0.0.4
Return
KI2CStatus I2C_OK on success, I2C_ERROR on error
Parameters
  • i2c: I2C bus to read from
  • addr: I2C addr to read from
  • ptr: data buffer
  • len: length of data expected to read

struct KI2CConf
#include <i2c.h>

Structure used to store I2C bus configuration options.

Public Members

I2CAddressingMode addressing_mode

The size of the slave address.

Should be either 7-bits long or 10-bits long, as specified by the I2CAddressingMode enumerator

I2CRole role

The role of the I2C bus.

Should be either master or slave, as specified by the I2CRole enumerator

Warning
Only the Master role is available as of v0.1.0

uint32_t clock_speed

The clock speed of the I2C bus.

struct KI2C
#include <i2c.h>

Structure used to store I2C bus description/configuration information.

Public Members

KI2CNum bus_num

I2C device number.

KI2CConf conf

I2C device configuration values.

csp_mutex_t i2c_lock

Mutex for guarding device access.