mikroSDK Reference Manual

I2C Master Driver API Reference. More...

Functions list

void i2c_master_configure_default (i2c_master_config_t *config)
 Configure I2C Master configuration structure. More...
 
err_t i2c_master_open (i2c_master_t *obj, i2c_master_config_t *config)
 Open the I2C Master driver object. More...
 
err_t i2c_master_set_speed (i2c_master_t *obj, uint32_t speed)
 Set I2C Master module speed. More...
 
err_t i2c_master_set_timeout (i2c_master_t *obj, uint16_t timeout_pass_count)
 Set I2C Master timeout value. More...
 
err_t i2c_master_set_slave_address (i2c_master_t *obj, uint8_t address)
 Set I2C Slave address. More...
 
err_t i2c_master_write (i2c_master_t *obj, uint8_t *write_data_buf, size_t len_write_data)
 Write data to the I2C bus. More...
 
err_t i2c_master_read (i2c_master_t *obj, uint8_t *read_data_buf, size_t len_read_data)
 Read data from the I2C bus. More...
 
err_t i2c_master_write_then_read (i2c_master_t *obj, uint8_t *write_data_buf, size_t len_write_data, uint8_t *read_data_buf, size_t len_read_data)
 Write data to I2C bus followed by read. More...
 
void i2c_master_close (i2c_master_t *obj)
 Close I2C Master driver object. More...
 

Detailed Description

The I2C Master driver provides standard I2C Master functionality including setting the I2C speed and timeout.

Function Documentation

◆ i2c_master_configure_default()

void i2c_master_configure_default ( i2c_master_config_t config)

Configures I2C Master structure to default initialization values. Take into consideration that this is just structure variable initial values setting. Values need to be redefined by user.

Parameters
[in,out]configI2C Master driver configuration structure. See i2c_master_config_t structure definition for detailed explanation.

Default values:

Function Default value
Address 0
SCL pin 0xFFFFFFFF (invalid pin)
SDA pin 0xFFFFFFFF (invalid pin)
Speed 100K
Timeout value 10000 retries
Returns
Nothing.

Example

// I2C Master driver config structure.
i2c_master_config_t i2c_master_cfg;
// Fill structure with default values.
i2c_master_configure_default( &i2c_master_cfg );

◆ i2c_master_open()

err_t i2c_master_open ( i2c_master_t obj,
i2c_master_config_t config 
)

Opens the I2C Master driver object on selected pins. Allocates memory and pins for specified object.

Parameters
[in,out]objI2C Master driver object. See i2c_master_t structure definition for detailed explanation.
[in]configI2C Master driver configuration settings. See i2c_master_config_t structure definition for detailed explanation.
Returns
The function can return one of the values defined by i2c_master_err_t, which is size dependant on the architecture.
Precondition
Make sure that config structure has been adequately populated beforehand. See i2c_master_configure_default definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
// Specify desired SCL pin.
i2c_master_cfg.scl = MIKROBUS_1_SCL;
// Specify desired SDA pin.
i2c_master_cfg.sda = MIKROBUS_1_SDA;
// Allocate resources for I2C module.
if ( i2c_master_open( &i2c_master, &i2c_master_cfg ) == I2C_MASTER_ERROR )
{
// Error handling strategy
}

◆ i2c_master_set_speed()

err_t i2c_master_set_speed ( i2c_master_t obj,
uint32_t  speed 
)

Sets I2C Master module speed to speed value if possible.

Parameters
[in]objI2C Master driver object. See i2c_master_t structure definition for detailed explanation.
[in]speedSpecified I2C transmission rate. See i2c_master_speed_t for valid values.
Returns
The function can return one of the values defined by i2c_master_err_t, which is size dependant on the architecture.
Precondition
Make sure that adequate memory has been allocated beforehand. See i2c_master_open definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
// Set transmission rate.
{
// Error handling strategy
}

◆ i2c_master_set_timeout()

err_t i2c_master_set_timeout ( i2c_master_t obj,
uint16_t  timeout_pass_count 
)

Sets I2C Master module timeout interval to timeout_pass_count value. This means that the module shall retry any given operation timeout_pass_count number of times before exiting with adequate timeout value.

Parameters
[in]objI2C Master driver object. See i2c_master_t structure definition for detailed explanation.
[in]timeout_pass_countSpecified I2C master timeout value.
Returns
The function can return one of the values defined by i2c_master_err_t, which is size dependant on the architecture.
Precondition
Make sure that adequate memory has been allocated beforehand. See i2c_master_open definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
// Set timeout value.
if ( i2c_master_set_timeout( &i2c_master, 1000 ) == I2C_MASTER_ERROR )
{
// Error handling strategy
}

◆ i2c_master_set_slave_address()

err_t i2c_master_set_slave_address ( i2c_master_t obj,
uint8_t  address 
)

Sets I2C address of the subordinate I2C device to address which is targeted by read and write operations.

Parameters
[in]objI2C Master driver object. See i2c_master_t structure definition for detailed explanation.
[in]addressSpecified I2C slave address.
Returns
The function can return one of the values defined by i2c_master_err_t, which is size dependant on the architecture.
Precondition
Make sure that adequate memory has been allocated beforehand. See i2c_master_open definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
// Set slave address.
if ( i2c_master_set_slave_address( &i2c_master, 0x50 ) == I2C_MASTER_ERROR )
{
// Error handling strategy
}

◆ i2c_master_write()

err_t i2c_master_write ( i2c_master_t obj,
uint8_t *  write_data_buf,
size_t  len_write_data 
)

Function shall generate a START signal, followed by len_write_data number of writes from write_data_buf on the bus. Ends with a STOP signal.

Parameters
[in]objI2C master driver object. See i2c_master_t structure definition for detailed explanation.
[in]*write_data_bufData transmit buffer.
[in]len_write_dataNumber of bytes to write from data transmit buffer.
Returns
The function can return one of the values defined by i2c_master_err_t, which is size dependant on the architecture.
Precondition
Make sure that adequate memory has been allocated beforehand, and the module has been initialized to adequate I2C transmission rate. See i2c_master_open definition and i2c_master_set_speed for detailed explanation.
Note
It is recommended to check return value for error.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
// I2C data buffer.
uint8_t *write_buff;
if ( i2c_master_write( &i2c_master, &write_buff, sizeof( write_buff ) ) == I2C_MASTER_ERROR )
{
// Error handling strategy
}

◆ i2c_master_read()

err_t i2c_master_read ( i2c_master_t obj,
uint8_t *  read_data_buf,
size_t  len_read_data 
)

Function shall generate a START signal, followed by len_read_data number of reads from the bus placing the data in read_data_buf . Ends with a STOP signal.

Parameters
[in]objI2C master driver object. See i2c_master_t structure definition for detailed explanation.
[out]*read_data_bufData receive buffer.
[in]len_read_dataNumber of bytes to read from bus.
Returns
The function can return one of the values defined by i2c_master_err_t, which is size dependant on the architecture.
Precondition
Make sure that adequate memory has been allocated beforehand, and the module has been initialized to adequate I2C transmission rate. See i2c_master_open definition and i2c_master_set_speed for detailed explanation.
Note
It is recommended to check return value for error.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
// I2C data buffer.
uint8_t *read_buff;
if ( i2c_master_read( &i2c_master, &read_buff, sizeof( read_buff ) ) == I2C_MASTER_ERROR )
{
// Error handling strategy
}

◆ i2c_master_write_then_read()

err_t i2c_master_write_then_read ( i2c_master_t obj,
uint8_t *  write_data_buf,
size_t  len_write_data,
uint8_t *  read_data_buf,
size_t  len_read_data 
)

Function performs a write operation followed by a read operation on the bus. The operation consists of a start signal followed by len_write_data number of write operations ( data from write_data_buf ), a restart signal followed by len_read_data number of read operations ( placed in read_data_buf ), finishing the operation with a stop signal.

Parameters
[in]objI2C master driver object. See i2c_master_t structure definition for detailed explanation.
[in]*write_data_bufData transmit buffer.
[in]len_write_dataNumber of bytes to write from data transmit buffer.
[out]*read_data_bufData receive buffer.
[in]len_read_dataNumber of bytes to read from bus.
Returns
The function can return one of the values defined by i2c_master_err_t, which is size dependant on the architecture.
Precondition
Make sure that adequate memory has been allocated beforehand, and the module has been initialized to adequate I2C transmission rate. See i2c_master_open definition and i2c_master_set_speed for detailed explanation.
Note
It is recommended to check return value for error.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
// I2C data buffers.
uint8_t *write_buff;
uint8_t *read_buff;
if ( i2c_master_write_then_read( &i2c_master, &write_buff, sizeof( write_buff ), &read_buff, sizeof( read_buff ) ) == I2C_MASTER_ERROR )
{
// Error handling strategy
}

◆ i2c_master_close()

void i2c_master_close ( i2c_master_t obj)

De-allocates hardware resources for specific driver object and de-initializes the module on a hardware level, resets pin AF to default values, clears all buffers used by object and disables module clock for lower power consumption.

Parameters
[in,out]objI2C Master driver object. See i2c_master_t structure definition for detailed explanation.
Returns
Nothing.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
// Close the I2C Master module object handler.
i2c_master_close( &i2c_master );
i2c_master_t
I2C Master driver context structure, consisted of the following fields :
Definition: drv_i2c_master.h:119
i2c_master_write_then_read
err_t i2c_master_write_then_read(i2c_master_t *obj, uint8_t *write_data_buf, size_t len_write_data, uint8_t *read_data_buf, size_t len_read_data)
Write data to I2C bus followed by read.
i2c_master_set_slave_address
err_t i2c_master_set_slave_address(i2c_master_t *obj, uint8_t address)
Set I2C Slave address.
i2c_master_write
err_t i2c_master_write(i2c_master_t *obj, uint8_t *write_data_buf, size_t len_write_data)
Write data to the I2C bus.
i2c_master_config_t::scl
pin_name_t scl
Definition: drv_i2c_master.h:100
i2c_master_read
err_t i2c_master_read(i2c_master_t *obj, uint8_t *read_data_buf, size_t len_read_data)
Read data from the I2C bus.
i2c_master_config_t::sda
pin_name_t sda
Definition: drv_i2c_master.h:99
I2C_MASTER_ERROR
Definition: drv_i2c_master.h:59
i2c_master_open
err_t i2c_master_open(i2c_master_t *obj, i2c_master_config_t *config)
Open the I2C Master driver object.
i2c_master_set_speed
err_t i2c_master_set_speed(i2c_master_t *obj, uint32_t speed)
Set I2C Master module speed.
i2c_master_configure_default
void i2c_master_configure_default(i2c_master_config_t *config)
Configure I2C Master configuration structure.
i2c_master_set_timeout
err_t i2c_master_set_timeout(i2c_master_t *obj, uint16_t timeout_pass_count)
Set I2C Master timeout value.
I2C_MASTER_SPEED_STANDARD
Definition: drv_i2c_master.h:67
i2c_master_config_t
I2C Master initialization configuration structure, consisted of the following fields :
Definition: drv_i2c_master.h:95
i2c_master_close
void i2c_master_close(i2c_master_t *obj)
Close I2C Master driver object.