twi.h File Reference

Header for twi module. More...

#include "stm32_def.h"
#include "PeripheralPins.h"

Classes
struct	i2c_s
	I2C peripheral context: instance, HAL handle, pins, interrupts and slave buffers. More...

Macros
#define	OFFSETOF(type, member)   ((uint32_t) (&(((type *)(0))->member)))
	Manual implementation of offsetof (a gcc built-in function).
#define	I2C_IRQ_PRIO   2
	I2C interrupt preemption priority.
#define	I2C_IRQ_SUBPRIO   0
	I2C interrupt sub-priority.
#define	I2C_TXRX_BUFFER_SIZE   32
	Size in bytes of the slave Tx/Rx buffer of an i2c_t object.

Typedefs
typedef struct i2c_s	i2c_t
	I2C object type, see i2c_s.

Enumerations
enum	i2c_status_e {   I2C_OK = 0 , I2C_DATA_TOO_LONG = 1 , I2C_NACK_ADDR = 2 , I2C_NACK_DATA = 3 ,   I2C_ERROR = 4 , I2C_TIMEOUT = 5 , I2C_BUSY = 6 }
	I2C status returned by the i2c_* functions. More...

Functions
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.
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.

Detailed Description

Header for twi module.

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.

Macro Definition Documentation

I2C_IRQ_PRIO

#define I2C_IRQ_PRIO   2

I2C interrupt preemption priority.

Can be overridden before including this file.

I2C_IRQ_SUBPRIO

#define I2C_IRQ_SUBPRIO   0

I2C interrupt sub-priority.

Can be overridden before including this file.

I2C_TXRX_BUFFER_SIZE

#define I2C_TXRX_BUFFER_SIZE   32

Size in bytes of the slave Tx/Rx buffer of an i2c_t object.

Can be overridden before including this file.

Note

The size cannot exceed 255.

OFFSETOF

#define OFFSETOF	(		type,
			member
	)		((uint32_t) (&(((type *)(0))->member)))

Manual implementation of offsetof (a gcc built-in function).

Parameters

type	Structure type.
member	Member of the structure.

Enumeration Type Documentation

i2c_status_e

enum i2c_status_e

I2C status returned by the i2c_* functions.

Enumerator
I2C_OK	Operation completed successfully.
I2C_DATA_TOO_LONG	Data does not fit in the buffer.
I2C_NACK_ADDR	Address was not acknowledged (NACK).
I2C_NACK_DATA	Data was not acknowledged (NACK).
I2C_ERROR	Other error.
I2C_TIMEOUT	Operation timed out.
I2C_BUSY	Bus or peripheral is busy.

Function Documentation

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

void i2c_deinit

(

i2c_t *

obj

)

Deinitialize the GPIO pins and the I2C peripheral.

Parameters

obj	Pointer to the i2c_t structure.

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.