esphome::i2c::I2CBus Class Reference

This Class provides the methods to read and write bytes from an I2CBus. More...

#include <i2c_bus.h>

Inheritance diagram for esphome::i2c::I2CBus:

Public Member Functions
virtual	~I2CBus ()=default
virtual ErrorCode	write_readv (uint8_t address, const uint8_t *write_buffer, size_t write_count, uint8_t *read_buffer, size_t read_count)=0
	This virtual method writes bytes to an I2CBus from an array, then reads bytes into an array of ReadBuffer.
ErrorCode	read (uint8_t address, uint8_t *buffer, size_t len)
ErrorCode	write (uint8_t address, const uint8_t *buffer, size_t len, bool stop=true)
	ESPDEPRECATED ("This method is deprecated and will be removed in ESPHome 2026.3.0. Use write_readv() instead.", "2025.9.0") ErrorCode readv(uint8_t address
	for (size_t i=0;i !=count;i++)
	if (err !=ERROR_OK) return err
	for (size_t i=0;i !=count;i++)
	ESPDEPRECATED ("This method is deprecated and will be removed in ESPHome 2026.3.0. Use write_readv() instead.", "2025.9.0") ErrorCode writev(uint8_t address

Data Fields
ReadBuffer *	read_buffers
ReadBuffer size_t	count
SmallBufferWithHeapFallback< 128 >	buffer_alloc
uint8_t *	buffer = buffer_alloc.get(total_len)
auto	err = this->write_readv(address, nullptr, 0, buffer, total_len)
size_t	pos = 0
return	ERROR_OK
const WriteBuffer *	write_buffers
const WriteBuffer size_t	count
const WriteBuffer size_t bool	stop
std::vector< std::pair< uint8_t, bool > >	scan_results_
	array containing scan results
bool	scan_ {false}
	Should we scan ? Can be set in the yaml.

Detailed Description

This Class provides the methods to read and write bytes from an I2CBus.

Note

The I2CBus virtual class follows a Factory design pattern that provides all the interfaces methods required by clients while deferring the actual implementation of these methods to a subclasses. I2C-bus specification and user manual can be found here https://www.nxp.com/docs/en/user-guide/UM10204.pdf and an interesting I²C Application note https://www.nxp.com/docs/en/application-note/AN10216.pdf

Definition at line 60 of file i2c_bus.h.

Constructor & Destructor Documentation

~I2CBus()

virtual esphome::i2c::I2CBus::~I2CBus ( )

virtualdefault

Member Function Documentation

ESPDEPRECATED() [1/2]

esphome::i2c::I2CBus::ESPDEPRECATED	(	"This method is deprecated and will be removed in ESPHome 2026.3.0. Use write_readv() instead."	,
		"2025.9.0"	)

ESPDEPRECATED() [2/2]

esphome::i2c::I2CBus::ESPDEPRECATED	(	"This method is deprecated and will be removed in ESPHome 2026.3.0. Use write_readv() instead."	,
		"2025.9.0"	)

for() [1/2]

esphome::i2c::I2CBus::for ( size_t i = 0; i != count; i++ )

inline

Definition at line 91 of file i2c_bus.h.

for() [2/2]

esphome::i2c::I2CBus::for ( size_t i = 0; i != count; i++ )

inline

Definition at line 102 of file i2c_bus.h.

if()

esphome::i2c::I2CBus::if

(

err !

= ERROR_OK

)

read()

ErrorCode esphome::i2c::I2CBus::read ( uint8_t address, uint8_t * buffer, size_t len )

inline

Definition at line 79 of file i2c_bus.h.

write()

ErrorCode esphome::i2c::I2CBus::write ( uint8_t address, const uint8_t * buffer, size_t len, bool stop = true )

inline

Definition at line 83 of file i2c_bus.h.

write_readv()

virtual ErrorCode esphome::i2c::I2CBus::write_readv ( uint8_t address, const uint8_t * write_buffer, size_t write_count, uint8_t * read_buffer, size_t read_count )

pure virtual

This virtual method writes bytes to an I2CBus from an array, then reads bytes into an array of ReadBuffer.

Parameters

address	address of the I²C device on the i2c bus
write_buffer	pointer to data
write_count	number of bytes to write
read_buffer	pointer to an array to receive data
read_count	number of bytes to read transmission. False will send a restart, keeping the connection active.

Returns

an i2c::ErrorCode

This is a pure virtual method that must be implemented in the subclass.

Implemented in esphome::i2c::ArduinoI2CBus, esphome::i2c::IDFI2CBus, and esphome::tca9548a::TCA9548AChannel.

Field Documentation

buffer

uint8_t* esphome::i2c::I2CBus::buffer = buffer_alloc.get(total_len)

Definition at line 96 of file i2c_bus.h.

buffer_alloc

SmallBufferWithHeapFallback<128> esphome::i2c::I2CBus::buffer_alloc

Definition at line 95 of file i2c_bus.h.

count [1/2]

ReadBuffer size_t esphome::i2c::I2CBus::count

Initial value:

{
    size_t total_len = 0

Definition at line 89 of file i2c_bus.h.

count [2/2]

const WriteBuffer size_t esphome::i2c::I2CBus::count

Definition at line 113 of file i2c_bus.h.

err

auto esphome::i2c::I2CBus::err = this->write_readv(address, nullptr, 0, buffer, total_len)

Definition at line 98 of file i2c_bus.h.

ERROR_OK

return esphome::i2c::I2CBus::ERROR_OK

Definition at line 108 of file i2c_bus.h.

pos

size_t esphome::i2c::I2CBus::pos = 0

Definition at line 101 of file i2c_bus.h.

read_buffers

ReadBuffer* esphome::i2c::I2CBus::read_buffers

Definition at line 89 of file i2c_bus.h.

scan_

bool esphome::i2c::I2CBus::scan_ {false}

Should we scan ? Can be set in the yaml.

Definition at line 136 of file i2c_bus.h.

scan_results_

std::vector<std::pair<uint8_t, bool> > esphome::i2c::I2CBus::scan_results_

array containing scan results

Definition at line 135 of file i2c_bus.h.

stop

const WriteBuffer size_t bool esphome::i2c::I2CBus::stop

Initial value:

= true) {
    size_t total_len = 0;
    for (size_t i = 0; i != count; i++) {
      total_len += write_buffers[i].len;
    }
 
    SmallBufferWithHeapFallback<128> buffer_alloc;  
    uint8_t *buffer = buffer_alloc.get(total_len);
 
    size_t pos = 0;
    for (size_t i = 0; i != count; i++) {
      std::memcpy(buffer + pos, write_buffers[i].data, write_buffers[i].len);
      pos += write_buffers[i].len;
    }
 
    return this->write_readv(address, buffer, total_len, nullptr, 0);
  }
 
 protected:
  
  void i2c_scan_()

Definition at line 113 of file i2c_bus.h.

write_buffers

const WriteBuffer* esphome::i2c::I2CBus::write_buffers

Definition at line 113 of file i2c_bus.h.

---

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

• esphome/components/i2c/i2c_bus.h