I2C Master Driver

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...
err_t	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]

config

I2C 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]	obj	I2C Master driver object. See i2c_master_t structure definition for detailed explanation.
[in]	config	I2C 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]	obj	I2C Master driver object. See i2c_master_t structure definition for detailed explanation.
[in]	speed	Specified 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.
if ( i2c_master_set_speed( &i2c_master, I2C_MASTER_SPEED_STANDARD ) == I2C_MASTER_ERROR )
{
 // 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]	obj	I2C Master driver object. See i2c_master_t structure definition for detailed explanation.
[in]	timeout_pass_count	Specified 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]	obj	I2C Master driver object. See i2c_master_t structure definition for detailed explanation.
[in]	address	Specified 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]	obj	I2C master driver object. See i2c_master_t structure definition for detailed explanation.
[in]	*write_data_buf	Data transmit buffer.
[in]	len_write_data	Number 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]	obj	I2C master driver object. See i2c_master_t structure definition for detailed explanation.
[out]	*read_data_buf	Data receive buffer.
[in]	len_read_data	Number 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]	obj	I2C master driver object. See i2c_master_t structure definition for detailed explanation.
[in]	*write_data_buf	Data transmit buffer.
[in]	len_write_data	Number of bytes to write from data transmit buffer.
[out]	*read_data_buf	Data receive buffer.
[in]	len_read_data	Number 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()

err_t 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]

obj

I2C Master driver object. See i2c_master_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.

Example

// I2C driver context structure.
static i2c_master_t i2c_master;
 
// Close the I2C Master module object handler.
if ( I2C_MASTER_SUCCESS == i2c_master_close( &i2c_master ) ) {
 // No error
} else {
 // Handle the error
}