Driver for the TWI (Two-Wire Interface).

This driver provides access to the main features of the TWI controller. The TWI interconnects components on a unique two-wire bus. The TWI is programmable as a master or a slave with sequential or single-byte access. Multiple master capability is supported.

Usage

Enable the TWI peripheral clock in the PMC.
Enable the required TWI PIOs (see pio.h).
Enable TWI master mode by calling twi_enable_master_mode if it is a master on the I2C bus.
Configure the TWI in master mode by calling twi_master_init.
Send data to a slave device on the I2C bus by calling twi_master_write.
Receive data from a slave device on the I2C bus by calling the twi_master_read.
Enable TWI slave mode by calling twi_enable_slave_mode if it is a slave on the I2C bus.
Configure the TWI in slave mode by calling twi_slave_init.

Modules
	Related Project(s)
	In this section you can find all the projects related to the Two-Wire Interface (TWI).

Macros
#define	I2C_FAST_MODE_SPEED 400000

#define	LOW_LEVEL_TIME_LIMIT 384000

#define	TWI_CLK_CALC_ARGU 4

#define	TWI_CLK_DIV_MAX 0xFF

#define	TWI_CLK_DIV_MIN 7

#define	TWI_CLK_DIVIDER 2

#define	TWI_WP_KEY_VALUE TWI_WPMR_WPKEY_PASSWD

Functions
void	twi_disable_interrupt (Twi *p_twi, uint32_t ul_sources)
	Disable TWI interrupts. More...

void	twi_disable_master_mode (Twi *p_twi)
	Disable TWI master mode. More...

void	twi_disable_slave_mode (Twi *p_twi)
	Disable TWI slave mode. More...

void	twi_enable_interrupt (Twi *p_twi, uint32_t ul_sources)
	Enable TWI interrupts. More...

void	twi_enable_master_mode (Twi *p_twi)
	Enable TWI master mode. More...

void	twi_enable_slave_mode (Twi *p_twi)
	Enable TWI slave mode. More...

uint32_t	twi_get_interrupt_mask (Twi *p_twi)
	Read TWI interrupt mask. More...

uint32_t	twi_get_interrupt_status (Twi *p_twi)
	Get TWI interrupt status. More...

Pdc *	twi_get_pdc_base (Twi *p_twi)
	Get TWI PDC base address. More...

uint32_t	twi_master_init (Twi p_twi, const twi_options_t p_opt)
	Initialize TWI master mode. More...

uint32_t	twi_master_read (Twi p_twi, twi_packet_t p_packet)
	Read multiple bytes from a TWI compatible slave device. More...

uint32_t	twi_master_write (Twi p_twi, twi_packet_t p_packet)
	Write multiple bytes to a TWI compatible slave device. More...

uint32_t	twi_mk_addr (const uint8_t *addr, int len)
	Construct the TWI module address register field. More...

uint32_t	twi_probe (Twi *p_twi, uint8_t uc_slave_addr)
	Test if a chip answers a given I2C address. More...

uint8_t	twi_read_byte (Twi *p_twi)
	Reads a byte from the TWI bus. More...

void	twi_reset (Twi *p_twi)
	Reset TWI. More...

void	twi_set_slave_addr (Twi *p_twi, uint32_t ul_device_addr)
	Set TWI slave address. More...

uint32_t	twi_set_speed (Twi *p_twi, uint32_t ul_speed, uint32_t ul_mck)
	Set the I2C bus speed in conjunction with the clock frequency. More...

void	twi_slave_init (Twi *p_twi, uint32_t ul_device_addr)
	Initialize TWI slave mode. More...

uint32_t	twi_slave_read (Twi p_twi, uint8_t p_data)
	Read data from master. More...

uint32_t	twi_slave_write (Twi p_twi, uint8_t p_data)
	Write data to TWI bus. More...

void	twi_write_byte (Twi *p_twi, uint8_t uc_byte)
	Sends a byte of data to one of the TWI slaves on the bus. More...

#define I2C_FAST_MODE_SPEED 400000

Referenced by twi_set_speed().

#define LOW_LEVEL_TIME_LIMIT 384000

Referenced by twi_set_speed().

#define TWI_CLK_CALC_ARGU 4

Referenced by twi_set_speed().

#define TWI_CLK_DIV_MAX 0xFF

Referenced by twi_set_speed().

#define TWI_CLK_DIV_MIN 7

Referenced by twi_set_speed().

#define TWI_CLK_DIVIDER 2

Referenced by twi_set_speed().

#define TWI_WP_KEY_VALUE TWI_WPMR_WPKEY_PASSWD

void twi_disable_interrupt	(	Twi *	p_twi,
		uint32_t	ul_sources
	)

Disable TWI interrupts.

Parameters

p_twi	Pointer to a TWI instance.
ul_sources	Interrupts to be disabled.

Referenced by BOARD_TWI_Handler(), freertos_twi_master_init(), freertos_twi_read_packet_async(), freertos_twi_write_packet_async(), and local_twi_handler().

void twi_disable_master_mode ( Twi * p_twi )

Disable TWI master mode.

Parameters

p_twi Pointer to a TWI instance.

void twi_disable_slave_mode ( Twi * p_twi )

Disable TWI slave mode.

Parameters

p_twi Pointer to a TWI instance.

void twi_enable_interrupt	(	Twi *	p_twi,
		uint32_t	ul_sources
	)

Enable TWI interrupts.

Parameters

p_twi	Pointer to a TWI instance.
ul_sources	Interrupts to be enabled.

Referenced by BOARD_TWI_Handler(), freertos_twi_master_init(), freertos_twi_read_packet_async(), freertos_twi_write_packet_async(), main(), twi_master_pdc_read(), and twi_master_pdc_write().

void twi_enable_master_mode ( Twi * p_twi )

Enable TWI master mode.

Parameters

p_twi Pointer to a TWI instance.

Referenced by freertos_twi_master_init(), and twi_master_init().

void twi_enable_slave_mode ( Twi * p_twi )

Enable TWI slave mode.

Parameters

p_twi Pointer to a TWI instance.

Referenced by twi_slave_init().

uint32_t twi_get_interrupt_mask ( Twi * p_twi )

Read TWI interrupt mask.

Parameters

p_twi Pointer to a TWI instance.

Returns: The interrupt mask value.

Referenced by BOARD_TWI_Handler(), and local_twi_handler().

uint32_t twi_get_interrupt_status ( Twi * p_twi )

Get TWI interrupt status.

Parameters

p_twi Pointer to a TWI instance.

Return values

TWI	interrupt status.

Referenced by BOARD_TWI_Handler(), and local_twi_handler().

Pdc* twi_get_pdc_base ( Twi * p_twi )

Get TWI PDC base address.

Parameters

p_twi Pointer to a TWI instance.

Returns: TWI PDC registers base for PDC driver to access.

References Assert, and NULL.

Referenced by main().

uint32_t twi_master_init	(	Twi *	p_twi,
		const twi_options_t *	p_opt
	)

Initialize TWI master mode.

Parameters

p_twi	Pointer to a TWI instance.
p_opt	Options for initializing the TWI module (see twi_options_t).

Returns: TWI_SUCCESS if initialization is complete, error code otherwise.

References FAIL, twi_options::master_clk, twi_options::smbus, twi_options::speed, twi_enable_master_mode(), TWI_INVALID_ARGUMENT, twi_reset(), twi_set_speed(), and TWI_SUCCESS.

Referenced by main(), and twi_master_setup().

uint32_t twi_master_read	(	Twi *	p_twi,
		twi_packet_t *	p_packet
	)

Read multiple bytes from a TWI compatible slave device.

Note: This function will NOT return until all data has been read or error occurs.

Parameters

p_twi	Pointer to a TWI instance.
p_packet	Packet information and data (see twi_packet_t).

Returns: TWI_SUCCESS if all bytes were read, error code otherwise.

References twi_packet::addr, twi_packet::addr_length, twi_packet::buffer, twi_packet::chip, twi_packet::length, TWI_ERROR_TIMEOUT, TWI_INVALID_ARGUMENT, twi_mk_addr(), TWI_RECEIVE_NACK, TWI_SUCCESS, and TWI_TIMEOUT.

Referenced by at24cxx_read_byte(), at24cxx_read_continuous(), at24cxx_read_page(), main(), mcp980x_read_register(), mxt_get_crc_value(), mxt_get_message_count(), mxt_probe_device(), mxt_read_config_object(), mxt_read_config_reg(), mxt_read_id_block(), mxt_read_message(), mxt_read_object_table(), and qt_read_regs().

uint32_t twi_master_write	(	Twi *	p_twi,
		twi_packet_t *	p_packet
	)

Write multiple bytes to a TWI compatible slave device.

Note: This function will NOT return until all data has been written or error occurred.

Parameters

p_twi	Pointer to a TWI instance.
p_packet	Packet information and data (see twi_packet_t).

Returns: TWI_SUCCESS if all bytes were written, error code otherwise.

References twi_packet::addr, twi_packet::addr_length, twi_packet::buffer, twi_packet::chip, twi_packet::length, TWI_INVALID_ARGUMENT, twi_mk_addr(), TWI_RECEIVE_NACK, and TWI_SUCCESS.

Referenced by at24cxx_acknowledge_polling(), at24cxx_write_byte(), at24cxx_write_continuous(), at24cxx_write_page(), main(), mcp980x_write_register(), mxt_write_config_object(), mxt_write_config_reg(), qt_read_regs(), qt_write_regs(), twi_probe(), and wm8731_write_register().

uint32_t twi_mk_addr	(	const uint8_t *	addr,
		int	len
	)

Construct the TWI module address register field.

The TWI module address register is sent out MSB first. And the size controls which byte is the MSB to start with.

Please see the device datasheet for details on this.

Referenced by twi_master_pdc_read(), twi_master_pdc_write(), twi_master_read(), and twi_master_write().

uint32_t twi_probe	(	Twi *	p_twi,
		uint8_t	uc_slave_addr
	)

Test if a chip answers a given I2C address.

Parameters

p_twi	Pointer to a TWI instance.
uc_slave_addr	Address of the remote chip to search for.

Returns: TWI_SUCCESS if a chip was found, error code otherwise.

References twi_packet::addr, twi_packet::addr_length, twi_packet::buffer, twi_packet::chip, data, twi_packet::length, and twi_master_write().

uint8_t twi_read_byte ( Twi * p_twi )

Reads a byte from the TWI bus.

Parameters

p_twi Pointer to a TWI instance.

Returns: The byte read.

Referenced by BOARD_TWI_Handler(), freertos_twi_read_packet_async(), and main().

void twi_reset ( Twi * p_twi )

Reset TWI.

Parameters

p_twi Pointer to a TWI instance.

Referenced by freertos_twi_master_init(), twi_master_init(), and twi_slave_init().

void twi_set_slave_addr	(	Twi *	p_twi,
		uint32_t	ul_device_addr
	)

Set TWI slave address.

Parameters

p_twi	Pointer to a TWI instance.
ul_device_addr	Device address of the SAM slave device on the I2C bus.

uint32_t twi_set_speed	(	Twi *	p_twi,
		uint32_t	ul_speed,
		uint32_t	ul_mck
	)

Set the I2C bus speed in conjunction with the clock frequency.

Parameters

p_twi	Pointer to a TWI instance.
ul_speed	The desired I2C bus speed (in Hz).
ul_mck	Main clock of the device (in Hz).

Return values

PASS	New speed setting is accepted.
FAIL	New speed setting is rejected.

References FAIL, I2C_FAST_MODE_SPEED, LOW_LEVEL_TIME_LIMIT, PASS, TWI_CLK_CALC_ARGU, TWI_CLK_DIV_MAX, TWI_CLK_DIV_MIN, and TWI_CLK_DIVIDER.

Referenced by create_twi_task(), and twi_master_init().

void twi_slave_init	(	Twi *	p_twi,
		uint32_t	ul_device_addr
	)

Initialize TWI slave mode.

Parameters

p_twi	Pointer to a TWI instance.
ul_device_addr	Device address of the SAM slave device on the I2C bus.

References twi_enable_slave_mode(), and twi_reset().

Referenced by main(), and twi_slave_setup().

uint32_t twi_slave_read	(	Twi *	p_twi,
		uint8_t *	p_data
	)

Read data from master.

Note: This function will NOT return until master sends a STOP condition.

Parameters

p_twi	Pointer to a TWI instance.
p_data	Pointer to the data buffer where data received will be stored.

Returns: Number of bytes read.

uint32_t twi_slave_write	(	Twi *	p_twi,
		uint8_t *	p_data
	)

Write data to TWI bus.

Note: This function will NOT return until master sends a STOP condition.

Parameters

p_twi	Pointer to a TWI instance.
p_data	Pointer to the data buffer to be sent.

Returns: Number of bytes written.

void twi_write_byte	(	Twi *	p_twi,
		uint8_t	uc_byte
	)

Sends a byte of data to one of the TWI slaves on the bus.

Parameters

p_twi	Pointer to a TWI instance.
byte	The byte to send.

Referenced by BOARD_TWI_Handler().

Microchip® Advanced Software Framework

Modules

Macros

Functions