I²C Bus
This component sets up the I²C bus for your esp32, esp8266, rp2040, nrf52, bk72xx, or host platform. In
order for these components to work correctly, you need to define the I²C bus in your configuration. On ESP32 (both
Arduino and ESP-IDF frameworks), internal pullup resistors are enabled by default. On ESP8266, the internal 10kΩ pullup
resistors are always enabled. External pullups are still recommended for longer wire runs or multiple devices. You can
use multiple devices on one I²C bus as each device is given a unique address for communicating between it and the ESP.
You can do this by hopping wires from the two lines (SDA and SCL) from each device board to the next device board or by
connecting the wires from each device back to the two I²C pins on the ESP.
# Example configuration entry for ESP32i2c: sda: GPIOXX scl: GPIOXX scan: true id: bus_a# Example configuration entry for BK72xxi2c: sda: GPIOXX scl: GPIOXX# Example configuration entry for host platformi2c: device: /dev/i2c-1 scan: trueConfiguration variables
Section titled “Configuration variables”-
id (Optional, ID): Manually specify the ID for this I²C bus if you need multiple I²C buses.
-
scan (Optional, boolean): If ESPHome should do a search of the I²C address space on startup. Defaults to
true. -
frequency (Optional, frequency): Set the frequency the I²C bus should operate on. Defaults to
50kHz(100kHzonbk72xx). Values are10kHz,50kHz,100kHz,200kHz, …800kHz. Onbk72xxthe real clock can be slower, see below.
esp32, esp8266, rp2040, nrf52
Section titled “esp32, esp8266, rp2040, nrf52”-
sda (Optional, Pin): The pin for the data line of the I²C bus. Defaults to the default of your board (usually GPIO21 for ESP32 and GPIO4 for ESP8266).
-
scl (Optional, Pin): The pin for the clock line of the I²C bus. Defaults to the default of your board (usually GPIO22 for ESP32 and GPIO5 for ESP8266).
-
timeout (Optional, Time): Set the I²C bus timeout. Defaults to the framework defaults (
100usonesp32,1sonesp8266and1sonrp2040). Maximum onesp32is 13ms.
esp32 only
Section titled “esp32 only”-
sda_pullup_enabled (Optional, boolean): Enable the internal pullup resistor for the SDA pin. Defaults to
true. -
scl_pullup_enabled (Optional, boolean): Enable the internal pullup resistor for the SCL pin. Defaults to
true. -
low_power_mode (Optional, boolean): Enable the low-power (master only) I²C bus. Only available on ESP32C5, ESP32C6 and ESP32P4. Defaults to
falseunless required.
bk72xx
Section titled “bk72xx”The BK72xx chips do not have an I²C implementation in the Arduino framework, so ESPHome drives the bus in software
on two ordinary GPIO pins (“bit-banging”). Any two GPIO pins can be used; there are no default pins, and inverted
is not supported on them.
-
sda (Required, Pin): The pin for the data line of the I²C bus.
-
scl (Required, Pin): The pin for the clock line of the I²C bus.
-
timeout (Optional, Time): How long a device may hold the clock line low (clock stretching) before the transfer is aborted. Defaults to
1ms.
The internal pullup resistors are enabled while a line is released, but external pullups are still recommended. The bus is driven from the main loop and a transfer blocks it for its duration, so keep the number of bytes per transfer small. The actual clock frequency can be lower than configured because of software overhead.
- device (Required, string): The I²C device path to use (e.g.,
/dev/i2c-0,/dev/i2c-1).
Multiple I²C buses
Section titled “Multiple I²C buses”If the device supports multiple I²C buses, they need to be defined separately and sensors need to be set up specifying the correct bus:
# Example configuration entryi2c: - id: bus_a sda: GPIOXX scl: GPIOXX scan: true - id: bus_b sda: GPIOXX scl: GPIOXX scan: true# Sensors should be specified as followssensor: - platform: bme680 i2c_id: bus_b address: 0x76For I²C multiplexing see Tca9548A.