A better I2C master library, originally by Wayne Truchsess. See http://dsscircuits.com/index.php/articles/66-arduino-i2c-master-library
On most Arduino boards, SDA (data line) is on analog input pin 4, and SCL (clock line) is on analog input pin 5. On the Arduino Mega, SDA is digital pin 20 and SCL is 21. (source: https://www.arduino.cc/en/Reference/Wire)
For devices that don't use de-facto standard register scheme you can use the low-level methods directly
I2c._start();
I2c._sendAddress(slave_addr);
I2c._sendByte(my_byte);
I2c._stop();
For more details see the documentation below, section titled: Low-level Methods
- Description:
- Enables the I2C hardware
- Parameters:
- none
- Returns:
- none
- Description:
- Disables the I2C hardware
- Parameters:
- none
- Returns:
- none
- Description:
- Enables high speed mode (400kHz)
- Parameters:
-
fast - Boolean
True: High Speed
False: Low Speed
- Returns:
- none
- Description:
- Enables/disables internal pullup resistors
- Parameters:
-
activate - Boolean
True: Enable internal pullup resistors (default)
False: Disable internal pullup resistors
- Returns:
- none
- Description:
- Allows the user to program a time out limit to prevent and recover from I2C bus lockups. I2C bus lockups have a tendency to freeze a program which typically requires a power cycle to restart your program. This allows the user to define a time out in which the I2C will release itself and reinitialize and continue on with the next function. Setting the value to zero will disable the function. On a side note, be careful with setting too low a value because some devices support clock stretching which can increase the time before an acknowledgement is sent which could be misconstrued as a lockup.
If a lock up occurs the returned parameters from Read and/or Writes will contain a 1.
- Parameters:
-
timeOut - uint16_t
The amount of time to wait before timing out. Can range from 0 - 65535 milliseconds. If it's set to 0 it will be disabled. - Returns:
- none
- Description:
- Scans the bus for I2C devices and reports back each 7 bit address to the Serial Monitor. The timeout feature was implemented so if there is a problem with the bus during the scan, it will display on Serial Monitor that there was a problem.
- Parameters:
- none
- Returns:
- none
- Description:
-
Initiate an I2C write operation with no data sent. Typically used to set the "pointer" to a register address
NOTE: For devices with 16-bit register addresses use I2c.write16(address, registerAddress). It is identical except registerAddress is a uint16_t - Parameters:
-
address - uint8_t
The 7 bit I2C slave address -
registerAddress - uint8_t
Address of the register you wish to access (as per the datasheet) - Returns:
-
uint8_t
0: Function executed with no errors
1: Function timed out waiting for successful completion of a Start bit
2: Function timed out waiting for ACK/NACK while addressing slave in transmit mode (MT)
3: Function timed out waiting for ACK/NACK while sending data to the slave
4: Function timed out waiting for successful completion of a Repeated Start
5: Function timed out waiting for ACK/NACK while addressing slave in receiver mode (MR)
6: Function timed out waiting for ACK/NACK while receiving data from the slave
7: Function timed out waiting for successful completion of the Stop bit
8 - 0xFF: See datasheet for exact meaning
- Description:
- Initiate an I2C write operation, sending a single data byte. Typically used to send a single byte of data to a register address
NOTE: For devices with 16-bit register addresses use I2c.write16(address, registerAddress, data). It is identical except registerAddress is a uint16_t - Parameters:
-
address - uint8_t
The 7 bit I2C slave address -
registerAddress - uint8_t
Address of the register you wish to access (as per the datasheet) -
data - uint8_t
A single byte of data to send - Returns:
-
uint8_t
0: Function executed with no errors
1: Function timed out waiting for successful completion of a Start bit
2: Function timed out waiting for ACK/NACK while addressing slave in transmit mode (MT)
3: Function timed out waiting for ACK/NACK while sending data to the slave
4: Function timed out waiting for successful completion of a Repeated Start
5: Function timed out waiting for ACK/NACK while addressing slave in receiver mode (MR)
6: Function timed out waiting for ACK/NACK while receiving data from the slave
7: Function timed out waiting for successful completion of the Stop bit
8 - 0xFF: See datasheet for exact meaning
- Description:
- Initiate an I2C write operation, array of char. Typically used to send an array of char starting at registerAddress location. As a side note there is no restriction on how many bytes may be sent unlike the Wire library which has a 32 byte restriction
NOTE: For devices with 16-bit register addresses use I2c.write16(address, registerAddress, *data). It is identical except registerAddress is a uint16_t - Parameters:
-
address - uint8_t
The 7 bit I2C slave address -
registerAddress - uint8_t
Address of the register you wish to access (as per the datasheet) -
*data - char
Array of characters - Returns:
-
uint8_t
0: Function executed with no errors
1: Function timed out waiting for successful completion of a Start bit
2: Function timed out waiting for ACK/NACK while addressing slave in transmit mode (MT)
3: Function timed out waiting for ACK/NACK while sending data to the slave
4: Function timed out waiting for successful completion of a Repeated Start
5: Function timed out waiting for ACK/NACK while addressing slave in receiver mode (MR)
6: Function timed out waiting for ACK/NACK while receiving data from the slave
7: Function timed out waiting for successful completion of the Stop bit
8 - 0xFF: See datasheet for exact meaning
- Description:
- Initiate an I2C write operation, array of bytes. Typically used to send an array of bytes starting at registerAddress location. As a side note there is no restriction on how many bytes may be sent unlike the Wire library which has a 32 byte restriction
NOTE: For devices with 16-bit register addresses use I2c.write16(address, registerAddress, *data, numberBytes). It is identical except registerAddress is a uint16_t - Parameters:
-
address - uint8_t
The 7 bit I2C slave address -
registerAddress - uint8_t
Address of the register you wish to access (as per the datasheet) -
*data - uint8_t
Array of bytes -
numberBytes - uint8_t
The number of bytes in the array to be sent - Returns:
-
uint8_t
0: Function executed with no errors
1: Function timed out waiting for successful completion of a Start bit
2: Function timed out waiting for ACK/NACK while addressing slave in transmit mode (MT)
3: Function timed out waiting for ACK/NACK while sending data to the slave
4: Function timed out waiting for successful completion of a Repeated Start
5: Function timed out waiting for ACK/NACK while addressing slave in receiver mode (MR)
6: Function timed out waiting for ACK/NACK while receiving data from the slave
7: Function timed out waiting for successful completion of the Stop bit
8 - 0xFF: See datasheet for exact meaning
- Description:
- Initiate a read operation from the current position of slave register pointer. The bytes will be stored in an internal buffer and will have the 32 byte size restriction. Data can be read out of the buffer using I2c.receive().
- Parameters:
-
address - uint8_t
The 7 bit I2C slave address -
numberBytes - uint8_t
The number of bytes to be read - Returns:
-
uint8_t
0: Function executed with no errors
1: Function timed out waiting for successful completion of a Start bit
2: Function timed out waiting for ACK/NACK while addressing slave in transmit mode (MT)
3: Function timed out waiting for ACK/NACK while sending data to the slave
4: Function timed out waiting for successful completion of a Repeated Start
5: Function timed out waiting for ACK/NACK while addressing slave in receiver mode (MR)
6: Function timed out waiting for ACK/NACK while receiving data from the slave
7: Function timed out waiting for successful completion of the Stop bit
8 - 0xFF: See datasheet for exact meaning
Unlike the Wire library the read operation will not return the number of bytes read, instead it will return the error code which can be used for debugging.
- Description:
- Initiate a read operation from the current position of slave register pointer. The bytes will be stored in the dataBuffer. As a side note there is a maximum of 255 bytes that may be received unlike the Wire library which has a 32 byte restriction.
- Parameters:
-
address - uint8_t
The 7 bit I2C slave address -
numberBytes - uint8_t
The number of bytes to be read -
*dataBuffer - uint8_t
Array to store the read data - Returns:
-
uint8_t
0: Function executed with no errors
1: Function timed out waiting for successful completion of a Start bit
2: Function timed out waiting for ACK/NACK while addressing slave in transmit mode (MT)
3: Function timed out waiting for ACK/NACK while sending data to the slave
4: Function timed out waiting for successful completion of a Repeated Start
5: Function timed out waiting for ACK/NACK while addressing slave in receiver mode (MR)
6: Function timed out waiting for ACK/NACK while receiving data from the slave
7: Function timed out waiting for successful completion of the Stop bit
8 - 0xFF: See datasheet for exact meaning
Unlike the Wire library the read operation will not return the number of bytes read, instead it will return the error code which can be used for debugging.
NOTE: For reading more bytes (up to 65535) use I2c.readex(address, numberBytes, *dataBuffer). It is identical except numberBytes is a uint16_t
- Description:
- Initiate a write operation to set the pointer to the registerAddress, then sending a repeated start (not a stop then start) and store the number of bytes in an internal buffer. The 32 byte size restriction is imposed for this function. Data can be read out of the buffer using I2c.receive().
NOTE: For devices with 16-bit register addresses use I2c.read16(address, registerAddress, numberBytes). It is identical except registerAddress is a uint16_t - Parameters:
-
address - uint8_t
The 7 bit I2C slave address -
registerAddress - uint8_t
Starting register address to read data from -
numberBytes - uint8_t
The number of bytes to be read - Returns:
-
uint8_t
0: Function executed with no errors
1: Function timed out waiting for successful completion of a Start bit
2: Function timed out waiting for ACK/NACK while addressing slave in transmit mode (MT)
3: Function timed out waiting for ACK/NACK while sending data to the slave
4: Function timed out waiting for successful completion of a Repeated Start
5: Function timed out waiting for ACK/NACK while addressing slave in receiver mode (MR)
6: Function timed out waiting for ACK/NACK while receiving data from the slave
7: Function timed out waiting for successful completion of the Stop bit
8 - 0xFF: See datasheet for exact meaning
Unlike the Wire library the read operation will not return the number of bytes read, instead it will return the error code which can be used for debugging.
- Description:
- Initiate a write operation to set the pointer to the registerAddress, then sending a repeated start (not a stop then start) and store the number of bytes in the dataBuffer. As a side note there is a maximum of 255 bytes that may be received unlike the Wire library which has a 32 byte restriction.
- Parameters:
-
address - uint8_t
The 7 bit I2C slave address -
registerAddress - uint8_t
Starting register address to read data from -
numberBytes - uint8_t
The number of bytes to be read -
*dataBuffer - uint8_t
An array to store the read data - Returns:
-
uint8_t
0: Function executed with no errors
1: Function timed out waiting for successful completion of a Start bit
2: Function timed out waiting for ACK/NACK while addressing slave in transmit mode (MT)
3: Function timed out waiting for ACK/NACK while sending data to the slave
4: Function timed out waiting for successful completion of a Repeated Start
5: Function timed out waiting for ACK/NACK while addressing slave in receiver mode (MR)
6: Function timed out waiting for ACK/NACK while receiving data from the slave
7: Function timed out waiting for successful completion of the Stop bit
8 - 0xFF: See datasheet for exact meaning
Unlike the Wire library the read operation will not return the number of bytes read, instead it will return the error code which can be used for debugging.
NOTE: For devices with 16-bit register addresses use I2c.read16(address, registerAddress, numberBytes, *dataBuffer). It is identical except registerAddress is a uint16_t
For reading more bytes (up to 65535) use I2c.readex(address, registerAddress, numberBytes, *dataBuffer). It is identical except numberBytes is a uint16_t
- Description:
- Returns the number of unread bytes stored in the internal 32 byte buffer
- Parameters:
- none
- Returns:
-
uint8_t
The number of unread bytes
- Description:
- Returns the first unread byte of the internal buffer.
- Parameters:
- none
- Returns:
-
uint8_t
First unread byte of the internal buffer
- Description:
- Sends out a Start Condition. This puts all slave devices on notice that a transmission is about to start. This function incorporates the timeOut function.
- Parameters:
- none
- Returns:
-
uint8_t
0: The start condition was successfully sent
1: The function timed out
2 - 0xFF: See the datasheet
- Description:
- Sends out the address byte. The address byte's first 7 bits are the 7-bit address of the Slave you wish to communicate with, the last bit specifies if you wish to write or read to that slave, 0 = write & 1 = read.
- Parameters:
-
i2cAddress - uint8_t
The address byte you wish to send - Returns:
-
uint8_t
0: The address byte was successfully sent
1: The function timed out
2 - 0xFF: See the datasheet
- Description:
- Sends out a byte of data to the slave.
- Parameters:
-
i2cData - uint8_t
The data byte you wish to send - Returns:
-
uint8_t
0: The data byte was successfully sent
1: The function timed out
2 - 0xFF: See the datasheet
- Description:
- Receives a byte from the slave. The ack parameter specifies whether or not to send an acknowledge signal after receiving it. If it is the last byte you want to receive it must be 0, so that the slave will stop transmitting and allow the master to send a stop.
- Parameters:
-
ack - uint8_t
Whether or not you want the master to acknowledge the receipt of the data byte. If this is the last byte being received, do not acknowledge.
0: Do not send an ACK signal on receipt
1 - 0xFF: Send an ACK signal on receipt
- Returns:
-
uint8_t
0: The data byte was successfully received
1: The function timed out
2 - 0xFF: See the datasheet
- Description:
- Receives a byte from the slave. The ack parameter specifies whether or not to send an acknowledge signal after receiving it. If it is the last byte you want to receive it must be 0, so that the slave will stop transmitting and allow the master to send a stop.
- Parameters:
-
ack - uint8_t
Whether or not you want the master to acknowledge the receipt of the data byte. If this is the last byte being received, do not acknowledge.
0: Do not send an ACK signal on receipt
1 - 0xFF: Send an ACK signal on receipt
-
*target - uint8_t
A byte to store the received data. - Returns:
-
uint8_t
0: The data byte was successfully received
6: The function timed out
1 - 5 and 7 - 0xFF: See the datasheet
- Description:
- Send out a stop condition
- Parameters:
- none
- Returns:
-
uint8_t
0: The stop condition was successfully sent
1: The function timed out
2 - 0xFF: See the datasheet