I²C Address Conflicts, Explained

An I²C sensor that ESPHome cannot find is rarely a dead part. It is usually one of four things: the YAML is looking at the wrong address, another part is already answering on that address, the bus is electrically out of spec, or the wiring never reached the chip. This guide starts with the boot log, which tells you which of those you have. It then covers the four ways to get parts that share an address onto one ESP32: re-strap one, give it a second bus, put a TCA9548A multiplexer in front of it, or move its address in software. The examples are ESPHome YAML, and the electrical sections apply to Arduino sketches unchanged. If you only want a combination checked, the pin & address conflict planner does it for the 49 parts whose addresses are on record here.

Start with the bus scan

ESPHome's i2c: block declares a bus: two pins, and optionally an id and a speed. With scanning on, which is the default, the node probes every ordinary address from 0x08 to 0x77 at start-up and records which ones answer. Write scan: true anyway, so whoever reads the YAML next knows the log will carry the results.

i2c:
  id: i2c_main
  sda: GPIO21
  scl: GPIO22
  scan: true

The results are printed with the rest of the configuration under the i2c tag:

Results from bus scan:
Found device at address 0x44
Found device at address 0x76

You do not have to catch the boot over USB. When a log viewer connects, it asks the node to print its configuration again, and the stored scan results come with it.

Every address in that list is a chip that acknowledged when called. A chip that does not acknowledge (a NACK, in I²C terms) is simply missing from the list. No error is printed, so a missing sensor is a quiet gap rather than a red line. The red line comes later, from the sensor's own component: a Communication failed message, and a line in the configuration dump saying the component is marked FAILED.

What the scan is telling you

One part in this index never shows up in a scan, however well it is wired. The AS3935 lightning sensor breakout ships at 0x03, below the range ESPHome probes, because the I²C specification reserves 0x00–0x07. For that part, the component's own log is the only check.

Why addresses collide

A 7-bit address allows 128 values. The I²C specification (NXP UM10204) reserves eight at each end, 0x00–0x07 and 0x78–0x7F, for the general call, 10-bit addressing and other bus-level uses. That leaves 112 for parts. Manufacturers choose from that range independently and tend to reuse an address across a family: Bosch's pressure sensors sit at 0x76 or 0x77, and Sensirion's SHT3x and SHT4x humidity sensors at 0x44. So parts from different makers, doing unrelated jobs, can ship on the same address. Two of the same part always do.

Fixed, strappable, or movable in software

Whether a clash costs you a solder jumper or extra hardware depends on how each part's address is set. There are three kinds, and every part on an I²C device page here says which it is.

• Strappable. One or more address pins, read by the chip, select from a small set (the glossary calls this address strapping). The names vary by maker: ADDR on the BH1750 and several TI parts, SDO on Bosch sensors, AD0 on the MPU6050, A0–A2 on IO expanders and the TCA9548A. A0–A2 are plain binary, so three pins give eight addresses. Some single pins do more. The OPT3001 and ADS1115 read whether ADDR is tied to ground, supply, SDA or SCL, and get four addresses from one pin.
• Fixed. No address pins. The address is set in the silicon, and two of the same fixed part cannot share a bus, whatever you do.
• Movable in software. The VL53L0X boots at 0x29 and accepts a new address over the bus, which it forgets at power-off. The MLX90614 stores a new address in its EEPROM.

Tie address pins to something. A floating pin can read differently from one power-up to the next. The OPT3001 samples its ADDR pin on every transaction, so a loose strap can change its address while it runs. Breakout makers also pre-strap: Adafruit's BME688 board ships at 0x77, while the BMP280 module documented here is strapped to 0x76, and ESPHome's BMP280 platform assumes 0x77 unless the YAML says otherwise. The scan settles which you have.

Address pins on the parts in this index

Fixed at one address, 21 of the 49 parts on record: QMC5883L 0x0D, VEML7700 0x10, PMSA003I 0x12, HMC5883L 0x1E, PN532 0x24, HYT271 0x28, TCS34725 0x29, TSL2591 0x29, MAX17043 0x36, AHT10 0x38, AHT20 0x38, APDS9960 0x39, HDC1080 0x40, HTU21D 0x40, SHT40 0x44, LTR390 0x53, SGP30 0x58, SCD30 0x61, SCD41 0x62, SEN55 0x69, SPS30 0x69.

The crowded addresses in this index

Group the parts documented here by the address they boot at, and 13 addresses have more than one claimant. At 4 of them, two or more of the parts are fixed. No strap can separate those; the rest resolve with a jumper and an address: line. Every combination below is one someone could realistically order for a single build.

A strap only stretches so far. A part with one address pin gets two addresses, so two BME280s share a bus happily and a third needs a bus or a multiplexer channel of its own. Count how many of a part you intend to fit before counting on its strap.

Way out 1: re-strap one part

If either part in a clash is strappable, move it. On a breakout that usually means bridging or cutting a solder jumper, or wiring an address pin to ground or 3.3V, then adding a matching address: line to that sensor's YAML. Check where the part lands. An SHT31 strapped away from 0x44 moves to 0x45, which is also one of the OPT3001's addresses. With a Sensirion sensor on the bus, the OPT3001 is better strapped to SDA or SCL (0x46 or 0x47). Re-scan after every change.

Way out 2: a second bus

An address only has to be unique on its own bus. ESPHome lets you declare several buses as a list, each with its own id and pins, and each sensor names its bus with i2c_id. Once there is more than one bus, give every I²C component an i2c_id, so none of them depends on which bus ESPHome would pick. Here two SHT40s, fixed at 0x44, each get a bus to themselves:

i2c:
  - id: bus_a
    sda: GPIO21
    scl: GPIO22
  - id: bus_b
    sda: GPIO32
    scl: GPIO33

sensor:
  - platform: sht4x
    i2c_id: bus_a
    temperature:
      name: "Bedroom Temperature"
    humidity:
      name: "Bedroom Humidity"
  - platform: sht4x
    i2c_id: bus_b
    temperature:
      name: "Loft Temperature"
    humidity:
      name: "Loft Humidity"

How many buses you get depends on the chip. ESPHome checks the number of hardware I²C controllers and rejects a configuration that declares more buses than that:

On the ESP32, any output-capable GPIO can carry SDA or SCL, so the second bus needs no special pins. Keep the bus off the strapping pins (GPIO0, 2, 5, 12 and 15) if you can. The pull-ups hold those pins high at the moment the chip reads them to decide how to boot. The ESP32 vs ESP8266 guide covers the other pin limits. In Arduino, the equivalent is Wire.begin(sda, scl) for the first bus and Wire1 on chips with a second controller. Many sensor libraries accept the bus as an argument to their own begin().

Way out 3: a TCA9548A multiplexer

When the clashing parts are identical and fixed, or there are more of them than buses, use a TCA9548A. It sits on the bus at its own address and connects the main bus to any of eight downstream channels, and it powers up with every channel off. ESPHome's tca9548a component turns each channel into a bus of its own:

tca9548a:
  - address: 0x70
    id: mux0
    i2c_id: i2c_main
    channels:
      - bus_id: mux0_ch0
        channel: 0
      - bus_id: mux0_ch1
        channel: 1

sensor:
  - platform: sht4x
    i2c_id: mux0_ch0
    temperature:
      name: "Kitchen Temperature"
    humidity:
      name: "Kitchen Humidity"
  - platform: sht4x
    i2c_id: mux0_ch1
    temperature:
      name: "Pantry Temperature"
    humidity:
      name: "Pantry Humidity"

Each sensor points its i2c_id at a channel's bus_id. Before every read or write, ESPHome selects that channel, and afterwards it switches all channels off again. Identical parts on different channels therefore never see each other's traffic. Parts that do not clash can stay on the main bus beside the multiplexer. What follows from the TI datasheet and from how the component works:

• The boot scan covers the main bus. It shows the multiplexer at 0x70, not the sensors behind it. Check those in their components' logs.
• Every channel needs its own pull-ups. Most sensor breakouts bring them. A bare chip on a channel has none.
• Channels can run at different voltages. The chip runs from 1.65V to 5.5V and never passes a high level above what its supply allows. Powered from 3.3V, it can serve a channel pulled up to 5V while the ESP32 side stays at 3.3V.
• Mind its own address. A0–A2 move it from 0x70 to 0x77, and BME680, BME280, BMP280, BME688, BMP388, BMP390, DPS310 already default to 0x76 or 0x77. Leave it at 0x70 unless you are fitting several multiplexers.
• Channels split capacitance. With one channel selected at a time, a long bus spread over channels behaves like several short ones.
• Tie RESET high. The pin can clear a channel stuck low without cutting power, but ESPHome's component does not drive it, and the datasheet asks for a pull-up.

It runs at up to 400kHz. On a single-controller chip like the ESP32-C3, it is the only way to separate identical fixed-address parts. The IO expansion category lists it alongside the expanders it is often confused with.

Way out 4: move the address in software

The VL53L0X time-of-flight sensor has a pin that makes this possible. XSHUT holds the chip in reset. Give each sensor's XSHUT a GPIO, name it as enable_pin, and ESPHome uses those pins to bring each sensor up on its own and write its new address. The vl53l0x component requires an enable_pin for any address other than 0x29. The chip forgets the address at power-off, so the sequence runs at every boot.

sensor:
  - platform: vl53l0x
    name: "Left Distance"
    address: 0x30
    enable_pin: GPIO18
  - platform: vl53l0x
    name: "Right Distance"
    address: 0x31
    enable_pin: GPIO19

Pick addresses nothing else on the bus uses, and check the scan afterwards. The trick does not transfer to every part at 0x29. The TCS34725 and TSL2591 share that address but have no reset pin to hold them off the bus, so for them the choice is a second bus or a multiplexer. The MLX90614 keeps its new address in EEPROM, so the change is made once rather than at every boot.

Pull-ups: the fault that looks like a clash

I²C lines are open-drain. Chips only ever pull SDA and SCL low, and a resistor to the supply pulls them back up. Too weak a pull-up and the line rises too slowly to read as high in time. Too strong and a chip cannot pull it low enough. Either way reads fail and parts drop in and out of the scan, which looks just like an address fault.

The ESPHome i2c component turns on the ESP32's internal pull-ups by default, and the ESP8266's are always on. Both are weak. Espressif's I²C documentation calls the internal ones too weak for a fast bus. It recommends external resistors between 1kΩ and 10kΩ, with 2–5kΩ as the usual choice.

Those external resistors are usually already there, on the breakouts, and that is the catch with several boards on one bus: their pull-ups add in parallel. Three boards with 10kΩ each make about 3.3kΩ, which is fine. Six boards with 4.7kΩ each make under 800Ω. That is below the specification's floor at 3.3V, about 1kΩ, set by a chip having to hold the line at 0.4V while sinking 3mA. The ceiling depends on capacitance: the resistance must not exceed the allowed rise time divided by 0.8473 times the bus capacitance. At 200pF that is about 5.9kΩ for Standard-mode (up to 100kbit/s) and 1.8kΩ for Fast-mode (400kbit/s). If parts scan fine one at a time but not together, count the resistors and remove some. The board's schematic shows which ones they are, and some boards provide a jumper to disconnect them.

5V pull-ups on a 3.3V ESP32

A breakout without its own regulator pulls SDA and SCL up to whatever feeds its VIN pin. Feed it 5V and the ESP32's pins sit at 5V, and Espressif gives 3.6V as the limit for its GPIOs. Power such boards from 3V3 whenever the part runs at 3.3V. Boards with a regulator and on-board level shifting, as some Adafruit breakouts have, can take 5V safely. Check the schematic rather than the silkscreen.

Level shifting 5V parts

A few parts need 5V to run, and the DS1307 real-time clock in this index is one. The usual fix is the bidirectional shifter described in application note AN10441. It uses one N-channel MOSFET per line: gate to 3.3V, source to the 3.3V side, drain to the 5V side, and pull-ups on each side to that side's supply. When nothing pulls low, the MOSFET is off and each side rests at its own voltage. When a chip on either side pulls low, the MOSFET conducts and the other side follows it down. The circuit is rated for Standard-mode and Fast-mode buses. If a TCA9548A is on the bus anyway, one of its channels does the same job.

Speed, cable length and capacitance

ESPHome runs I²C at 50kHz unless frequency: says otherwise. The ESP32's controller is specified to 400kHz, the TCA9548A also stops at 400kHz, and every part on the bus must be rated for the speed you choose. Going faster buys little for sensors read once a minute, and going slower buys margin.

The specification sets no maximum length. It sets a maximum capacitance of 400pF per line for Standard-mode and Fast-mode, and cable length is how you spend it. Each chip's pins can add up to 10pF, and wire adds capacitance for every centimetre. Short runs inside one enclosure are comfortably within budget; runs to another room are where buses give out. When a bus has to be long, try these in roughly this order:

1. Lower frequency:. 10kHz is a valid setting, and a slower clock gives a slow-rising edge longer to reach a valid high.
2. Fit stronger pull-ups, staying within the limits above.
3. In ribbon cable longer than 10cm, run ground (and ideally supply) between SDA and SCL, as the specification recommends, to cut crosstalk.
4. Split the parts across TCA9548A channels, so no one segment carries the whole load.
5. Add a bus buffer such as NXP's PCA9517, which divides the bus into segments that each stay under 400pF.

Clock stretching and stuck buses

Some chips pause a transfer by holding SCL low until they are ready. The specification calls this clock stretching. It is optional, most parts cannot do it, and controllers wait only so long. ESPHome's timeout: option sets that wait. On the ESP8266 it becomes the software I²C's clock-stretch limit, and on the ESP32 it is capped at 13ms. Change it only when a part's datasheet says it stretches and its reads fail.

A different failure holds SDA low indefinitely. A common cause is the ESP32 resetting in the middle of a read, leaving a sensor part-way through sending a byte. The specification's remedy is nine clock pulses, then a hardware reset or a power cycle if the line is still low. ESPHome tries a recovery when the bus starts, and the configuration dump says so if it failed. At that point, remove power from the sensors. A Bosch BMP280 has its own reason to need a power cycle: if its CSB pin is ever pulled low, it switches off I²C until power is removed.

Debugging checklist

1. Read the scan. Is the address present, absent, or not the one you expected? Each points to a different fix above.
2. Set every address: line from the scan, not from the datasheet.
3. With several parts, disconnect all but one, then add them back one at a time. A part that vanishes when another joins shares its address or overloads the pull-ups.
4. Run the parts through the planner for clashes already on record.
5. Count the pull-ups on the bus, and measure SDA and SCL with nothing happening: both should sit at 3.3V.
6. On long wires, drop frequency: to 10kHz before changing anything else.
7. If the log reports a line held low, power-cycle the sensors as well as the ESP32.