I2cMaster Namespace Reference

This namespace bundles the I2C-protocol-based interface to the TWI hardware. It provides logical cohesion for functions implement the Master 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, kI2cNotStarted = 0x02, kI2cInProgress = 0x04 }
	This enum lists I2C status codes reported by the various transmit functions. More...
enum	I2cSendErrorCodes {   kI2cNoError = 0, kI2cErrTxBufferFull = 1, kI2cErrMsgTooLong = 2, kI2cErrNullStatusPtr = 3,   kI2cErrWriteWithoutData = 4, kI2cErrReadWithoutStorage = 5 }
	This enum lists I2C errors codes that may occur when you try to write a message. More...
enum	I2cPullups { kPullupsOff, kPullupsOn }
	This enum lists the options for controlling the built-in pullups in the TWI hardware. More...

Functions
void	start (uint8_t speed=kI2cBusFast)
	Configures the TWI hardware for I2C communications in Master 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...
uint8_t	writeAsync (uint8_t address, uint8_t registerAddress, volatile uint8_t *status)
	Transmit a single register address (a one-byte message) asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function). More...
uint8_t	writeAsync (uint8_t address, uint8_t registerAddress, uint8_t data, volatile uint8_t *status)
	Transmit a single register address and corresponding single byte of data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function). More...
uint8_t	writeAsync (uint8_t address, uint8_t registerAddress, const char *data, volatile uint8_t *status)
	Transmit a single register address and corresponding null-terminated string of data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function). More...
uint8_t	writeAsync (uint8_t address, uint8_t registerAddress, uint8_t *data, uint8_t numberBytes, volatile uint8_t *status)
	Transmit a single register address and corresponding buffer of data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function). More...
uint8_t	readAsync (uint8_t address, uint8_t numberBytes, volatile uint8_t *destination, volatile uint8_t *bytesRead, volatile uint8_t *status)
	Request to read data from a device and receive that data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function). When the status variable reports kI2cCompletedOk, the requested data can be read from the receive buffer. More...
uint8_t	readAsync (uint8_t address, uint8_t registerAddress, uint8_t numberBytes, volatile uint8_t *destination, volatile uint8_t *bytesRead, volatile uint8_t *status)
	Request to read data from a specific register on a device and receive that data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function). When the status variable reports kI2cCompletedOk, the requested data can be read from the receive buffer. More...
int	writeSync (uint8_t address, uint8_t registerAddress)
	Transmit a single register address (a one-byte message) synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error). More...
int	writeSync (uint8_t address, uint8_t registerAddress, uint8_t data)
	Transmit a single register address and corresponding single byte of data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error). More...
int	writeSync (uint8_t address, uint8_t registerAddress, const char *data)
	Transmit a single register address and corresponding null-terminated string of data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error). More...
int	writeSync (uint8_t address, uint8_t registerAddress, uint8_t *data, uint8_t numberBytes)
	Transmit a single register address and corresponding buffer of data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error). More...
int	readSync (uint8_t address, uint8_t numberBytes, uint8_t *destination)
	Request to read data from a device and receive that data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error). More...
int	readSync (uint8_t address, uint8_t registerAddress, uint8_t numberBytes, uint8_t *destination)
	Request to read data from a specific register on a device and receive that data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error). More...

Detailed Description

This namespace bundles the I2C-protocol-based interface to the TWI hardware. It provides logical cohesion for functions implement the Master 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 asynchronous transmit functions return immediately after queuing data in the output buffer for transmission and the transmission happens asynchronously, using dedicated TWI hardware. Similarly, data is received asynchronously and placed into the input buffer.

These functions are designed around the normal operating modes of the I2C protocol. From a Master device point of view, I2C communications consist of sending a designated device a message to do something, and then either:

• doing nothing because no further action required on the Master's part (e.g., telling the designated device to shutdown)
• transmitting additional data needed by the designated device (e.g., telling the designated device to store some data)
• receiving data from the designated device (e.g., telling the designated device to report the current temperature or to read back some data from its memory)

For very simple devices, the receipt of the message itself can suffice to tell it to do something. More commonly, the instruction to the designated device consists of a single byte that passes a "register address" on the device. It is call a register address because it often corresponds directly to a memory register on the device. But it is best to think of it as an instruction code to the designated device (e.g., 0x01 = report the temperature; 0x02 = set the units to either F or C (depending on additional data sent by the Master); 0x03 = report the humidity; etc.)

The functions defined by this module conform directly to the above I2C paradigm. The functions come in both synchronous and asynchronous versions. The synchronous versions simply call the asynchronous versions and block internally until the asynchronous operations are complete.

Note also that even "read" operations always begin (from the Master's point of view) with a "send" to the designated device the Master wants to read data from. For this reason all operations (both read and write) utilize the transmit buffer.

Enumeration Type Documentation

I2cBusSpeed

enum I2cMaster::I2cBusSpeed

This enum lists I2C bus speed configurations.

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

I2cPullups

enum I2cMaster::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.

I2cSendErrorCodes

enum I2cMaster::I2cSendErrorCodes

This enum lists I2C errors codes that may occur when you try to write a message.

Enumerator
kI2cNoError	No error.
kI2cErrTxBufferFull	The transmit buffer is full (try again later)
kI2cErrMsgTooLong	The message is too long for the transmit buffer.
kI2cErrNullStatusPtr	The pointer to the status variable is null (need to provide a valid pointer)
kI2cErrWriteWithoutData	No data provided to send.
kI2cErrReadWithoutStorage	Performing a write+read, but no buffer provided to store the "read" data.

I2cStatusCodes

enum I2cMaster::I2cStatusCodes

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

Enumerator
kI2cCompletedOk	I2C communications completed on this message with no error.
kI2cError	I2C communications had an error on this message.
kI2cNotStarted	I2C communications not started on this message.
kI2cInProgress	I2C communications on this message still in progress.

Function Documentation

busy()

bool I2cMaster::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.

pullups()

void I2cMaster::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).

readAsync() [1/2]

uint8_t I2cMaster::readAsync	(	uint8_t	address,
		uint8_t	numberBytes,
		volatile uint8_t *	destination,
		volatile uint8_t *	bytesRead,
		volatile uint8_t *	status
	)

Request to read data from a device and receive that data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function). When the status variable reports kI2cCompletedOk, the requested data can be read from the receive buffer.

If the transmit buffer is full, this function will block until room is available in the buffer.

• address the I2C address of the destination device you want to read from.
• numberBytes the number of bytes you expect to read.
• destination a pointer to a buffer in which the received data will be stored; the buffer should be at least numberBytes large.
• bytesRead a pointer to a byte-sized countered in which the TWI hardware will asynchronously keep track of how many bytes have been received.
• status a pointer to a byte-size location in which the commincations status of this message will be reported (volatile because the value will be updates asynchronously after the function returns by the TWI hardware) values correspond to I2cStatusCodes.

Returns

error codes corresponding to I2cSendErrorCodes (0 means no error)

readAsync() [2/2]

uint8_t I2cMaster::readAsync	(	uint8_t	address,
		uint8_t	registerAddress,
		uint8_t	numberBytes,
		volatile uint8_t *	destination,
		volatile uint8_t *	bytesRead,
		volatile uint8_t *	status
	)

Request to read data from a specific register on a device and receive that data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function). When the status variable reports kI2cCompletedOk, the requested data can be read from the receive buffer.

If the transmit buffer is full, this function will block until room is available in the buffer.

• address the I2C address of the destination device you want to read from.
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it what you want to read (e.g., temperature or the starting address of a block of memory).
• numberBytes the number of bytes you expect to read.
• destination a pointer to a buffer in which the received data will be stored; the buffer should be at least numberBytes large.
• bytesRead a pointer to a byte-sized countered in which the TWI hardware will asynchronously keep track of how many bytes have been received.
• status a pointer to a byte-size location in which the commincations status of this message will be reported (volatile because the value will be updates asynchronously after the function returns by the TWI hardware); values correspond to I2cStatusCodes.

Returns

error codes corresponding to I2cSendErrorCodes (0 means no error)

readSync() [1/2]

int I2cMaster::readSync	(	uint8_t	address,
		uint8_t	numberBytes,
		uint8_t *	destination
	)

Request to read data from a device and receive that data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error).

• address the I2C address of the destination device you want to read from.
• numberBytes the number of bytes you expect to read.
• destination a pointer to a buffer in which the received data will be stored; the buffer should be at least numberBytes large.

Returns

an error code which if positive corresponds to I2cSendErrorCodes, or if negative the absolute value corresponds to I2cStatusCodes (0 means no error).

readSync() [2/2]

int I2cMaster::readSync	(	uint8_t	address,
		uint8_t	registerAddress,
		uint8_t	numberBytes,
		uint8_t *	destination
	)

Request to read data from a specific register on a device and receive that data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error).

• address the I2C address of the destination device you want to read from.
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it what you want to read (e.g., temperature or the starting address of a block of memory).
• numberBytes the number of bytes you expect to read.
• destination a pointer to a buffer in which the received data will be stored; the buffer should be at least numberBytes large.

Returns

an error code which if positive corresponds to I2cSendErrorCodes, or if negative the absolute value corresponds to I2cStatusCodes (0 means no error).

start()

void I2cMaster::start

(

uint8_t

speed = kI2cBusFast

)

Configures the TWI hardware for I2C communications in Master 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.

• speed the speed mode for the I2C protocol. The options are slow (100 KHz) or fast (400 KHz); the default is fast (kI2cBusFast).

stop()

void I2cMaster::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.

writeAsync() [1/4]

uint8_t I2cMaster::writeAsync	(	uint8_t	address,
		uint8_t	registerAddress,
		volatile uint8_t *	status
	)

Transmit a single register address (a one-byte message) asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function).

If the transmit buffer is full, this function will block until room is available in the buffer.

• address the I2C address of the destination device for this message
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it to do something (e.g., turn off or on).
• status a pointer to a byte-size location in which the commincations status of this message will be reported (volatile because the value will be updates asynchronously after the function returns by the TWI hardware); values correspond to I2cStatusCodes.

Returns

error codes corresponding to I2cSendErrorCodes (0 means no error)

writeAsync() [2/4]

uint8_t I2cMaster::writeAsync	(	uint8_t	address,
		uint8_t	registerAddress,
		uint8_t	data,
		volatile uint8_t *	status
	)

Transmit a single register address and corresponding single byte of data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function).

If the transmit buffer is full, this function will block until room is available in the buffer.

• address the I2C address of the destination device for this message
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it to do something (e.g., set the volume level).
• data a single byte of data serving as a parameter to the register address (e.g., the volume level to set).
• status a pointer to a byte-size location in which the commincations status of this message will be reported (volatile because the value will be updates asynchronously after the function returns by the TWI hardware); values correspond to I2cStatusCodes.

Returns

error codes corresponding to I2cSendErrorCodes (0 means no error)

writeAsync() [3/4]

uint8_t I2cMaster::writeAsync	(	uint8_t	address,
		uint8_t	registerAddress,
		const char *	data,
		volatile uint8_t *	status
	)

Transmit a single register address and corresponding null-terminated string of data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function).

If the transmit buffer is full, this function will block until room is available in the buffer.

• address the I2C address of the destination device for this message
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it to do something (e.g., an address in a memory device).
• data a null-terminated string of data serving as a parameter to the register address (e.g., a string to store sequentially starting at the registerAddress).
• status a pointer to a byte-size location in which the commincations status of this message will be reported (volatile because the value will be updates asynchronously after the function returns by the TWI hardware); values correspond to I2cStatusCodes.

Returns

error codes corresponding to I2cSendErrorCodes (0 means no error)

writeAsync() [4/4]

uint8_t I2cMaster::writeAsync	(	uint8_t	address,
		uint8_t	registerAddress,
		uint8_t *	data,
		uint8_t	numberBytes,
		volatile uint8_t *	status
	)

Transmit a single register address and corresponding buffer of data asynchronously. This function queues the message and returns immediately. Eventual status of the transmitted message can be monitored via the designated status variable (passed as a pointer to this function).

If the transmit buffer is full, this function will block until room is available in the buffer.

• address the I2C address of the destination device for this message
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it to do something (e.g., an address in a memory device).
• data a buffer of data serving as a parameter to the register address (e.g., the data to store sequentially starting at the registerAddress).
• numberBytes the number of bytes from the buffer to transmit.
• status a pointer to a byte-size location in which the commincations status of this message will be reported (volatile because the value will be updates asynchronously after the function returns by the TWI hardware); values correspond to I2cStatusCodes.

Returns

error codes corresponding to I2cSendErrorCodes (0 means no error)

writeSync() [1/4]

int I2cMaster::writeSync	(	uint8_t	address,
		uint8_t	registerAddress
	)

Transmit a single register address (a one-byte message) synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error).

• address the I2C address of the destination device for this message.
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it to do something (e.g., turn off or on).

Returns

an error code which if positive corresponds to I2cSendErrorCodes, or if negative the absolute value corresponds to I2cStatusCodes (0 means no error).

writeSync() [2/4]

int I2cMaster::writeSync	(	uint8_t	address,
		uint8_t	registerAddress,
		uint8_t	data
	)

Transmit a single register address and corresponding single byte of data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error).

• address the I2C address of the destination device for this message.
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it to do something (e.g., set the volume level).
• data a single byte of data serving as a parameter to the register address (e.g., the volume level to set).

Returns

an error code which if positive corresponds to I2cSendErrorCodes, or if negative the absolute value corresponds to I2cStatusCodes (0 means no error).

writeSync() [3/4]

int I2cMaster::writeSync	(	uint8_t	address,
		uint8_t	registerAddress,
		const char *	data
	)

Transmit a single register address and corresponding null-terminated string of data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error).

• address the I2C address of the destination device for this message
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it to do something (e.g., an address in a memory device).
• data a null-terminated string of data serving as a parameter to the register address (e.g., a string to store sequentially starting at the registerAddress).

Returns

an error code which if positive corresponds to I2cSendErrorCodes, or if negative the absolute value corresponds to I2cStatusCodes (0 means no error).

writeSync() [4/4]

int I2cMaster::writeSync	(	uint8_t	address,
		uint8_t	registerAddress,
		uint8_t *	data,
		uint8_t	numberBytes
	)

Transmit a single register address and corresponding buffer of data synchronously. This function blocks until the communications exchange is complete or encounters an error. Error codes are returned (0 means no error).

• address the I2C address of the destination device for this message
• registerAddress in device-centric terms, the register address on the destination device; think of it as a one-byte instruction to the destination device telling it to do something (e.g., an address in a memory device).
• data a buffer of data serving as a parameter to the register address (e.g., the data to store sequentially starting at the registerAddress).
• numberBytes the number of bytes from the buffer to transmit.

Returns

an error code which if positive corresponds to I2cSendErrorCodes, or if negative the absolute value corresponds to I2cStatusCodes (0 means no error).