Arduino library · Core

The Arduino Wire library: talking I2C to sensors and displays

Wire.h is Arduino’s I2C library, and nearly every sensor and display library sits on top of it. I2C uses two shared lines, SDA for data and SCL for the clock, and every chip on the bus has a 7-bit address. The Arduino is the controller: it starts each conversation, names the address, and either sends bytes or asks for some back.

Built in on Mokxi: #include <Wire.h> and it builds, with nothing to install. Free, and no account needed.

What Wire does

A write is three steps: beginTransmission(address) opens a message, write() adds bytes to a 32-byte buffer, and endTransmission() sends it all and returns a status (0 for success, 2 when nobody acknowledged the address). A read is requestFrom(address, count), then read() for each byte that arrived. Register reads usually send the register number first with endTransmission(false), which keeps the bus for a repeated start.

The pins are fixed by the board: A4 and A5 on an Uno or Nano, 20 and 21 on a Mega, 2 and 3 on a Leonardo, GPIO 21 and 22 on a classic ESP32 (and any two pins with Wire.begin(sda, scl) there). The bus needs pull-up resistors, which most breakout boards already carry.

Library Manager nameWire
AuthorArduino
Include#include <Wire.h>
Boardsevery board Mokxi compiles for
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesAccelerometer and gyroscope, MPU6050, Character LCD with I2C backpack

Install it

It builds on every board Mokxi compiles for.

In Mokxi it is built in: #include <Wire.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board it comes with the board package (Arduino), so the Arduino IDE has it as soon as the board is installed: there is nothing to add from the Library Manager.

ESP32-C3 · Arduino Uno · Arduino Nano · Arduino Mega 2560 · Arduino Leonardo · SparkFun Pro Micro · Arduino Micro · ESP32-C6 · ATtiny85 · Raspberry Pi Pico · Raspberry Pi Pico W · Seeed XIAO SAMD21 · STM32 · STM32 Nucleo-F411RE · STM32 Blue Pill · micro:bit V2 · Arduino Uno R4 · ESP32 DevKit · ESP32-S3-DevKitC-1 · ESP8266 NodeMCU · Arduino Pro Mini 3.3 V · Seeed XIAO ESP32-C3 · ESP32-C3 SuperMini · Seeed XIAO ESP32-C6 · ESP32-DevKitC V4 · LOLIN32 Lite · Wemos D1 R32 · Cheap Yellow Display · TTGO T-Display · Seeed XIAO ESP32-S3 · Arduino Nano ESP32 · Arduino Nano RP2040 Connect · Seeed XIAO RP2040 · Waveshare RP2040-Zero · Arduino Uno R4 WiFi

The calls you will use

In the order a sketch meets them.

Wire.begin()

Joins the bus as the controller on the board’s standard SDA and SCL pins. Call it once in setup().

Wire.begin(21, 22)

The ESP32 form: SDA and SCL on the GPIOs you name.

Wire.setClock(400000)

Sets the bus speed. 100 kHz is the default; 400 kHz is fast mode, which most sensors and OLEDs accept.

Wire.beginTransmission(0x68)

Starts a message to the device at that address. Nothing is sent yet.

Wire.write(0x3B)

Adds a byte (often a register number) to the message buffer.

Wire.endTransmission()

Sends the message and returns 0 on success, 2 if the address was not acknowledged, 3 if a data byte was not. endTransmission(false) holds the bus for a repeated start.

Wire.beginTransmission(0x68);
Wire.write(0x3B);
byte status = Wire.endTransmission(false);
if (status != 0) Serial.println("no answer");

Wire.requestFrom(0x68, 6)

Reads up to 6 bytes from the device into the receive buffer and returns how many came.

Wire.available()

How many received bytes are waiting. read() takes them one at a time.

Wire.requestFrom(0x68, 2);
int16_t ax = (Wire.read() << 8) | Wire.read();

Example: ADXL345 accelerometer on I2C

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
// An ADXL345 accelerometer, read with nothing but Wire.
//
//   ADXL345 SDA -> A4   SCL -> A5   VCC -> 5V   GND -> GND   CS -> 3.3V
//
// The chip answers at address 0x53. Writing 0x08 to its power register
// (0x2D) starts it measuring; then six bytes from 0x32 are X, Y and Z, each
// a 16-bit number, low byte first.
//
// Drag the board to tip it.

#include <Wire.h>

const int ADDRESS = 0x53;

void writeRegister(byte reg, byte value) {
  Wire.beginTransmission(ADDRESS);
  Wire.write(reg);
  Wire.write(value);
  Wire.endTransmission();
}

void setup() {
  Serial.begin(9600);
  Wire.begin();
  writeRegister(0x2D, 0x08);
  Serial.println("Mokxi Uno: ADXL345 on A4 and A5");
}

void loop() {
  Wire.beginTransmission(ADDRESS);
  Wire.write(0x32);
  Wire.endTransmission();
  Wire.requestFrom(ADDRESS, 6);
  int axes[3];
  for (int i = 0; i < 3; i++) {
    byte low = Wire.read();
    byte high = Wire.read();
    axes[i] = (int)((high << 8) | low);
  }
  Serial.print("x ");
  Serial.print(axes[0]);
  Serial.print("  y ");
  Serial.print(axes[1]);
  Serial.print("  z ");
  Serial.println(axes[2]);
  delay(300);
}

Open it in the editor, wired and ready to run · ADXL345 accelerometer on I2C: the project page

Common errors and how to fix them

'Wire' was not declared in this scope

Add #include <Wire.h> at the top of the sketch. Some libraries include it for you, but a sketch that calls Wire itself has to include it too.

endTransmission() returns 2 and the device never answers

The address is wrong or the device is not on the bus. Run an I2C scanner to see which addresses answer, then check SDA and SCL are on the board’s I2C pins (not swapped) and that the module has power and ground.

The sketch freezes inside a Wire call

A missing pull-up or a shorted line can hold SDA or SCL low forever. Check the module’s pull-up resistors and wiring; on recent AVR cores, Wire.setWireTimeout() makes a stuck transfer give up instead of hanging.

Two I2C modules work alone but not together

They share an address. Many modules have a solder jumper or an ADDR pin to move one of them; otherwise use a second bus or an I2C multiplexer such as the TCA9548A.

Questions and answers

Do I need pull-up resistors?

I2C needs them on SDA and SCL, usually 4.7k to 10k to the logic supply. Almost every breakout board already has them, so with one or two modules you rarely add your own.

Try Wire without installing anything

Open the example, change the sketch, and keep your version in a free account.