I2C Master HAL

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

Functions list
void	hal_i2c_master_configure_default (hal_i2c_master_config_t *config)
	Configure I2C Master HAL configuration structure. More...
err_t	hal_i2c_master_open (handle_t *handle, bool hal_obj_open_state)
	Open the I2C Master HAL object. 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...
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...

Detailed Description

API for configuring and manipulating I2C Master HAL module.

Function Documentation

hal_i2c_master_configure_default()

void hal_i2c_master_configure_default

(

hal_i2c_master_config_t *

config

)

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 configuration 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
	)

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 = PB3;
 
 // Specify desired SDA pin
hal_i2c_master_cfg.sda = PB4;
 
// Allocate resources for I2C module.
if ( hal_i2c_master_open( &hal_i2c_master->handle, true ) == 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
	)

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 baud 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
	)

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_set_slave_address()

void hal_i2c_master_set_slave_address	(	handle_t *	handle,
		hal_i2c_master_config_t *	config
	)

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_write()

err_t hal_i2c_master_write	(	handle_t	handle,
		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]	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_read()

err_t hal_i2c_master_read	(	handle_t	handle,
		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]	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_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
	)

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
}

hal_i2c_master_close()

err_t hal_i2c_master_close

(

handle_t *

handle

)

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 module object handler
hal_i2c_master_close( &hal_i2c_master->handle );