I2C Configuration Functions

Modules
	I2C hal tests
	The I2C HAL tests ensure driver conformance to defined behaviour.

Functions
void	i2c_init_direct (i2c_t *obj, const i2c_pinmap_t *pinmap)
	Initialize the I2C peripheral. More...
void	i2c_init (i2c_t *obj, PinName sda, PinName scl)
	Initialize the I2C peripheral. More...
void	i2c_free (i2c_t *obj)
	Release a I2C object. More...
void	i2c_frequency (i2c_t *obj, int hz)
	Configure the I2C frequency. More...
int	i2c_start (i2c_t *obj)
	Send START command. More...
int	i2c_stop (i2c_t *obj)
	Send STOP command. More...
int	i2c_read (i2c_t *obj, int address, char *data, int length, int stop)
	Blocking reading data. More...
int	i2c_write (i2c_t *obj, int address, const char *data, int length, int stop)
	Blocking sending data. More...
void	i2c_reset (i2c_t *obj)
	Reset I2C peripheral. More...
int	i2c_byte_read (i2c_t *obj, int last)
	Read one byte. More...
int	i2c_byte_write (i2c_t *obj, int data)
	Write one byte. More...
const PinMap *	i2c_master_sda_pinmap (void)
	Get the pins that support I2C SDA. More...
const PinMap *	i2c_master_scl_pinmap (void)
	Get the pins that support I2C SCL. More...
const PinMap *	i2c_slave_sda_pinmap (void)
	Get the pins that support I2C SDA. More...
const PinMap *	i2c_slave_scl_pinmap (void)
	Get the pins that support I2C SCL. More...

Detailed Description

Defined behavior

• i2c_init initializes i2c_t control structure
• i2c_init configures the pins used by I2C
• i2c_free returns the pins owned by the I2C object to their reset state
• i2c_frequency configure the I2C frequency
• i2c_start sends START command
• i2c_read reads length bytes from the I2C slave specified by address to the data buffer
• i2c_read reads generates a stop condition on the bus at the end of the transfer if stop parameter is non-zero
• i2c_read reads returns the number of symbols received from the bus
• i2c_write writes length bytes to the I2C slave specified by address from the data buffer
• i2c_write generates a stop condition on the bus at the end of the transfer if stop parameter is non-zero
• i2c_write returns zero on success, error code otherwise
• i2c_reset resets the I2C peripheral
• i2c_byte_read reads and return one byte from the specfied I2C slave
• i2c_byte_read uses last parameter to inform the slave that all bytes have been read
• i2c_byte_write writes one byte to the specified I2C slave
• i2c_byte_write returns 0 if NAK was received, 1 if ACK was received, 2 for timeout
• i2c_slave_mode enables/disables I2S slave mode
• i2c_slave_receive returns: 1 - read addresses, 2 - write to all slaves, 3 write addressed, 0 - the slave has not been addressed
• i2c_slave_read reads length bytes from the I2C master to the data buffer
• i2c_slave_read returns non-zero if a value is available, 0 otherwise
• i2c_slave_write writes length bytes to the I2C master from the data buffer
• i2c_slave_write returns non-zero if a value is available, 0 otherwise
• i2c_slave_address configures I2C slave address
• i2c_transfer_asynch starts I2C asynchronous transfer
• i2c_transfer_asynch writes tx_length bytes to the I2C slave specified by address from the tx buffer
• i2c_transfer_asynch reads rx_length bytes from the I2C slave specified by address to the rx buffer
• i2c_transfer_asynch generates a stop condition on the bus at the end of the transfer if stop parameter is non-zero
• The callback given to i2c_transfer_asynch is invoked when the transfer completes
• i2c_transfer_asynch specifies the logical OR of events to be registered
• The i2c_transfer_asynch function may use the DMAUsage hint to select the appropriate async algorithm
• i2c_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise returns 0.
• i2c_active returns non-zero if the I2C module is active or 0 if it is not
• i2c_abort_asynch aborts an on-going async transfer

Undefined behavior

• Calling i2c_init multiple times on the same i2c_t
• Calling any function other than i2c_init on a non-initialized i2c_t
• Initialising the I2C peripheral with invalid SDA and SCL pins.
• Passing pins that cannot be on the same peripheral
• Passing an invalid pointer as obj to any function
• Use of a null pointer as an argument to any function.
• Initialising the peripheral in slave mode if slave mode is not supported
• Operating the peripheral in slave mode without first specifying and address using i2c_slave_address
• Setting an address using i2c_slave_address after initialising the peripheral in master mode
• Setting an address to an I2C reserved value
• Specifying an invalid address when calling any read or write functions
• Setting the length of the transfer or receive buffers to larger than the buffers are
• Passing an invalid pointer as handler
• Calling i2c_abort_asynch when no transfer is currently in progress

Function Documentation

i2c_init_direct()

void i2c_init_direct	(	i2c_t *	obj,
		const i2c_pinmap_t *	pinmap
	)

Initialize the I2C peripheral.

It sets the default parameters for I2C peripheral, and configures its specifieds pins.

Parameters

obj	The I2C object
pinmap	Pinmap pointer to structure which holds static pinmap

i2c_init()

void i2c_init	(	i2c_t *	obj,
		PinName	sda,
		PinName	scl
	)

Initialize the I2C peripheral.

It sets the default parameters for I2C peripheral, and configures its specifieds pins.

Parameters

obj	The I2C object
sda	The sda pin
scl	The scl pin

i2c_free()

void i2c_free

(

i2c_t *

obj

)

Release a I2C object.

Return the pins owned by the I2C object to their reset state

Parameters

obj	The I2C object to deinitialize

i2c_frequency()

void i2c_frequency	(	i2c_t *	obj,
		int	hz
	)

Configure the I2C frequency.

Parameters

obj	The I2C object
hz	Frequency in Hz

i2c_start()

int i2c_start

(

i2c_t *

obj

)

Send START command.

Parameters

obj	The I2C object

i2c_stop()

int i2c_stop

(

i2c_t *

obj

)

Send STOP command.

Parameters

obj	The I2C object

i2c_read()

int i2c_read	(	i2c_t *	obj,
		int	address,
		char *	data,
		int	length,
		int	stop
	)

Blocking reading data.

Parameters

obj	The I2C object
address	8/11-bit address (last bit is 1)
data	The buffer for receiving
length	Number of bytes to read
stop	Stop to be generated after the transfer is done

Returns

Number of read bytes

i2c_write()

int i2c_write	(	i2c_t *	obj,
		int	address,
		const char *	data,
		int	length,
		int	stop
	)

Blocking sending data.

Parameters

obj	The I2C object
address	8/11-bit address (last bit is 0)
data	The buffer for sending
length	Number of bytes to write
stop	Stop to be generated after the transfer is done

Returns

zero or non-zero - Number of written bytes negative - I2C_ERROR_XXX status

i2c_reset()

void i2c_reset

(

i2c_t *

obj

)

Reset I2C peripheral.

TODO: The action here. Most of the implementation sends stop()

Parameters

obj	The I2C object

i2c_byte_read()

int i2c_byte_read	(	i2c_t *	obj,
		int	last
	)

Read one byte.

Parameters

obj	The I2C object
last	Acknoledge

Returns

The read byte

i2c_byte_write()

int i2c_byte_write	(	i2c_t *	obj,
		int	data
	)

Write one byte.

Parameters

obj	The I2C object
data	Byte to be written

Returns

0 if NAK was received, 1 if ACK was received, 2 for timeout, or 3 for other error.

i2c_master_sda_pinmap()

const PinMap * i2c_master_sda_pinmap

(

void

)

Get the pins that support I2C SDA.

Return a PinMap array of pins that support I2C SDA in master mode. The array is terminated with {NC, NC, 0}.

Returns

PinMap array

i2c_master_scl_pinmap()

const PinMap * i2c_master_scl_pinmap

(

void

)

Get the pins that support I2C SCL.

Return a PinMap array of pins that support I2C SCL in master mode. The array is terminated with {NC, NC, 0}.

Returns

PinMap array

i2c_slave_sda_pinmap()

const PinMap * i2c_slave_sda_pinmap

(

void

)

Get the pins that support I2C SDA.

Return a PinMap array of pins that support I2C SDA in slave mode. The array is terminated with {NC, NC, 0}.

Returns

PinMap array

i2c_slave_scl_pinmap()

const PinMap * i2c_slave_scl_pinmap

(

void

)

Get the pins that support I2C SCL.

Return a PinMap array of pins that support I2C SCL in slave mode. The array is terminated with {NC, NC, 0}.

Returns

PinMap array