I2CComponent

To make i2c devices easier to implement in esphomelib, there’s a special I2CComponent implementing a bunch of i2c helper functions on top of the Arduino Wire library. It is also the preferred way of using i2c peripherals since it implements timeouts, verbose logs for debugging issues, and for the ESP32 the ability to have multiple i2c busses in operation at the same time.

API Reference

class I2CComponent : public Component

The I2CComponent is the base of esphomelib’s i2c communication.

It handles setting up the bus (with pins, clock frequency) and provides nice helper functions to make reading from the i2c bus easier (see read_bytes, write_bytes) and safe (with read timeouts).

For the user, it has a few setters (see set_sda_pin, set_scl_pin, set_frequency) to setup some parameters for the bus. Additionally, the i2c component has a scan feature that will scan the entire 7-bit i2c address range for devices that respond to transmissions to make finding the address of an i2c device easier.

On the ESP32, you can even have multiple I2C bus for communication, simply create multiple I2CComponents, each with different SDA and SCL pins and use set_parent on all I2CDevices that use the non-first I2C bus.

Public Functions

I2CComponent(uint8_t sda_pin, uint8_t scl_pin, bool scan = false)
void set_sda_pin(uint8_t sda_pin)

Set the i2c SDA pin for this bus.

void set_scl_pin(uint8_t scl_pin)

Set the i2c SCL pin for this bus.

void set_frequency(uint32_t frequency)

Set the i2c clock frequency in Hz for this bus, defaults to 1000 Hz.

void set_scan(bool scan)

Set if a scan of the entire i2c address range should be done on startup.

bool read_bytes(uint8_t address, uint8_t register_, uint8_t *data, uint8_t len, uint32_t conversion = 0)

Read len amount of bytes from a register into data.

Optionally with a conversion time after writing the register value to the bus.

Return
If the operation was successful.
Parameters
  • address: The address to send the request to.
  • register_: The register number to write to the bus before reading.
  • data: An array to store len amount of 8-bit bytes into.
  • len: The amount of bytes to request and write into data.
  • conversion: The time in ms between writing the register value and reading out the value.

bool read_bytes_16(uint8_t address, uint8_t register_, uint16_t *data, uint8_t len, uint32_t conversion = 0)

Read len amount of 16-bit words (MSB first) from a register into data.

Return
If the operation was successful.
Parameters
  • address: The address to send the request to.
  • register_: The register number to write to the bus before reading.
  • data: An array to store len amount of 16-bit words into.
  • len: The amount of 16-bit words to request and write into data.
  • conversion: The time in ms between writing the register value and reading out the value.

bool read_byte(uint8_t address, uint8_t register_, uint8_t *data, uint32_t conversion = 0)

Read a single byte from a register into the data variable. Return true if successful.

bool read_byte_16(uint8_t address, uint8_t register_, uint16_t *data, uint32_t conversion = 0)

Read a single 16-bit words (MSB first) from a register into the data variable. Return true if successful.

bool write_bytes(uint8_t address, uint8_t register_, const uint8_t *data, uint8_t len)

Write len amount of 8-bit bytes to the specified register for address.

Return
If the operation was successful.
Parameters
  • address: The address to use for the transmission.
  • register_: The register to write the values to.
  • data: An array from which len bytes of data will be written to the bus.
  • len: The amount of bytes to write to the bus.

bool write_bytes_16(uint8_t address, uint8_t register_, const uint16_t *data, uint8_t len)

Write len amount of 16-bit words (MSB first) to the specified register for address.

Return
If the operation was successful.
Parameters
  • address: The address to use for the transmission.
  • register_: The register to write the values to.
  • data: An array from which len 16-bit words of data will be written to the bus.
  • len: The amount of bytes to write to the bus.

bool write_byte(uint8_t address, uint8_t register_, uint8_t data)

Write a single byte of data into the specified register of address. Return true if successful.

bool write_byte_16(uint8_t address, uint8_t register_, uint16_t data)

Write a single 16-bit word of data into the specified register of address. Return true if successful.

void begin_transmission_(uint8_t address)

Begin a write transmission to an address.

bool end_transmission_(uint8_t address)

End a write transmission to an address, return true if successful.

bool request_from_(uint8_t address, uint8_t len)

Request data from an address with a number of (8-bit) bytes.

Return
True if all requested bytes were read, false otherwise.
Parameters
  • address: The address to request the bytes from.
  • len: The number of bytes to receive, must not be 0.

void HOT I2CComponent::write_(uint8_t address, const uint8_t * data, uint8_t len)

Write len amount of bytes from data to address. begin_transmission_ must be called before this.

void HOT I2CComponent::write_16_(uint8_t address, const uint16_t * data, uint8_t len)

Write len amount of 16-bit words from data to address. begin_transmission_ must be called before this.

bool receive_(uint8_t address, uint8_t *data, uint8_t len)

Request len amount of bytes from address and write the result it into data. Returns true iff was successful.

bool receive_16_(uint8_t address, uint16_t *data, uint8_t len)

Request len amount of 16-bit words from address and write the result into data. Returns true iff was successful.

void setup()

Setup the i2c. bus.

void dump_config()
float get_setup_priority() const

Set a very high setup priority to make sure it’s loaded before all other hardware.

Protected Attributes

TwoWire *wire_
uint8_t sda_pin_
uint8_t scl_pin_
bool scan_
uint32_t frequency_ = {1000}
class I2CDevice

All components doing communication on the I2C bus should subclass I2CDevice.

This class stores 1. the address of the i2c device and has a helper function to allow users to manually set the address and 2. stores a reference to the “parent” I2CComponent.

All this class basically does is to expose all helper functions from I2CComponent.

Subclassed by display::I2CSSD1306, display::PCF8574LCDDisplay, io::PCF8574Component, output::PCA9685OutputComponent, sensor::ADS1115Component, sensor::BH1750Sensor, sensor::BME280Component, sensor::BME680Component, sensor::BMP085Component, sensor::BMP280Component, sensor::DHT12Component, sensor::HDC1080Component, sensor::HMC5883LComponent, sensor::HTU21DComponent, sensor::INA219Component, sensor::INA3221Component, sensor::MPU6050Component, sensor::MS5611Component, sensor::SHT3XDComponent, sensor::TCS34725Component, sensor::TSL2561Sensor

Public Functions

I2CDevice(I2CComponent *parent, uint8_t address)
void set_address(uint8_t address)

Manually set the i2c address of this device.

void set_parent(I2CComponent *parent)

Manually set the parent i2c bus for this device.

Protected Functions

bool read_bytes(uint8_t register_, uint8_t *data, uint8_t len, uint32_t conversion = 0)

Read len amount of bytes from a register into data.

Optionally with a conversion time after writing the register value to the bus.

Return
If the operation was successful.
Parameters
  • register_: The register number to write to the bus before reading.
  • data: An array to store len amount of 8-bit bytes into.
  • len: The amount of bytes to request and write into data.
  • conversion: The time in ms between writing the register value and reading out the value.

bool read_bytes_16(uint8_t register_, uint16_t *data, uint8_t len, uint32_t conversion = 0)

Read len amount of 16-bit words (MSB first) from a register into data.

Return
If the operation was successful.
Parameters
  • register_: The register number to write to the bus before reading.
  • data: An array to store len amount of 16-bit words into.
  • len: The amount of 16-bit words to request and write into data.
  • conversion: The time in ms between writing the register value and reading out the value.

bool read_byte(uint8_t register_, uint8_t *data, uint32_t conversion = 0)

Read a single byte from a register into the data variable. Return true if successful.

bool read_byte_16(uint8_t register_, uint16_t *data, uint32_t conversion = 0)

Read a single 16-bit words (MSB first) from a register into the data variable. Return true if successful.

bool write_bytes(uint8_t register_, const uint8_t *data, uint8_t len)

Write len amount of 8-bit bytes to the specified register.

Return
If the operation was successful.
Parameters
  • register_: The register to write the values to.
  • data: An array from which len bytes of data will be written to the bus.
  • len: The amount of bytes to write to the bus.

bool write_bytes_16(uint8_t register_, const uint16_t *data, uint8_t len)

Write len amount of 16-bit words (MSB first) to the specified register.

Return
If the operation was successful.
Parameters
  • register_: The register to write the values to.
  • data: An array from which len 16-bit words of data will be written to the bus.
  • len: The amount of bytes to write to the bus.

bool write_byte(uint8_t register_, uint8_t data)

Write a single byte of data into the specified register. Return true if successful.

bool write_byte_16(uint8_t register_, uint16_t data)

Write a single 16-bit word of data into the specified register. Return true if successful.

Protected Attributes

uint8_t address_
I2CComponent *parent_