Skip to content

Latest commit

 

History

History
546 lines (457 loc) · 20.3 KB

README.md

File metadata and controls

546 lines (457 loc) · 20.3 KB
Raw

Arduino I2C master library

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)

Pro tip

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

Documentation

I2c.begin()

Description:
Enables the I2C hardware
Parameters:
none
Returns:
none

I2c.end()

Description:
Disables the I2C hardware
Parameters:
none
Returns:
none

I2c.setSpeed(fast)

Description:
Enables high speed mode (400kHz)
Parameters:
fast - Boolean
True: High Speed
False: Low Speed
Returns:
none

I2c.pullup(activate)

Description:
Enables/disables internal pullup resistors
Parameters:
activate - Boolean
True: Enable internal pullup resistors (default)
False: Disable internal pullup resistors
Returns:
none

I2c.timeOut(timeOut)

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

I2c.scan()

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

I2c.write(address, registerAddress)

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

I2c.write(address, registerAddress, data)

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

I2c.write(address, registerAddress, *data)

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

I2c.write(address, registerAddress, *data, numberBytes)

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

I2c.read(address, numberBytes)

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.

I2c.read(address, numberBytes, *dataBuffer)

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.


NOTE: For reading more bytes (up to 65535) use I2c.readex(address, numberBytes, *dataBuffer). It is identical except numberBytes is a uint16_t
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.

I2c.read(address, registerAddress, numberBytes)

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.

I2c.read(address, registerAddress, numberBytes, *dataBuffer)

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.


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
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.

I2c.available()

Description:
Returns the number of unread bytes stored in the internal 32 byte buffer
Parameters:
none
Returns:
uint8_t
The number of unread bytes

I2c.receive()

Description:
Returns the first unread byte of the internal buffer.
Parameters:
none
Returns:
uint8_t
First unread byte of the internal buffer

Low-level methods

I2c._start()

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

I2c._sendAddress(i2cAddress)

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

I2c._sendByte(i2cData)

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

I2c._receiveByte(ack)

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

I2c._receiveByte(ack, *target)

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

I2c._stop()

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