ESPHome  1.15.1
Public Member Functions | Protected Attributes
esphome::i2c::I2CComponent Class Reference

The I2CComponent is the base of ESPHome's i2c communication. More...

#include <i2c.h>

Inheritance diagram for esphome::i2c::I2CComponent:
esphome::Component

Public Member Functions

 I2CComponent ()
 
void set_sda_pin (uint8_t sda_pin)
 
void set_scl_pin (uint8_t scl_pin)
 
void set_frequency (uint32_t frequency)
 
void set_scan (bool scan)
 
bool read_bytes (uint8_t address, uint8_t a_register, uint8_t *data, uint8_t len, uint32_t conversion=0)
 Read len amount of bytes from a register into data. More...
 
bool read_bytes_raw (uint8_t address, uint8_t *data, uint8_t len)
 
bool read_bytes_16 (uint8_t address, uint8_t a_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. More...
 
bool read_byte (uint8_t address, uint8_t a_register, uint8_t *data, uint32_t conversion=0)
 Read a single byte from a register into the data variable. Return true if successful. More...
 
bool read_byte_16 (uint8_t address, uint8_t a_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. More...
 
bool write_bytes (uint8_t address, uint8_t a_register, const uint8_t *data, uint8_t len)
 Write len amount of 8-bit bytes to the specified register for address. More...
 
bool write_bytes_raw (uint8_t address, const uint8_t *data, uint8_t len)
 
bool write_bytes_16 (uint8_t address, uint8_t a_register, const uint16_t *data, uint8_t len)
 Write len amount of 16-bit words (MSB first) to the specified register for address. More...
 
bool write_byte (uint8_t address, uint8_t a_register, uint8_t data)
 Write a single byte of data into the specified register of address. Return true if successful. More...
 
bool write_byte_16 (uint8_t address, uint8_t a_register, uint16_t data)
 Write a single 16-bit word of data into the specified register of address. Return true if successful. More...
 
void raw_begin_transmission (uint8_t address)
 Begin a write transmission to an address. More...
 
bool raw_end_transmission (uint8_t address)
 End a write transmission to an address, return true if successful. More...
 
bool raw_request_from (uint8_t address, uint8_t len)
 Request data from an address with a number of (8-bit) bytes. More...
 
void raw_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. More...
 
void raw_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. More...
 
bool raw_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. More...
 
bool raw_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. More...
 
void setup () override
 Setup the i2c. bus. More...
 
void dump_config () override
 
float get_setup_priority () const override
 Set a very high setup priority to make sure it's loaded before all other hardware. More...
 
- Public Member Functions inherited from esphome::Component
virtual void loop ()
 This method will be called repeatedly. More...
 
float get_actual_setup_priority () const
 
void set_setup_priority (float priority)
 
virtual float get_loop_priority () const
 priority of loop(). More...
 
void call ()
 
virtual void on_shutdown ()
 
virtual void on_safe_shutdown ()
 
uint32_t get_component_state () const
 
virtual void mark_failed ()
 Mark this component as failed. More...
 
bool is_failed ()
 
virtual bool can_proceed ()
 
bool status_has_warning ()
 
bool status_has_error ()
 
void status_set_warning ()
 
void status_set_error ()
 
void status_clear_warning ()
 
void status_clear_error ()
 
void status_momentary_warning (const std::string &name, uint32_t length=5000)
 
void status_momentary_error (const std::string &name, uint32_t length=5000)
 
bool has_overridden_loop () const
 

Protected Attributes

TwoWire * wire_
 
uint8_t sda_pin_
 
uint8_t scl_pin_
 
uint32_t frequency_
 
bool scan_
 
- Protected Attributes inherited from esphome::Component
uint32_t component_state_ {0x0000}
 State of this component. More...
 
float setup_priority_override_ {NAN}
 

Additional Inherited Members

- Protected Member Functions inherited from esphome::Component
virtual void call_loop ()
 
virtual void call_setup ()
 
void set_interval (const std::string &name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a unique name. More...
 
void set_interval (uint32_t interval, std::function< void()> &&f)
 
bool cancel_interval (const std::string &name)
 Cancel an interval function. More...
 
void set_timeout (uint32_t timeout, std::function< void()> &&f)
 
void set_timeout (const std::string &name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a unique name. More...
 
bool cancel_timeout (const std::string &name)
 Cancel a timeout function. More...
 
void defer (const std::string &name, std::function< void()> &&f)
 Defer a callback to the next loop() call. More...
 
void defer (std::function< void()> &&f)
 Defer a callback to the next loop() call. More...
 
bool cancel_defer (const std::string &name)
 Cancel a defer callback using the specified name, name must not be empty. More...
 

Detailed Description

The I2CComponent is the base of ESPHome'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.

Definition at line 26 of file i2c.h.

Constructor & Destructor Documentation

◆ I2CComponent()

esphome::i2c::I2CComponent::I2CComponent ( )

Definition at line 11 of file i2c.cpp.

Member Function Documentation

◆ dump_config()

void esphome::i2c::I2CComponent::dump_config ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 27 of file i2c.cpp.

◆ get_setup_priority()

float esphome::i2c::I2CComponent::get_setup_priority ( ) const
overridevirtual

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

Reimplemented from esphome::Component.

Definition at line 53 of file i2c.cpp.

◆ raw_begin_transmission()

void esphome::i2c::I2CComponent::raw_begin_transmission ( uint8_t  address)

Begin a write transmission to an address.

Definition at line 55 of file i2c.cpp.

◆ raw_end_transmission()

bool esphome::i2c::I2CComponent::raw_end_transmission ( uint8_t  address)

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

Definition at line 59 of file i2c.cpp.

◆ raw_receive()

bool esphome::i2c::I2CComponent::raw_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.

Definition at line 108 of file i2c.cpp.

◆ raw_receive_16()

bool esphome::i2c::I2CComponent::raw_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.

Definition at line 118 of file i2c.cpp.

◆ raw_request_from()

bool esphome::i2c::I2CComponent::raw_request_from ( uint8_t  address,
uint8_t  len 
)

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

Parameters
addressThe address to request the bytes from.
lenThe number of bytes to receive, must not be 0.
Returns
True if all requested bytes were read, false otherwise.

Definition at line 82 of file i2c.cpp.

◆ raw_write()

void HOT esphome::i2c::I2CComponent::raw_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.

Definition at line 91 of file i2c.cpp.

◆ raw_write_16()

void HOT esphome::i2c::I2CComponent::raw_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.

Definition at line 98 of file i2c.cpp.

◆ read_byte()

bool esphome::i2c::I2CComponent::read_byte ( uint8_t  address,
uint8_t  a_register,
uint8_t *  data,
uint32_t  conversion = 0 
)

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

Definition at line 150 of file i2c.cpp.

◆ read_byte_16()

bool esphome::i2c::I2CComponent::read_byte_16 ( uint8_t  address,
uint8_t  a_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.

Definition at line 153 of file i2c.cpp.

◆ read_bytes()

bool esphome::i2c::I2CComponent::read_bytes ( uint8_t  address,
uint8_t  a_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.

Parameters
addressThe address to send the request to.
a_registerThe register number to write to the bus before reading.
dataAn array to store len amount of 8-bit bytes into.
lenThe amount of bytes to request and write into data.
conversionThe time in ms between writing the register value and reading out the value.
Returns
If the operation was successful.

Definition at line 130 of file i2c.cpp.

◆ read_bytes_16()

bool esphome::i2c::I2CComponent::read_bytes_16 ( uint8_t  address,
uint8_t  a_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.

Parameters
addressThe address to send the request to.
a_registerThe register number to write to the bus before reading.
dataAn array to store len amount of 16-bit words into.
lenThe amount of 16-bit words to request and write into data.
conversionThe time in ms between writing the register value and reading out the value.
Returns
If the operation was successful.

Definition at line 141 of file i2c.cpp.

◆ read_bytes_raw()

bool esphome::i2c::I2CComponent::read_bytes_raw ( uint8_t  address,
uint8_t *  data,
uint8_t  len 
)

Definition at line 138 of file i2c.cpp.

◆ set_frequency()

void esphome::i2c::I2CComponent::set_frequency ( uint32_t  frequency)
inline

Definition at line 31 of file i2c.h.

◆ set_scan()

void esphome::i2c::I2CComponent::set_scan ( bool  scan)
inline

Definition at line 32 of file i2c.h.

◆ set_scl_pin()

void esphome::i2c::I2CComponent::set_scl_pin ( uint8_t  scl_pin)
inline

Definition at line 30 of file i2c.h.

◆ set_sda_pin()

void esphome::i2c::I2CComponent::set_sda_pin ( uint8_t  sda_pin)
inline

Definition at line 29 of file i2c.h.

◆ setup()

void esphome::i2c::I2CComponent::setup ( )
overridevirtual

Setup the i2c. bus.

Reimplemented from esphome::Component.

Definition at line 23 of file i2c.cpp.

◆ write_byte()

bool esphome::i2c::I2CComponent::write_byte ( uint8_t  address,
uint8_t  a_register,
uint8_t  data 
)

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

Definition at line 173 of file i2c.cpp.

◆ write_byte_16()

bool esphome::i2c::I2CComponent::write_byte_16 ( uint8_t  address,
uint8_t  a_register,
uint16_t  data 
)

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

Definition at line 176 of file i2c.cpp.

◆ write_bytes()

bool esphome::i2c::I2CComponent::write_bytes ( uint8_t  address,
uint8_t  a_register,
const uint8_t *  data,
uint8_t  len 
)

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

Parameters
addressThe address to use for the transmission.
a_registerThe register to write the values to.
dataAn array from which len bytes of data will be written to the bus.
lenThe amount of bytes to write to the bus.
Returns
If the operation was successful.

Definition at line 156 of file i2c.cpp.

◆ write_bytes_16()

bool esphome::i2c::I2CComponent::write_bytes_16 ( uint8_t  address,
uint8_t  a_register,
const uint16_t *  data,
uint8_t  len 
)

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

Parameters
addressThe address to use for the transmission.
a_registerThe register to write the values to.
dataAn array from which len 16-bit words of data will be written to the bus.
lenThe amount of bytes to write to the bus.
Returns
If the operation was successful.

Definition at line 167 of file i2c.cpp.

◆ write_bytes_raw()

bool esphome::i2c::I2CComponent::write_bytes_raw ( uint8_t  address,
const uint8_t *  data,
uint8_t  len 
)

Definition at line 162 of file i2c.cpp.

Field Documentation

◆ frequency_

uint32_t esphome::i2c::I2CComponent::frequency_
protected

Definition at line 129 of file i2c.h.

◆ scan_

bool esphome::i2c::I2CComponent::scan_
protected

Definition at line 130 of file i2c.h.

◆ scl_pin_

uint8_t esphome::i2c::I2CComponent::scl_pin_
protected

Definition at line 128 of file i2c.h.

◆ sda_pin_

uint8_t esphome::i2c::I2CComponent::sda_pin_
protected

Definition at line 127 of file i2c.h.

◆ wire_

TwoWire* esphome::i2c::I2CComponent::wire_
protected

Definition at line 126 of file i2c.h.


The documentation for this class was generated from the following files: