Usage

Using the I2C device library is actually very simple, especially if you're using the Arduino IDE. You can use other development systems, but you'll need to place the library source files in the compiler's include path somewhere, or in your project's relevant source folder.

Installation

  1. Get the latest version of the files library from GitHub using one of these methods:
  2. Extract the archive or copy the contents of the /i2cdevlib/Arduino folder into your Arduino user library folder, or your project's include path. For Arduino installations, this defaults to /Arduino/Libraries inside your main documents/personal folder (e.g. C:\Users\Ender Wiggin\Documents on Windows 7 or /home/enderw/ on Linux). Note that even if you have an Arduino sketch library folder, you may need to manually create a subfolder for user libraries.

    NOTE: Do NOT extract the entire repository directly into your Arduino libraries folder. The repository root contains a collection of ported variants for many different platforms, and putting them all into the Arduino build path will cause compile errors that cannot be fixed.
  3. Arduino IDE only: restart the Arduino IDE if it's running to make sure new libraries are scanned and available in the menu.

Implementation

  1. Make sure the desired I2C implementation is selected in I2Cdev.h This will not likely change between your different projects. The default option is to use the Arduino Wire library, but there are other options if Wire is not available. The NBWire library from Gene Knight is working, but not bug-free when interrupts are in use. I am also in the process of incorporating Francesco Ferrara's FastWire code.
  2. If you're using the Arduino Wire library, make sure you #include "Wire.h" in your main sketch file. The I2Cdev.h header also includes it if necessary, but Arduino's build process requires that your main sketch file have it as well. If you're using other implementations, this is not necessary.
  3. Include whatever device class headers you need for your project, such as ADXL345.h or MPU6050.h. These headers will automatically include I2Cdev.h for you, so don't worry about including that one yourself.
  4. Instantiate and use any devices you want to, and have fun!

Basic Example

Although many of the device libraries also include example code (usually found in the /Examples subfolder inside the device folder), here's a quick example to get you started on your own. This is the same as the ADXL345 "Raw Acceleration Measurements" code (source on GitHub here).

// Arduino Wire library is required if I2Cdev I2CDEV_ARDUINO_WIRE implementation
// is used in I2Cdev.h
#include "Wire.h"

// I2Cdev and ADXL345 must be installed as libraries, or else the .cpp/.h files
// for both classes must be in the include path of your project
#include "ADXL345.h"

// class default I2C address is 0x53
// specific I2C addresses may be passed as a parameter here
// ALT low = 0x53 (default for SparkFun 6DOF board)
// ALT high = 0x1D
ADXL345 accel;

int16_t ax, ay, az;

#define LED_PIN 13 // (Arduino is 13, Teensy is 6)
bool blinkState = false;

void setup() {
    // join I2C bus (I2Cdev library doesn't do this automatically)
    Wire.begin();

    // initialize serial communication
    // (38400 chosen because it works as well at 8MHz as it does at 16MHz, but
    // it's really up to you depending on your project)
    Serial.begin(38400);

    // initialize device
    Serial.println("Initializing I2C devices...");
    accel.initialize();

    // verify connection
    Serial.println("Testing device connections...");
    Serial.println(accel.testConnection() ? "ADXL345 connection successful" : "ADXL345 connection failed");

    // configure LED for output
    pinMode(LED_PIN, OUTPUT);
}

void loop() {
    // read raw accel measurements from device
    accel.getAcceleration(&ax, &ay, &az);

    // display tab-separated accel x/y/z values
    Serial.print("accel:\t");
    Serial.print(ax); Serial.print("\t");
    Serial.print(ay); Serial.print("\t");
    Serial.println(az);

    // blink LED to indicate activity
    blinkState = !blinkState;
    digitalWrite(LED_PIN, blinkState);
}