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
I2CAddressingMode
¶ Expected addressing mode of I2C bus.
Values:
-
K_ADDRESSINGMODE_7BIT
= 0¶
-
K_ADDRESSINGMODE_10BIT
¶
-
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 initializeconf
: 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:
The DEFAULT_I2C define is derived from the json default values.KI2CConf default_conf = k_i2c_conf_defaults(); k_i2c_init(DEFAULT_I2C, &default_conf);
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 overaddr
: address of target I2C deviceptr
: pointer to data bufferlen
: 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 fromaddr
: address of target I2C deviceptr
: pointer to data bufferlen
: 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 fromaddr
: I2C addr to write toptr
: data bufferlen
: 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 fromaddr
: I2C addr to read fromptr
: data bufferlen
: 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 fromaddr
: I2C addr to write toptr
: data bufferlen
: 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 fromaddr
: I2C addr to read fromptr
: data bufferlen
: 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.
-
I2CAddressingMode
-
struct
KI2C
¶ - #include <i2c.h>
Structure used to store I2C bus description/configuration information.