skip navigational linksPJRC
Shopping Cart Checkout Shipping Cost Download Website
Home Products Teensy Blog Forum
You are here: Teensy Teensyduino Libraries Wire

PJRC Store
Teensy 3.6, $29.25
Teensy 3.5, $24.25
Teensy 3.2, $19.80
Teensy LC, $11.65
Teensy 2.0, $16.00
Teensy++ 2.0, $24.00
Teensy
Main Page
Hardware
Getting Started
How-To Tips
Code Library
Projects
Teensyduino
Reference

Wire Library

The Wire library allows you to communicate with I2C devices, often also called "2 wire" or "TWI" (Two Wire Interface).

Download: Wire is included with Arduino

Brian "nox771" has written an improved I2C library for Teensy 3.0.

Hardware Requirements

I2C devices communicate with 2 signals, called SDA and SCL. Normally a 4.7K pullup resistor is connected between each signal and power (+3.3V on Teensy 3.0, +5V on Teensy 2.0). On Teensy 2.0, the weak internal pullup resistors may be sufficient for short wires to a single device. Because the internal resistors are so weak, communication may be slower or unreliable if the wires are long.

SignalTeensy 2.0Teensy++ 2.0Teensy LCTeensy 3.0 - 3.6
SCLPin 5Pin 0Pin 19Pin 19
SDAPin 6Pin 1Pin 18Pin 18

Teensy LC & 3.0-3.6 requires pullup resistors to +3.3V. The on-chip pullups are not used. 4.7K resistors are recommended for most applications.

The Wire library is not compatible with Teensy 1.0.

Basic Usage

Wire.begin()

Begin using Wire in master mode, where you will initiate and control data transfers. This is the most common use when interfacing with most I2C peripheral chips.

Wire.begin(address)

Begin using Wire in slave mode, where you will respond at "address" when other I2C masters chips initiate communication.

Transmitting

Wire.beginTransmission(address)

Start a new transmission to a device at "address". Master mode is used.

Wire.write(data)

Send data. In master mode, beginTransmission must be called first.

Wire.endTransmission()

In master mode, this ends the transmission and causes all buffered data to be sent.

Receiving

Wire.requestFrom(address, count)

Read "count" bytes from a device at "address". Master mode is used.

Wire.available()

Retuns the number of bytes available by calling receive.

Wire.read()

Receive 1 byte.

Pin Configuration (Teensy LC & 3.x Only)

Wire.setSDA(pin)

Configure the pin used for data. Possible alternate pins are shown on the pinout card. This function may be called before or after Wire.begin(). All pins used must have real pullup resistors.

Wire.setSCL(pin)

Configure the pin used for clock. Possible alternate pins are shown on the pinout card. This function may be called before or after Wire.begin(). All pins used must have real pullup resistors.

Responding in Slave Mode

Wire.OnReceive(myReceiveHandlerFunction)

Causes "myReceiveHandlerFunction" to be called when a master device sends data. This only works in slave mode.

Wire.OnRequest(myRequestHandlerFunction)

Causes "myRequestHandlerFunction" to be called when a master device wishes to read data. This only works in slave mode.

Example Program

This simple example uses a 24C256 I2C EEPROM. The first byte is read, incremented, and written back.

#include <Wire.h>

void setup() 
{
  Wire.begin();
  Serial.begin(9600);
}

void loop() 
{
  byte num=0;
  
  // set the 24C256 eeprom address to 0
  Wire.beginTransmission(80);
  Wire.write(0);  // address low byte
  Wire.write(0);  // address high byte
  Wire.endTransmission();
  
  // read 1 byte, from address 0
  Wire.requestFrom(80, 1);
  while(Wire.read()) {
    num = Wire.receive();
  }
  Serial.print("num = ");
  Serial.println(num, DEC);
  
  // increment num
  num = num + 1;
  
  // write "num" to 24C256 eeprom at address zero
  Wire.beginTransmission(80);
  Wire.write(0);    // address low byte
  Wire.write(0);    // address high byte
  Wire.write(num);  // any more send starts writing
  Wire.endTransmission();
  
  // next time loop runs, it should retrieve the
  // same number it wrote last time... even if you
  // shut off the power
  delay(5000);
}

Using Addresses

Many datasheets will document I2C addresses as 8 bit numbers including a R/W bit. Here is an excerpt from the AT24C256B datasheet, the chip used in the example above.

The Wire library requires addresses which do not include the R/W bit. Based only on the datasheet, you might conclude the address is 160 when writing and 161 when reading. The Wire library needs address 80 to communicate with this chip. The R/W bit is automatically created based on your use of the send or receive functions.

More Details

Please refer to the official Wire library documentation for more details.