Open the editorEditor
Arduino library 路 Communication

i2cdetect: print every I2C address that answers

i2cdetect, by Mike Causer, is a one-function library that does what the Linux command of the same name does: it walks the I2C bus, asks each address whether anyone is there, and prints a grid of the ones that answered. Sixteen addresses a row, the hex address where a device acknowledged and -- where none did.

Open the example in the editorSee the calls

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

What i2cdetect does

It is the first thing to run when a new module will not respond. Most "begin() failed" and "device not found" problems turn out to be an address that is not what the tutorial said: an OLED at 0x3D instead of 0x3C, an LCD backpack at 0x3F instead of 0x27, or a BME280 at 0x76 rather than 0x77. One scan shows the real address, or shows that nothing is on the bus at all, which points at wiring or power.

The library uses Wire for the bus, so the scan runs on the board鈥檚 standard SDA and SCL pins unless the sketch called Wire.begin() with others first.

Library Manager namei2cdetect
AuthorMike Causer
Include#include <i2cdetect.h>
Boardsevery board Mokxi compiles for
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesPressure, humidity and temperature, BME280

Install it

It builds on every board Mokxi compiles for.

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

On a real board, install "i2cdetect" by Mike Causer from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add i2cdetect to lib_deps in PlatformIO. Mokxi follows the calls of release 1.0.0, so a sketch written here builds there too.

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()

Starts I2C before the scan. Pass pins first on an ESP32 if the bus is not on the default ones.

Serial.begin(9600)

The table is printed to Serial, so start it and open the Serial Monitor at the same rate.

i2cdetect()

Scans addresses 0x03 to 0x77 and prints the table.

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

i2cdetect(0x20, 0x27)

Scans only a range, here the eight addresses a PCF8574 backpack can be set to.

Wire.endTransmission()

What the scan relies on for each address: 0 means a device acknowledged, anything else means nobody did. A hand-written scanner checks the same value.

Example: The i2cdetect table of an OLED and a BME280

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

sketch.ino 路 Arduino Uno R3
#include <Wire.h>
#include <i2cdetect.h>

void setup() {
  Wire.begin();
  Serial.begin(9600);
  Serial.println("i2cdetect example\n");
  i2cdetect();  // default range from 0x03 to 0x77
}

void loop() {}

Wiring

  • Arduino Uno R3 A4 to OLED display, 128x64 SDA
  • Arduino Uno R3 A5 to OLED display, 128x64 SCL
  • Arduino Uno R3 5V to OLED display, 128x64 VCC
  • Arduino Uno R3 GND to OLED display, 128x64 GND
  • Arduino Uno R3 A4 to Pressure, humidity and temperature, BME280 SDA
  • Arduino Uno R3 A5 to Pressure, humidity and temperature, BME280 SCL
  • Arduino Uno R3 5V to Pressure, humidity and temperature, BME280 VIN
  • Arduino Uno R3 GND to Pressure, humidity and temperature, BME280 GND

Open it in the editor, wired and ready to run

Common errors and how to fix them

The table is all -- with no addresses

Nothing on the bus answered. Check that SDA and SCL go to the board鈥檚 I2C pins (A4 and A5 on an Uno) and are not swapped, that the module has power and ground, and that there are pull-ups on the lines.

The Serial Monitor shows nothing, or unreadable characters

Open the Serial Monitor at the same baud rate the sketch passes to Serial.begin(). The scan runs once in setup(), so press reset after opening the monitor if you missed it.

The scan finds an address, but the library for the module still fails

Pass the address the scan found to the module library鈥檚 begin() or constructor. Many libraries default to one address and a module wired with its jumper or ADDR pin changed answers at another.

Keep going

Learn

Parts

More communication libraries

Every built-in library 路 Open the editor

Try i2cdetect without installing anything

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

Start building free
Open the editor