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.