I2C Master HAL

I2C Master Hardware Abstraction Layer API Reference. More...

Collaboration diagram for I2C Master HAL:

Functions
err_t	hal_i2c_master_open (handle_t *handle, bool hal_obj_open_state)
	Open the I2C Master HAL object. More...
void	hal_i2c_master_set_slave_address (handle_t *handle, hal_i2c_master_config_t *config)
	Set I2C slave address. More...
err_t	hal_i2c_master_write (handle_t handle, uint8_t *write_data_buf, size_t len_write_data)
	Write data to the I2C bus. More...
err_t	hal_i2c_master_read (handle_t handle, uint8_t *read_data_buf, size_t len_read_data)
	Read data from the I2C bus. More...
err_t	hal_i2c_master_write_then_read (handle_t handle, uint8_t *write_data_buf, size_t len_write_data, uint8_t *read_data_buf, size_t len_read_data)
	Write data followed by read. More...
err_t	hal_i2c_master_close (handle_t *handle)
	Closes I2C Master HAL object. More...
void	hal_i2c_master_configure_default (hal_i2c_master_config_t *config)
	Configure I2C Master HAL configuration structure. More...
err_t	hal_i2c_master_set_speed (handle_t *handle, hal_i2c_master_config_t *config)
	Set I2C master module speed. More...
void	hal_i2c_master_set_timeout (handle_t *handle, hal_i2c_master_config_t *config)
	Set I2C master timeout value. More...

Detailed Description

I2C Master Hardware Abstraction Layer API Reference.

API for configuring and manipulating I2C Master HAL module.

Function Documentation

hal_i2c_master_close()

err_t hal_i2c_master_close

(

handle_t *

handle

)

Closes I2C Master HAL object.

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]

handle

I2C handle. See hal_i2c_master_t structure definition for detailed explanation.

Returns

Nothing.

Example

// Close the I2C Master HAL module object handler.
hal_i2c_master_close( &hal_i2c_master->handle );

hal_i2c_master_configure_default()

void hal_i2c_master_configure_default

(

hal_i2c_master_config_t *

config

)

Configure I2C Master HAL configuration structure.

Configures configuration 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 HAL driver configuration structure. See hal_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 HAL config structure.
static hal_i2c_master_config_t hal_i2c_master_cfg;
 
// Fill structure with default values.
hal_i2c_master_configure_default( &hal_i2c_master_cfg );

hal_i2c_master_open()

err_t hal_i2c_master_open	(	handle_t *	handle,
		bool	hal_obj_open_state
	)

Open the I2C Master HAL object.

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

Parameters

[in,out]	handle	I2C Master HAL object. See hal_i2c_master_t structure definition for detailed explanation.
[in]	hal_obj_open_state	I2C state. Is it open or not.

Returns

The function can return one of the values defined by hal_i2c_master_err_t, which is size dependant on the architecture.

Note

It is recommended to check return value for error.

Example

// I2C HAL context structure.
static hal_i2c_master_t hal_i2c_master;
 
// Specify desired SCL pin.
hal_i2c_master_cfg.scl = MIKROBUS_1_SCL;
 
// Specify desired SDA pin.
hal_i2c_master_cfg.sda = MIKROBUS_1_SDA;
 
// Allocate resources for I2C module.
if ( hal_i2c_master_open( &hal_i2c_master->handle, true ) == HAL_I2C_MASTER_ERROR )
{
    // Error handling strategy
}

Calling sensorif to initalise and enable I2C

hal_i2c_master_read()

err_t hal_i2c_master_read	(	handle_t	handle,
		uint8_t *	read_data_buf,
		size_t	len_read_data
	)

Read data from the I2C bus.

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]	handle	I2C handle. See i2c_master_t structure definition for detailed explanation.
[out]	*read_data_buf	Data buffer.
[in]	len_read_data	Number of bytes to read from bus.

Returns

The function can return one of the values defined by hal_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 hal_i2c_master_open definition and hal_i2c_master_set_speed for detailed explanation.

Note

It is recommended to check return value for error.

Example

// Set timeout value.
if ( hal_i2c_master_read( &hal_i2c_master, &read_buff, sizeof( read_buff ) ) == HAL_I2C_MASTER_ERROR )
{
    // Error handling strategy
}

hal_i2c_master_set_slave_address()

void hal_i2c_master_set_slave_address	(	handle_t *	handle,
		hal_i2c_master_config_t *	config
	)

Set I2C slave address.

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

Parameters

[in]	handle	I2C handle. See i2c_master_t structure definition for detailed explanation.
[in]	config	I2C HAL configuration structure. See hal_i2c_master_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_i2c_master_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_i2c_master_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// Set slave address.
if ( hal_i2c_master_set_slave_address( &hal_i2c_master, 0x50 ) == HAL_I2C_MASTER_ERROR )
{
    // Error handling strategy
}

hal_i2c_master_set_speed()

err_t hal_i2c_master_set_speed	(	handle_t *	handle,
		hal_i2c_master_config_t *	config
	)

Set I2C master module speed.

Sets I2C module speed to config->speed value if possible.

Parameters

[in]	handle	I2C handle. See i2c_master_t structure definition for detailed explanation.
[in]	config	I2C HAL configuration structure. See hal_i2c_master_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_i2c_master_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_i2c_master_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// Set transmission rate.
if ( hal_i2c_master_set_speed( &hal_i2c_master->handle, HAL_I2C_MASTER_SPEED_STANDARD ) == HAL_I2C_MASTER_ERROR )
{
    // Error handling strategy
}

hal_i2c_master_set_timeout()

void hal_i2c_master_set_timeout	(	handle_t *	handle,
		hal_i2c_master_config_t *	config
	)

Set I2C master timeout value.

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

Parameters

[in]	handle	I2C handle. See i2c_master_t structure definition for detailed explanation.
[in]	config	I2C HAL configuration structure. See hal_i2c_master_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_i2c_master_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_i2c_master_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// Set timeout value.
if ( hal_i2c_master_set_timeout( &hal_i2c_master->handle, 1000 ) == HAL_I2C_MASTER_ERROR )
{
    // Error handling strategy
}

hal_i2c_master_write()

err_t hal_i2c_master_write	(	handle_t	handle,
		uint8_t *	write_data_buf,
		size_t	len_write_data
	)

Write data to the I2C bus.

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]	handle	I2C handle. See i2c_master_t structure definition for detailed explanation.
[in]	*write_data_buf	Data buffer.
[in]	len_write_data	Number of bytes to write from data buffer.

Returns

The function can return one of the values defined by hal_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 hal_i2c_master_open definition and hal_i2c_master_set_speed for detailed explanation.

Note

It is recommended to check return value for error.

Example

// Set timeout value.
if ( hal_i2c_master_write( &hal_i2c_master->handle, &write_buff, sizeof( write_buff ) ) == HAL_I2C_MASTER_ERROR )
{
    // Error handling strategy
}

hal_i2c_master_write_then_read()

err_t hal_i2c_master_write_then_read	(	handle_t	handle,
		uint8_t *	write_data_buf,
		size_t	len_write_data,
		uint8_t *	read_data_buf,
		size_t	len_read_data
	)

Write data followed by read.

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]	handle	I2C handle. See i2c_master_t structure definition for detailed explanation.
[in]	*write_data_buf	Data buffer.
[in]	len_write_data	Number of bytes to write from data buffer.
[out]	*read_data_buf	Data buffer.
[in]	len_read_data	Number of bytes to read from bus.

Returns

The function can return one of the values defined by hal_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 hal_i2c_master_open definition and hal_i2c_master_set_speed for detailed explanation.

Note

It is recommended to check return value for error.

Example

// Set timeout value.
if ( hal_i2c_master_write_then_read( &hal_i2c_master->handle,  &write_buff, sizeof( write_buff ), &read_buff, sizeof( read_buff ) ) == HAL_I2C_MASTER_ERROR )
{
    // Error handling strategy
}