Arduino and the Two-Wire Interface (TWI/I2C) Including A Short Didactic Parenthetical On Making TWI Work On An Arduino Mini

I have been using the Arduino and Atmel microcontroller’s generally using the SPI (serial-peripheral interface), but decided to look at the two-wire (a.k.a. I2C) interface as well. I’m doing this partially because it would be good to know how it works, but also because it’s electrically more compact. It only uses two-wires, rather than the four required for SPI, so schematic designs and board layouts become a bit more manageable. The trade-off is a little bit more complicated protocols semantics, but nothing out of control. (I’m also looking at using a two-axis accelerometer that’s much less expensive than the three-axis one I’ve been using – $4 versus $15. For some experiments, two-axes may be perfectly fine, and I’m happy to save the $11.)

The first step was making sure the Arduino would handle the TWI – there’s pretty much no reason it shouldn’t, because the Atmega8 certainly handles it. So, the next step was finding out how best to handle TWI transactions.

To do this, I consulted the Atmega8 specification sheet, which has a pretty thorough explanation of the protocol and the implementation details on the Atmega8. (There are also a couple of useful application notes available here and here.) It’s so thorough that I had to print it out. I got a pretty good understanding of how it works but before I started coding, I noticed that there were some TWI libraries both in avrlibc and in the “Wire” library in Wiring.org happens to be packaged as a “sanctioned” external library for Arduino, so that was pretty much that.

Nicholas Zambetti, who wrote the Wire library, pretty much told me it should work with no problems, and he was pretty much right. No problems. His library abstracts the TWI innards really nicely, so I don’t have to muck with any Atmega registers or anything of that sort.

I hooked up my Arduino to a handy accelerometer for testing. (I’m still using the expensive LIS3LV02DQ.) Analog In 4 goes to SDA, and Analog In 5 goes to SCL. I have pull-up resistors on those lines, but Nicolas explains that his library enables the internal pull-ups on the Atmega, so I can probably pull those from my breadboard. Either way, it’s working just fine, even with the external pull-up resistors. (I’m using 4.7k resistors.)

Arduino Mini TWI (I2C)

(I also found in one weird situation that I had to explicitly clear the clock prescaler to get the UART functioning properly. This was while getting TWI working on an AT90USB1287 – TWI worked fine, but the UART was spitting out garbage. On chips where the clock prescaler can be set through the fuses, it’s important to verify that the prescaler isn’t hard wired to divide the clock. This’ll cause anything that is dependent on timing to potentially be off kilter. In my case, the UART was expecting an 8MHz clock to determine timing and baud rate, but the clock was being divided in hardware – not even in the firmware.)

Wire/TWI (I2C) on the Arduino Mini

Getting TWI working on the Arduino Mini (Although the Arduino and Arduino Mini share a name, they don’t share the same processor. The Arduino Mini uses an ATmega168, while the Arduino..normal.. uses an ATmega8. You’ll need to recompile/re-“verify” the Wire library files in order to get TWI to work on the ATmega168/Arduino Mini. There’s a thing or two you’ll have to do by hand to get this to work, and you’ll need to do it each time you move code that’s using the Wire library to a different processor. In other words, when you decide to port the code to the ATmega8, or you put an ATmega16 in your Arduino, or whatever — you’ll need to recompile these libraries. Here’s the drill:

Navigate in a file browser or command prompt to the root of your Arduino file hierarchy. Then go into:

lib/targets/libraries/Wire/
delete Wire.o

lib/targets/libraries/Wire/utility
delete twi.o

Once you’ve done this, make one modification to the header file twi.h in lib/targets/libraries/Wire/utility. Look around line 27 for a commented out line like this:

//#define ATMEGA8

Un-comment it (take out the “//” in the front.) This’ll ensure that the internal pull-up resistors on the ATmega8 are enabled when you’re developing for the normal Arduino. You’ll only need to make this change to twi.h once and for all. Future builds of Arduino should have this fixed.

For those who are curious — pull-up resistors are required on the TWI lines — SCL and SDA. You may use your own external pull-ups, but enabling the internal ones saves you the hassle. But, I don’t think you’ll do much harm if you have the internal one’s enabled and use external ones. But, generally you’ll want to avoid having both internal and external pull-ups.)

Anyway. These modifications described above should get TWI working on the Arduino Mini.)

Here’s the code I wrote and ran:

#include

// TWI (I2C) sketch to communicate with the LIS3LV02DQ accelerometer
// Using the Wire library (created by Nicholas Zambetti)
// http://wiring.org.co/reference/libraries/Wire/index.html
// On the Arduino board, Analog In 4 is SDA, Analog In 5 is SCL
// These correspond to pin 27 (PC4/ADC4/SDA) and pin 28 (PC5/ADC5/SCL) on the Atmega8
// The Wire class handles the TWI transactions, abstracting the nitty-gritty to make
// prototyping easy.

void setup()
{
  pinMode(9, OUTPUT);
  digitalWrite(9, HIGH);
  Serial.begin(9600);

  CLKPR = (1<<clkpce);
  CLKPR = 0;

  Wire.begin(); // join i2c bus (address optional for master)
  Wire.beginTransmission(0x1D);
  Wire.send(0x20); // CTRL_REG1 (20h)
  Wire.send(0x87); // Device on, 40hz, normal mode, all axis's enabled
  Wire.endTransmission();

}

void loop()
{

  byte z_val_l, z_val_h, x_val_l, x_val_h, y_val_l, y_val_h;
  int z_val, x_val, y_val;
  //Serial.println("hello?");
  //byte in_byte;
  // transmit to device with address 0x1D
  // according to the LIS3L* datasheet, the i2c address of is fixed
  // at the factory at 0011101b (0x1D)
  Wire.beginTransmission(0x1D);
  // send the sub address for the register we want to read
  // this is for the OUTZ_H register
  // n.b. supposedly masking the register address with 0x80,
  // you can do multiple reads, with the register address auto-incremented
  Wire.send(0x28);
  // stop transmitting
  Wire.endTransmission();
 // Now do a transfer reading one byte from the LIS3L*
 // This data will be the contents of register 0x28
 Wire.requestFrom(0x1D, 1);
  while(Wire.available())
 {
   x_val_l = Wire.receive();
 }
 Wire.beginTransmission(0x1D); Wire.send(0x29); Wire.endTransmission();
 Wire.requestFrom(0x1D, 1);
 while(Wire.available())
 {
    x_val_h = Wire.receive();
 }
 x_val = x_val_h;
 x_val <<= 8;
 x_val += x_val_l;

 // Y Axis
 Wire.beginTransmission(0x1D); Wire.send(0x2A); Wire.endTransmission();
 Wire.requestFrom(0x1D, 1);
 while(Wire.available())
 {
    y_val_l = Wire.receive();
 }
 Wire.beginTransmission(0x1D); Wire.send(0x2B); Wire.endTransmission();
 Wire.requestFrom(0x1D, 1);
 while(Wire.available())
 {
    y_val_h = Wire.receive();
 }

 y_val = y_val_h;
 y_val <<= 8;
 y_val += y_val_l;

// Z Axis
 Wire.beginTransmission(0x1D); Wire.send(0x2C); Wire.endTransmission();
 Wire.requestFrom(0x1D, 1);
 while(Wire.available())
 {
    z_val_l = Wire.receive();
 }
 Wire.beginTransmission(0x1D); Wire.send(0x2D); Wire.endTransmission();
 Wire.requestFrom(0x1D, 1);
 while(Wire.available())
 {
    z_val_h = Wire.receive();
 }

 z_val = z_val_h;
 z_val <<= 8;
 z_val += z_val_l;
  // Set up to read the next register
  // Supposedly, if you set the most significant bit of
  // the register address to 1, you can do a multiple read,
  // with the register address auto-incrementing. This way, you
  // don't have to do another write — specifying the next register —
  // before reading the next register value. This would be very good, but
  // with a cursory attempt, I have yet to make this work.
/*
    Wire.beginTransmission(0x1D); // transmit to device #4
  Wire.send(0x2C);        // read outx_h
  // stop transmitting
  Wire.endTransmission();
  Wire.requestFrom(0x1D, 1);
 while(Wire.available())
 {
   z_val_l = Wire.receive();
 }

 z_val = z_val_h;
 z_val <<= 8;
 z_val += z_val_l;

  // z axis acceleration, all set.
  // Perfectly still and with the z-axis parallel to the ground, it should be about 1024-ish
  // (I find in practice it is around 1019.)
  // When the z-axis is orthogonal to the ground, it should be zero.
  // 1024 is +1g acceleration, or normal gravity
  // 2048 is +2g
  // 0 is 0g
  Serial.println(z_val, DEC);
*/
Serial.print(x_val, HEX); Serial.print(" ");Serial.print(y_val, HEX); Serial.print(" "); Serial.println(z_val, HEX);
delay(100);
}

Technorati Tags: ,

26 thoughts on “Arduino and the Two-Wire Interface (TWI/I2C) Including A Short Didactic Parenthetical On Making TWI Work On An Arduino Mini”

  1. Julian, thanks for your excellent example of the TWI on the Arduino. It helped me get up and running in no time. I have one question though, I tried to take your example a little further by writing my own I2C code (instead of using the wire library) and to do multiple reads from the accelerometer. However, I cannot get it to work. Did you ever get the multiple read functionality to work? I could swear I’m following the LIS3LV02DQ data sheet to the T.

    Thanks!

  2. Felixe,

    They’re ST Microelectronics’ LIS3LV02DQ, a 3-axis accelerometer with digital outputs.

    I get the break-out boards from Spark Fun Electronics:

    http://tinyurl.com/mfa6g

    They’re not particularly inexpensive — about $15 single quantities for the individual pieces, and $43 on the break-out board.

    Julian

  3. Here is a working example based on the code above that does multiple reads at once for reading all three axis.. I’m using this sketch on an arduino nano.. Thanks for the original example 🙂

    #include <wire.h>

    // TWI (I2C) sketch to communicate with the LIS3LV02DQ accelerometer

    // Using the Wire library (created by Nicholas Zambetti)
    // http://wiring.org.co/reference/libraries/Wire/index.html
    // On the Arduino board, Analog In 4 is SDA, Analog In 5 is SCL
    // These correspond to pin 27 (PC4/ADC4/SDA) and pin 28 (PC5/ADC5/SCL) on the Atmega8
    // The Wire class handles the TWI transactions, abstracting the nitty-gritty to make
    // prototyping easy.

    #define OUTX_L 0x28
    #define OUTX_H 0x29
    #define OUTY_L 0x2A
    #define OUTY_H 0x2B
    #define OUTZ_L 0x2C
    #define OUTZ_H 0x2D

    #define XAXIS 0
    #define YAXIS 1
    #define ZAXIS 2

    void setup() {

    Wire.begin(); // join i2c bus (address optional for master)
    Serial.begin( 9600 );

    Wire.beginTransmission( 0x1D );
    Wire.send( 0x20 ); // CTRL_REG1 ( 20h )

    Wire.send( 0x87 ); // Device on, 40hz, normal mode, all axis’s enabled
    Wire.endTransmission();
    }

    void loop() {

    int val[3];
    // transmit to device with address 0x1D
    // according to the LIS3L* datasheet, the i2c address of is fixed
    // at the factory at 0011101b (0x1D)

    Wire.beginTransmission( 0x1D );
    // send the sub address for the *first* register we want to read
    // this is for the OUTX_L register

    // set the MSB so we can do multiple reads, with the register address auto-incremented
    Wire.send( OUTX_L | 0x80);
    // stop transmitting
    Wire.endTransmission();

    // Now do a transfer reading six bytes from the LIS3L*
    // This data will be the contents of the X Y and Z registers
    Wire.requestFrom( 0x1D, 6 );

    while ( Wire.available() < 6 ) {
    // this isn’t really necessary
    // a better thing to do would be to set up an onReceive handler,
    // buffer the data and go off and do something else if the data isn’t ready
    delay( 5 );
    }

    // read the data
    for ( int i = 0; i < 3; i++ ) {
    // read low byte
    byte low = Wire.receive();
    // read the high byte
    val[i] = ( Wire.receive() << 8 ) + low;
    }

    // do something with the values
    Serial.print( ” x_val = ” );
    Serial.print( val[XAXIS], DEC );
    Serial.print( ” y_val = ” );
    Serial.print( val[YAXIS], DEC );
    Serial.print( ” z_val = ” );
    Serial.println( val[ZAXIS], DEC );

    delay( 250 );
    }

  4. Hi, I’ve had success with the Arduino Diecimila(Atmega168) with the accelerometer quite well.

    A newbie question:

    This time, I’ve got a SFE’s Skinny(Atmega168v, 8MHz) with 3.3v logic level.
    In this case, do I have reflect the changes in the clock speed for the I2C connection?

    Thanks a lot.

    Bryan

    1. Ooh. I haven’t heard of the Skinny, but it sounds quite useful!

      I’m guessing that you don’t need to make any adjustments in the source code. The LilyPad Arduino, which also runs at 8MHz can be specified under the menu item “Tools->Board” — that should compile your code with the correct F_CPU define of 8000000 without you mucking about under the hood.

      1. Thank you, Julian.

        Great, I don’t have to pull my hair out for the source coding adustments!
        The menu item selection will do the job for me! Wow.

        Bryan

      2. Hi, Julian.

        After I’ve received my Skinny, 8MHz clock with 3.3volt logic, from the SFE, I had to solve the problem with the program uploading to the Skinny.
        Since I already had success, using your didactic instructions, with Arduino Diecimila – I2C of LIS3LV02DQ – hooked up to my PC, I did not suspect the poor old FTDI driver. No success even with numerous changing of reset button timings!
        Anyway,long story short, I found the FTDI driver should be updated, and intalled the new one last week. The uploding works great.
        I still have to connect the Accelerometer to my Skinny at 3.3V.
        I understand I’m quite a bit behind schedule.
        My Skinny will be soon connected. 🙂

        Thanks for your help.

        Bryan

  5. Hi Julian

    Thanks for your very informative example 🙂

    I’ve been trying to get a Lilypad to talk to sparkfun’s capacitive sensing module (based on the AD7746) – but i’ve’ got almost nowhere with it!

    Have you any experience with this chip?

    cheers,

    -henry

    1. Hey Henry,

      I’ve never tried this part, but I actually think I have it on a break out board somewhere..just never got to it. I used the AD7150 though, which is also an I2C device. Never really had any particular problems with it.

      Where have you gotten with the AD7746? I can probably help you debug..

      .julian.

    2. Hi Julian,
      i’ve started using AD7150 but finding hard to interface with Arduino
      Do i ve to work on the register of AD7150

  6. hi all

    in all my research on the LIS3LV02DQ for twi/i2c no one mentions that the default for the LIS3LV02DQ is 4 wire. so you have to change this.

    there are 3 registers that have a 8 preferences each. you control the on/off by sending this Wire.send(B11010010); the comments list the presences for CTRL_REG2 in order

    Wire.begin(); // join i2c bus (address optional for master)
    Wire.beginTransmission(0x1D);
    Wire.send(0x21); // // CTRL_REG2 (21h)
    Wire.send(B11010010);

    // B11010010 corresponds to the seetings for below
    //FS bit is used to select Full Scale value. default = 1
    //BDU bit is used to inhibit output registers update default = 1
    //BLE bit is used to select Big Endian or Little Endiandefault = 0
    //BOOT bit is used to refresh the content of internal registers default = 1
    //IEN bit is used to switch the value present on data-ready pad default = 0
    //DRDY bit is used to enable Data-Ready (RDY/INT) default = 0
    //SPI 4/3 wire SIM is ‘0’ (default value) the 4-wire SIM is ‘1’ the 3-wire TWI (I2C)
    //DAS bit permits to decide between 12 bit right justified and 16 bit default = 0

  7. Hey Julian,

    Thanks for posting your experience with the TWI, it definitely helps towards understanding it better. The one thing I don’t recognize in your code are these lines:

    x_val = x_val_h;
    x_val <<= 8;
    x_val += x_val_l;

    Specifically, what the "<<=" operator does and how you're using it. Thanks again for the great example.

    1. That’s a bit shift operator — left shift.

      http://www.lix.polytechnique.fr/~liberti/public/computing/prog/c/C/CONCEPT/bit_shift.html#shift

      Since x_val is a 16 bit variable and it comes out in two pieces (x_val_h and x_val_l, which are each 8 bits) to assemble the full 16 bit variable x_val, we need to sort of cobble it together. First, taking x_val_h and putting it in x_val, so that x_val contains x_val_h in its lower 8 bits. Then, left shift x_val by 8 bits, so x_val_h is now effectively in the high 8 bits of x_val. Then, just adding x_val_l to x_val basically puts x_val_l in the lower 8 bits and the assembly of x_val is done: x_val_h is in the high 8 bits (from 15-8) and x_val_l is in the low 8 bits (from 0-7).

  8. I am looking for a similar i2c connection from a teensy (arduino based at90usb162 or atmega32u2 mcu) to a uBlox GPS receiver (NEO 5Q). Does anyone has experience with that? Or know about a tutorial/example code?

Comments are closed.