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.
void	i2c_init (i2c_t *obj, PinName sda, PinName scl)
	Initialize the I2C peripheral.
void	i2c_free (i2c_t *obj)
	Release a I2C object.
void	i2c_frequency (i2c_t *obj, int hz)
	Configure the I2C frequency.
int	i2c_read (i2c_t *obj, int address, char *data, int length, int stop)
	Blocking read of data.
int	i2c_write (i2c_t *obj, int address, const char *data, int length, int stop)
	Blocking write of data.
int	i2c_start (i2c_t *obj)
	Send START command.
int	i2c_stop (i2c_t *obj)
	Send STOP command.
void	i2c_reset (i2c_t *obj)
	Reset I2C peripheral.
int	i2c_byte_read (i2c_t *obj, int last)
	Read one byte.
int	i2c_byte_write (i2c_t *obj, int data)
	Write one byte.
const PinMap *	i2c_master_sda_pinmap (void)
	Get the pins that support I2C SDA.
const PinMap *	i2c_master_scl_pinmap (void)
	Get the pins that support I2C SCL.
const PinMap *	i2c_slave_sda_pinmap (void)
	Get the pins that support I2C SDA.
const PinMap *	i2c_slave_scl_pinmap (void)
	Get the pins that support I2C SCL.
i2c_capabilities_t const *	i2c_get_capabilities ()
	Fills the given i2c_capabilities_t structure with the capabilities of the I2C peripheral.

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

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

Blocking read of data.

This function may be called in these I2C states:

• IDLE
• HOLDING_BUS
• BYTE_READ (to do a repeated start after a single byte transaction)
• BYTE_WRITE (to do a repeated start after a single byte transaction)

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. Allowed to be 0 only if the supports_zero_length_transfer_transaction capability is true.
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 write of data.

This function may be called in these I2C states:

• IDLE
• HOLDING_BUS
• BYTE_READ (to do a repeated start after a single byte transaction)
• BYTE_WRITE (to do a repeated start after a single byte transaction)

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. Allowed to be 0 only if the supports_zero_length_transfer_transaction capability is true.
stop	Stop to be generated after the transfer is done

Return values

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

i2c_start()

int i2c_start

(

i2c_t *

obj

)

Send START command.

The I2C class guarantees that this will only be called at appropriate times (when the bus is idle or during an existing single-byte transaction to do a repeated start).

Note that some I2C peripherals (e.g. RP2xxx, newer STM32s) are not capable of sending a start condition until the address is known. On these MCUs, the start condition will not actually be sent until the first write_byte() call after the start().

This function may be called in these I2C states:

• IDLE
• HOLDING_BUS
• ADDRESSED (to do a repeated start after a zero length transaction, if supported)
• BYTE_READ
• BYTE_WRITE

Parameters

obj	The I2C object

i2c_stop()

int i2c_stop

(

i2c_t *

obj

)

Send STOP command.

This function may be called in these I2C states:

• ADDRESSED (to complete a zero length transaction, only allowed if the supports_zero_length_transfer_single_byte capability is enabled)
• BYTE_READ
• BYTE_WRITE

Parameters

obj	The I2C object

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.

This function may be called in these I2C states:

• ADDRESSED
• BYTE_READ

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.

This function may be called in these I2C states:

• STARTED (to send the address byte)
• ADDRESSED
• BYTE_WRITE

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

i2c_get_capabilities()

i2c_capabilities_t const * i2c_get_capabilities

(

)

Fills the given i2c_capabilities_t structure with the capabilities of the I2C peripheral.

Returns

Pointer to constant capabilities data