This file provides functions that interface to the TWI (two-wire serial interface) hardware of the Arduino Uno (ATmega328) and Arduino Mega (ATmega2560), providing a high-level interface to I2C protocol communications. Include this file if you want your application will operate in Master mode as defined in the I2C protocol. More...
#include <stdint.h>#include <stdlib.h>#include <util/atomic.h>
Go to the source code of this file.
Namespaces | |
| I2cMaster | |
| 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. | |
Enumerations | |
| enum | I2cMaster::I2cBusSpeed { I2cMaster::kI2cBusSlow, I2cMaster::kI2cBusFast } |
| This enum lists I2C bus speed configurations. More... | |
| enum | I2cMaster::I2cStatusCodes { I2cMaster::kI2cCompletedOk = 0x00, I2cMaster::kI2cError = 0x01, I2cMaster::kI2cNotStarted = 0x02, I2cMaster::kI2cInProgress = 0x04 } |
| This enum lists I2C status codes reported by the various transmit functions. More... | |
| enum | I2cMaster::I2cSendErrorCodes { I2cMaster::kI2cNoError = 0, I2cMaster::kI2cErrTxBufferFull = 1, I2cMaster::kI2cErrMsgTooLong = 2, I2cMaster::kI2cErrNullStatusPtr = 3, I2cMaster::kI2cErrWriteWithoutData = 4, I2cMaster::kI2cErrReadWithoutStorage = 5 } |
| This enum lists I2C errors codes that may occur when you try to write a message. More... | |
| enum | I2cMaster::I2cPullups { I2cMaster::kPullupsOff, I2cMaster::kPullupsOn } |
| This enum lists the options for controlling the built-in pullups in the TWI hardware. More... | |
Functions | |
| 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. More... | |
| void | I2cMaster::stop () |
| Terminates the I2C communications using the TWI hardware, and disables the TWI interrupts. More... | |
| void | I2cMaster::pullups (uint8_t set=kPullupsOn) |
| Sets the state of the internal pullups that are part of the TWI hardware. More... | |
| bool | I2cMaster::busy () |
| Reports whether the TWI hardware is busy communicating (either transmitting or receiving). More... | |
| 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). More... | |
| 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). More... | |
| 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). More... | |
| 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). More... | |
| 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. More... | |
| 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. More... | |
| 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). More... | |
| 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). More... | |
| 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). More... | |
| 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). More... | |
| 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). More... | |
| 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). More... | |
Detailed Description
This file provides functions that interface to the TWI (two-wire serial interface) hardware of the Arduino Uno (ATmega328) and Arduino Mega (ATmega2560), providing a high-level interface to I2C protocol communications. Include this file if you want your application will operate in Master mode as defined in the I2C protocol.
To use these functions, include I2cMaster.h and link against I2cMaster.cpp.
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.
The transmit buffer is a ring buffer. If you try to queue more data than the transmit buffer can hold, the write functions will block until there is room in the buffer (as a result of data being transmitted). Receive buffers are provided by the callers of these functions. Note that due to the nature of the I2C protocol, Master I2C "read" operations must still write a command instructing the destination device to send data for the Master to read, and thus "read" operations still utilize the transmit buffer.
The size of the transmit buffer can be set at compile time via macro constants (the receive buffers are provided the corresponding functions are called). The default size of the transmit buffer assumes the maximum transmit message length is 24 bytes and allows 3 out-going messages to be queued. You can change these defaults by defining the macros I2C_MASTER_MAX_TX_MSG_LEN to specify the maximum transmit message length and I2C_MASTER_MAX_TX_MSG_NBR to specify the maximum number of transmit messages to hold in the buffer. You need to make these define these macros prior to including the file I2cMaster.h, each time it is included. So you should define these using a compiler option (e.g., -DI2C_MASTER_MAX_TX_MSG_LEN=32 -DI2C_MASTER_MAX_TX_MSG_NBR=5) to ensure they are consistently defined throughout your project.
This interface assumes your application will operator in I2C Master mode as defined in the I2C protocol. If you wish your application to operate in I2C Slave mode, then instead include I2cSlave.h and link against I2cSlave.cpp.
- Note
- Only one of I2cMaster.cpp and I2cSlave.cpp can be linking into your application. These two files install different, incompatible versions of the TWI interrupt function. AVRTools does not support building an application that functions both as a Master and as a Slave under the I2C protocol. This limitation allows the corresponding TWI interrupt functions to be significantly leaner and faster.
