Maker tech hub - AI · 3D print · Pi · ESP32 · plus the classic tech archive.

Free ESP32 kit · AI tools directory · Books · Archive

Guide · Intermediate · ESP32

Debugging I²C on ESP32 (Pull-ups, Addresses, Scopes)

Scanner sketches, level shifting, and cable length reality.

Written by

Avery J. Parker

IT veteran, maker educator, and author of Network Ninja, 3D Printing Mastery, and AI Workflow Mastery. Business IT: Diversified Tech Solutions.

In this guide

  • Goal & materials
  • Steps / firmware
  • Troubleshooting
  • AI assist notes
  • Related gear & books

I²C is the default way to connect sensors and displays to an ESP32, and when it works it is effortless. When it does not, you usually get a sensor that is "not found," readings that drop out, or a bus that freezes. Almost every case comes down to wiring, pull-ups, addresses, voltage levels, or cable length. This guide works through them in the order that finds problems fastest.

Know your pins

On classic ESP32 DevKit boards, the Arduino core defaults to SDA on GPIO 21 and SCL on GPIO 22. The ESP32 can route I²C to most GPIOs, and other chips such as the ESP32-S3 and ESP32-C3 use different defaults. Be explicit in code:

Wire.begin(21, 22);        // SDA, SCL
Wire.setClock(100000);     // start at 100 kHz while debugging

Step 1: run a scanner

#include <Wire.h>

void setup() {
  Serial.begin(115200);
  Wire.begin(21, 22);
  Serial.println("Scanning I2C bus...");
  int found = 0;
  for (uint8_t addr = 1; addr < 127; addr++) {
    Wire.beginTransmission(addr);
    uint8_t err = Wire.endTransmission();
    if (err == 0) {
      Serial.printf("Device at 0x%02X\n", addr);
      found++;
    }
  }
  Serial.printf("Done, %d device(s) found\n", found);
}

void loop() {}

Interpret the result:

  • Expected address found: wiring and power are fine; look at your library settings and address.
  • Nothing found: check power, ground, SDA/SCL swap, and pull-ups.
  • Devices at every address, or the scan hangs: a line is stuck low or there is a short.

endTransmission() returns 0 on success; non-zero values indicate errors such as a NACK on the address or a timeout. Printing the code helps distinguish "no device" from "bus problem."

Step 2: addresses and conflicts

I²C uses 7-bit addresses, and libraries often expect you to pass the right one. Check the datasheet or the breakout board's documentation. Common examples: the SHT31 uses 0x44 or 0x45 depending on its address pin, and the SCD41 CO2 sensor uses 0x62. Many sensors have one or two selectable addresses set by a pin or solder jumper.

If two devices share a fixed address, you cannot put both on one bus as-is. Options are a second I²C bus on other pins (the ESP32 has two hardware I²C controllers) or an I²C multiplexer.

Step 3: pull-up resistors

I²C lines are open drain: devices only pull them low, and resistors pull them high. Without pull-ups the bus does not work; with too much pull-up the edges are sharp but devices may struggle to pull the line low.

  • Typical values are 2.2 kΩ to 10 kΩ to 3.3 V, with 4.7 kΩ a common choice for short buses at 100 kHz.
  • Many breakout boards include pull-ups. Several boards on one bus put those resistors in parallel, lowering the total resistance. With many modules, you may need to remove some.
  • The ESP32's internal pull-ups are weak and not a reliable substitute for external resistors.

Step 4: voltage levels

The ESP32 uses 3.3 V logic and its pins are not rated for 5 V. Many breakouts accept 3.3 V or 5 V power, and some pull their I²C lines up to whatever they are powered from. Powering such a board from 5 V puts 5 V on the ESP32's pins. Either power the module from 3.3 V (if it supports it) or use a bidirectional I²C level shifter.

Step 5: cable length and speed

I²C was designed for connections on a circuit board. Long wires add capacitance, which slows the rising edges until the bus stops working. The I²C specification sets a bus capacitance limit for standard and fast modes, and long jumper runs reach it quickly.

  • Keep wires short, and lower the clock to 100 kHz or even less for longer runs.
  • Twisting SDA with ground and SCL with ground, or using a cable with a ground between the signals, reduces crosstalk.
  • Slightly stronger pull-ups (lower resistance) speed up rising edges on longer lines, within the devices' limits.
  • For runs of several meters, use bus extender or differential I²C chips designed for the job, or put a microcontroller near the sensor and send data another way.

Step 6: look at the signals

When the basics check out, measure:

  • Multimeter: idle SDA and SCL should both sit near 3.3 V. A line near 0 V is stuck low.
  • Logic analyzer: inexpensive analyzers with open source software decode I²C, showing addresses, ACK and NACK, and data. This quickly shows a wrong address or a device that stops answering.
  • Oscilloscope: shows edge shape. Slow, rounded rising edges mean too much capacitance or too weak pull-ups.

Common mistakes

SymptomLikely causeFix
Not found on scanSDA/SCL swapped, no ground, no pull-upsCheck wiring and continuity; add pull-ups
Found by scanner, library failsLibrary using a different address or default pinsPass the address and call Wire.begin(sda, scl) first
Works short, fails with longer wiresBus capacitanceShorten, slow the clock, adjust pull-ups
Intermittent freezesNoise from motors or relays, marginal powerSeparate power, route I²C away from motor wiring
Bus stuck after a reset mid-transferA device holding SDA lowPower-cycle the sensor, or clock SCL a few times at startup to release it

Summary

Start with a scanner at 100 kHz on explicitly set pins. If nothing answers, check power, ground, wiring, and pull-ups. If the wrong thing answers, check addresses. If it works on the bench but not in the build, look at voltage levels, cable length, and noise, then use a logic analyzer to see what the bus is really doing.

Related