twi.c File Reference

provide the TWI interface More...

#include "core_debug.h"
#include "utility/twi.h"
#include "PinAF_STM32F1.h"
#include "stm32yyxx_ll_gpio.h"
#include "stm32yyxx_ll_i2c.h"

Classes
struct	I2C_timing_t
	Timing value computed for a given I2C input clock, cached to avoid computing it again. More...
struct	I2C_Charac_t
	I2C bus characteristics of a speed mode (frequency range and timings from the I2C specification, UM10204). More...

Macros
#define	I2C_TIMEOUT_TICK   100
	I2C timeout in tick unit.
#define	SLAVE_MODE_TRANSMIT   0
	Slave mode: the slave is sending data to the master.
#define	SLAVE_MODE_RECEIVE   1
	Slave mode: the slave is receiving data from the master.
#define	SLAVE_MODE_LISTEN   2
	Slave mode: the slave is listening for its address.
#define	I2C_TIMING
#define	I2C_TIMING_COMPUTE
#define	I2C_VALID_TIMING_NBR   8U
#define	I2C_ANALOG_FILTER_DELAY_MIN   50U /* ns */
#define	I2C_ANALOG_FILTER_DELAY_MAX   260U /* ns */
#define	I2C_USE_ANALOG_FILTER   1U
#define	I2C_DIGITAL_FILTER_COEF   0U
#define	I2C_PRESC_MAX   16U
#define	I2C_SCLDEL_MAX   16U
#define	I2C_SDADEL_MAX   16U
#define	I2C_SCLH_MAX   256U
#define	I2C_SCLL_MAX   256U
#define	SEC2NSEC   1000000000UL

Enumerations
enum	I2C_speed_freq_t { I2C_SPEED_FREQ_STANDARD , I2C_SPEED_FREQ_FAST , I2C_SPEED_FREQ_FAST_PLUS , I2C_SPEED_FREQ_NUMBER }
	I2C speed modes, used as index of I2C_ClockTiming and I2C_Charac.
enum	i2c_index_t { I2C_NUM }
	Index of each I2C instance available on the family, used to index i2c_handles. More...

Functions
static uint32_t	i2c_getClkFreq (I2C_TypeDef *i2c)
	This function return the I2C clock source frequency.
static uint32_t	i2c_computeTiming (uint32_t clkSrcFreq, uint32_t i2c_speed)
	Calculate PRESC, SCLDEL, SDADEL, SCLL and SCLH and find best configuration.
static uint32_t	i2c_getTiming (i2c_t *obj, uint32_t frequency)
	Compute I2C timing according current I2C clock source and required I2C clock.
void	i2c_init (i2c_t *obj, uint32_t timing, uint32_t ownAddress)
	Initialize and set up the GPIO pins and the I2C peripheral.
void	i2c_deinit (i2c_t *obj)
	Deinitialize the GPIO pins and the I2C peripheral.
void	i2c_setTiming (i2c_t *obj, uint32_t frequency)
	Set the transmission speed.
i2c_status_e	i2c_master_write (i2c_t *obj, uint8_t dev_address, uint8_t *data, uint16_t size)
	Write bytes to a device at a given address.
i2c_status_e	i2c_slave_write_IT (i2c_t *obj, uint8_t *data, uint16_t size)
	Buffer bytes to send to the master in slave transmit mode.
i2c_status_e	i2c_master_read (i2c_t *obj, uint8_t dev_address, uint8_t *data, uint16_t size)
	Read bytes from a device at a given address in master mode.
i2c_status_e	i2c_IsDeviceReady (i2c_t *obj, uint8_t devAddr, uint32_t trials)
	Check whether the target device is ready for communication.
i2c_t *	get_i2c_obj (I2C_HandleTypeDef *hi2c)
	Get the i2c_t object that embeds a given HAL I2C handle.
void	i2c_attachSlaveRxEvent (i2c_t *obj, void(*function)(i2c_t *))
	Set the function called when the slave receives data from a master.
void	i2c_attachSlaveTxEvent (i2c_t *obj, void(*function)(i2c_t *))
	Set the function called when a master requests data from the slave.
void	HAL_I2C_AddrCallback (I2C_HandleTypeDef *hi2c, uint8_t TransferDirection, uint16_t AddrMatchCode)
	Slave Address Match callback.
void	HAL_I2C_ListenCpltCallback (I2C_HandleTypeDef *hi2c)
	Listen Complete callback.
void	HAL_I2C_SlaveRxCpltCallback (I2C_HandleTypeDef *hi2c)
	Slave RX complete callback.
void	HAL_I2C_SlaveTxCpltCallback (I2C_HandleTypeDef *hi2c)
	Slave TX complete callback.
void	HAL_I2C_ErrorCallback (I2C_HandleTypeDef *hi2c)
	I2C error callback.

Variables
static I2C_timing_t	I2C_ClockTiming [I2C_SPEED_FREQ_NUMBER] = {0}
	Cache of the computed timing for each speed mode (see I2C_speed_freq_t).
static const I2C_Charac_t	I2C_Charac []
	I2C characteristics of each speed mode, indexed by I2C_speed_freq_t.
static I2C_HandleTypeDef *	i2c_handles [I2C_NUM]
	HAL handle of each initialized I2C instance, indexed by i2c_index_t.

Detailed Description

provide the TWI interface

Author

WI6LABS

Version

V1.0.0

Date

01-August-2016

Attention

© COPYRIGHT(c) 2016 STMicroelectronics

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of STMicroelectronics nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Enumeration Type Documentation

i2c_index_t

enum i2c_index_t

Index of each I2C instance available on the family, used to index i2c_handles.

I2C_NUM is the number of instances.

Function Documentation

get_i2c_obj()

i2c_t * get_i2c_obj

(

I2C_HandleTypeDef *

hi2c

)

Get the i2c_t object that embeds a given HAL I2C handle.

Parameters

hi2c	Pointer to the handle member of an i2c_t object (I2C_HandleTypeDef, or hal_i2c_handle_t with USE_HALV2_DRIVER).

Returns

Pointer to the i2c_t object that contains hi2c.

Note

The object is recovered by pointer arithmetic (container_of style). hi2c must point to the handle member of a valid i2c_t, otherwise the result is undefined.

HAL_I2C_AddrCallback()

void HAL_I2C_AddrCallback	(	I2C_HandleTypeDef *	hi2c,
		uint8_t	TransferDirection,
		uint16_t	AddrMatchCode
	)

Slave Address Match callback.

Parameters

hi2c	Pointer to a I2C_HandleTypeDef or hal_i2c_handle_t structure that contains the configuration information for the specified I2C.
TransferDirection	Master request Transfer Direction (Write/Read), value of I2C_XferOptions_definition
AddrMatchCode	Address Match Code

HAL_I2C_ErrorCallback()

void HAL_I2C_ErrorCallback

(

I2C_HandleTypeDef *

hi2c

)

I2C error callback.

Note

In master mode, the callback is not used because the error is reported to the Arduino API from i2c_master_write() and i2c_master_read(). In slave mode, there is no mechanism in Arduino API to report an error so the error callback forces the slave to listen again.

Parameters

hi2c	Pointer to a I2C_HandleTypeDef structure that contains the configuration information for the specified I2C.

HAL_I2C_ListenCpltCallback()

void HAL_I2C_ListenCpltCallback

(

I2C_HandleTypeDef *

hi2c

)

Listen Complete callback.

Parameters

hi2c	Pointer to a I2C_HandleTypeDef or hal_i2c_handle_t structure that contains the configuration information for the specified I2C.

HAL_I2C_SlaveRxCpltCallback()

void HAL_I2C_SlaveRxCpltCallback

(

I2C_HandleTypeDef *

hi2c

)

Slave RX complete callback.

Parameters

hi2c	Pointer to a I2C_HandleTypeDef structure that contains the configuration information for the specified I2C.

HAL_I2C_SlaveTxCpltCallback()

void HAL_I2C_SlaveTxCpltCallback

(

I2C_HandleTypeDef *

hi2c

)

Slave TX complete callback.

Parameters

hi2c	Pointer to a I2C_HandleTypeDef structure that contains the configuration information for the specified I2C.

i2c_attachSlaveRxEvent()

void i2c_attachSlaveRxEvent	(	i2c_t *	obj,
		void(*)(i2c_t *)	function
	)

Set the function called when the slave receives data from a master.

Parameters

obj	Pointer to the i2c_t structure.
function	Callback function to use, called with the i2c_t structure.

i2c_attachSlaveTxEvent()

void i2c_attachSlaveTxEvent	(	i2c_t *	obj,
		void(*)(i2c_t *)	function
	)

Set the function called when a master requests data from the slave.

Parameters

obj	Pointer to the i2c_t structure.
function	Callback function to use, called with the i2c_t structure.

i2c_computeTiming()

static uint32_t i2c_computeTiming ( uint32_t  clkSrcFreq, uint32_t  i2c_speed  )

static

Calculate PRESC, SCLDEL, SDADEL, SCLL and SCLH and find best configuration.

Parameters

clkSrcFreq	I2C source clock in HZ.
i2c_speed	I2C frequency (index).

Returns

config index (0 to I2C_VALID_TIMING_NBR], 0xFFFFFFFF for no valid config.

i2c_deinit()

void i2c_deinit

(

i2c_t *

obj

)

Deinitialize the GPIO pins and the I2C peripheral.

Parameters

obj	Pointer to the i2c_t structure.

i2c_getClkFreq()

static uint32_t i2c_getClkFreq ( I2C_TypeDef *  i2c )

static

This function return the I2C clock source frequency.

Parameters

i2c	I2C instance

Returns

frequency in Hz

i2c_getTiming()

static uint32_t i2c_getTiming ( i2c_t *  obj, uint32_t  frequency  )

static

Compute I2C timing according current I2C clock source and required I2C clock.

Parameters

obj	Pointer to i2c_t structure
frequency	Required I2C clock in Hz.

Returns

I2C timing or 0 in case of error.

i2c_init()

void i2c_init	(	i2c_t *	obj,
		uint32_t	timing,
		uint32_t	ownAddress
	)

Initialize and set up the GPIO pins and the I2C peripheral.

Parameters

obj	Pointer to the i2c_t structure.
timing	I2C clock frequency in Hz.
ownAddress	Own address already shifted left by 1 (7-bit address << 1).

i2c_IsDeviceReady()

i2c_status_e i2c_IsDeviceReady	(	i2c_t *	obj,
		uint8_t	devAddr,
		uint32_t	trials
	)

Check whether the target device is ready for communication.

Parameters

obj	Pointer to the i2c_t structure.
devAddr	7-bit address of the device.
trials	Number of trials.

Returns

I2C_OK if the device is ready, I2C_NACK_ADDR if it does not answer, otherwise the i2c_status_e error code.

i2c_master_read()

i2c_status_e i2c_master_read	(	i2c_t *	obj,
		uint8_t	dev_address,
		uint8_t *	data,
		uint16_t	size
	)

Read bytes from a device at a given address in master mode.

Parameters

obj	Pointer to the i2c_t structure.
dev_address	7-bit address of the device.
data	Pointer to the buffer receiving the data.
size	Number of bytes to read.

Returns

I2C_OK on success, otherwise the i2c_status_e error code.

i2c_master_write()

i2c_status_e i2c_master_write	(	i2c_t *	obj,
		uint8_t	dev_address,
		uint8_t *	data,
		uint16_t	size
	)

Write bytes to a device at a given address.

A size of 0 checks whether the device is ready (scan / ping) instead of writing.

Parameters

obj	Pointer to the i2c_t structure.
dev_address	7-bit address of the device.
data	Pointer to the data to write.
size	Number of bytes to write.

Returns

I2C_OK on success, otherwise the i2c_status_e error code.

i2c_setTiming()

void i2c_setTiming	(	i2c_t *	obj,
		uint32_t	frequency
	)

Set the transmission speed.

The I2C peripheral must be initialized before.

Parameters

obj	Pointer to the i2c_t structure.
frequency	I2C transmission speed in Hz.

i2c_slave_write_IT()

i2c_status_e i2c_slave_write_IT	(	i2c_t *	obj,
		uint8_t *	data,
		uint16_t	size
	)

Buffer bytes to send to the master in slave transmit mode.

Parameters

obj	Pointer to the i2c_t structure.
data	Pointer to the data to buffer.
size	Number of bytes to buffer, at most I2C_TXRX_BUFFER_SIZE.

Returns

I2C_OK on success, I2C_DATA_TOO_LONG if size exceeds I2C_TXRX_BUFFER_SIZE.

Variable Documentation

i2c_handles

I2C_HandleTypeDef* i2c_handles[I2C_NUM]

static

HAL handle of each initialized I2C instance, indexed by i2c_index_t.

Used by the interrupt handlers.