This namespace bundles the I2C-protocol-based interface to the TWI hardware. It provides logical cohesion for functions implement the Slave portions of the I2C protocol and prevents namespace collisions. More...

Enumerations
enum	I2cBusSpeed { kI2cBusSlow, kI2cBusFast }
	This enum lists I2C bus speed configurations. More...

enum	I2cStatusCodes { kI2cCompletedOk = 0x00, kI2cError = 0x01, kI2cTxPartial = 0x02, kI2cRxOverflow = 0x04, kI2cInProgress = 0x06 }
	This enum lists I2C status codes reported by the various transmit functions. More...

enum	I2cPullups { kPullupsOff, kPullupsOn }
	This enum lists the options for controlling the built-in pullups in the TWI hardware. More...

Functions
uint8_t	processI2cMessage (uint8_t *buffer, uint8_t len)
	This function must be defined by the user. It is called by the TWI interrupt function installed as part of I2cSlave.cpp whenever it receives a message from the Master. The user should implement this function to respond to the data in the buffer, taking actions and as appropriate returning data to the buffer (for asynchronous transmission to the Master). More...

void	start (uint8_t ownAddress, uint8_t speed=kI2cBusFast, bool answerGeneralCall=false)
	Configures the TWI hardware for I2C communications in Slave mode. You must call this function before conducting any I2C communications using the functions in this module. More...

void	stop ()
	Terminates the I2C communications using the TWI hardware, and disables the TWI interrupts. More...

void	pullups (uint8_t set=kPullupsOn)
	Sets the state of the internal pullups that are part of the TWI hardware. More...

bool	busy ()
	Reports whether the TWI hardware is busy communicating (either transmitting or receiving). More...

Detailed Description

This namespace bundles the I2C-protocol-based interface to the TWI hardware. It provides logical cohesion for functions implement the Slave portions of the I2C protocol and prevents namespace collisions.

These interfaces are buffered for both input and output and operate using interrupts associated with the TWI hardware. This means the functions return immediately after queuing data for transmission and the transmission happens asynchronously, using the dedicated TWI hardware.

These functions are designed around the normal operating modes of the I2C protocol. From a Slave device point of view, I2C communications consist of receiving a message from the Master telling it to do something, and in response:

Processing the message and taking whatever action is appropriate.
If that action includes returning data to the Master, queuing that data for transmission.

The functions defined by this module conform directly to the above I2C paradigm. The key function is processI2cMessage() and must be defined by the user. This function is called whenever the Slave receives a message and is also used to pass back any data that should be transmitted back to the Master.

Enumeration Type Documentation

§ I2cBusSpeed

enum I2cSlave::I2cBusSpeed

This enum lists I2C bus speed configurations.

Enumerator
kI2cBusSlow	I2C slow (standard) mode: 100 KHz.
kI2cBusFast	I2C fast mode: 400 KHz.

§ I2cPullups

enum I2cSlave::I2cPullups

This enum lists the options for controlling the built-in pullups in the TWI hardware.

Enumerator
kPullupsOff	Disable the built-in TWI hardware pullups.
kPullupsOn	Enable the built-in TWI hardware pullups.

§ I2cStatusCodes

enum I2cSlave::I2cStatusCodes

This enum lists I2C status codes reported by the various transmit functions.

Enumerator
kI2cCompletedOk	I2C communications completed with no error.
kI2cError	I2C communications encountered an error.
kI2cTxPartial	I2C Master terminated transmission before all data were sent.
kI2cRxOverflow	Recieved a message larger than can be held in the receive buffer.
kI2cInProgress	I2C communications on this message still in progress.

Function Documentation

§ busy()

bool I2cSlave::busy ( )

Reports whether the TWI hardware is busy communicating (either transmitting or receiving).

Returns: true if the TWI hardware is busy communicating; false if the TWI hardware is idle.

§ processI2cMessage()

uint8_t I2cSlave::processI2cMessage	(	uint8_t *	buffer,
		uint8_t	len
	)

This function must be defined by the user. It is called by the TWI interrupt function installed as part of I2cSlave.cpp whenever it receives a message from the Master. The user should implement this function to respond to the data in the buffer, taking actions and as appropriate returning data to the buffer (for asynchronous transmission to the Master).

The user should implement this function to do the following:

review the incoming data from the Master
take appropriate actions in response to that data
if data must be returned to the Master, write the data into the buffer and return the number of bytes you placed in the buffer
if no data must be returned to the Master, return 0

Note: This function is called at interrupt time, so the implementation must be kept short. If any significant work must be done as a result of the message received from the Master, this function should simply set a flag that can be detected by the main execution thread and have it do the heavy lifting.

buffer is both an input and output parameter. On entrance to the function, it contains the message received from the Master; on return from the function should contain data (if any) that should be sent back to the Master.
len is only an input parameter. It is the number of received bytes in the input buffer.

Returns: the number of bytes placed in the buffer to be sent back to the Master; 0 if no data is to be returned to the Master.

§ pullups()

void I2cSlave::pullups ( uint8_t set = kPullupsOn )

Sets the state of the internal pullups that are part of the TWI hardware.

start() automatically enables the internal pullups. You only need to call this function if you want to turn them off, or if you want to alter their state.

set the desired state of the built-in internal pullup. Defaults to enable (kPullupsOn).

§ start()

void I2cSlave::start	(	uint8_t	ownAddress,
		uint8_t	speed = `kI2cBusFast`,
		bool	answerGeneralCall = `false`
	)

Configures the TWI hardware for I2C communications in Slave mode. You must call this function before conducting any I2C communications using the functions in this module.

This function enables the TWI related interrupts and enables the built-in hardware pullups.

ownAddress is the I2C address for this slave.
speed the speed mode for the I2C protocol. The options are slow (100 KHz) or fast (400 KHz); the default is fast (kI2cBusFast).
answerGeneralCall pass true for the Slave to answer I2C general calls; false for the Slave to ignore I2C general calls and only answer calls to his specific address. The defaults is to not answer general calls. and defaults to not answering I2C general calls.

§ stop()

void I2cSlave::stop ( )

Terminates the I2C communications using the TWI hardware, and disables the TWI interrupts.

After calling this function, you need to call start() again if you want to resume I2C communications.

Enumerations

Functions