esphome::i2c::I2CDevice Class Reference

This Class provides the methods to read/write bytes from/to an i2c device. More...

#include <i2c.h>

Inheritance diagram for esphome::i2c::I2CDevice:

Public Member Functions
	I2CDevice ()=default
	we use the C++ default constructor
void	set_i2c_address (uint8_t address)
	We store the address of the device on the bus.
uint8_t	get_i2c_address () const
	Returns the I2C address of the object.
void	set_i2c_bus (I2CBus *bus)
	we store the pointer to the I2CBus to use
I2CRegister	reg (uint8_t a_register)
	calls the I2CRegister constructor
I2CRegister16	reg16 (uint16_t a_register)
	calls the I2CRegister16 constructor
ErrorCode	read (uint8_t *data, size_t len) const
	reads an array of bytes from the device using an I2CBus
ErrorCode	read_register (uint8_t a_register, uint8_t *data, size_t len)
	reads an array of bytes from a specific register in the I²C device
ErrorCode	read_register16 (uint16_t a_register, uint8_t *data, size_t len)
	reads an array of bytes from a specific register in the I²C device
ErrorCode	write (const uint8_t *data, size_t len) const
	writes an array of bytes to a device using an I2CBus
ErrorCode	write_read (const uint8_t *write_data, size_t write_len, uint8_t *read_data, size_t read_len) const
	writes an array of bytes to a device, then reads an array, as a single transaction
ErrorCode	write_register (uint8_t a_register, const uint8_t *data, size_t len) const
	writes an array of bytes to a specific register in the I²C device
ErrorCode	write_register16 (uint16_t a_register, const uint8_t *data, size_t len) const
	write an array of bytes to a specific register in the I²C device
bool	read_bytes (uint8_t a_register, uint8_t *data, uint8_t len)
	Compat APIs All methods below have been added for compatibility reasons.
bool	read_bytes_raw (uint8_t *data, uint8_t len) const
template<size_t N>
optional< std::array< uint8_t, N > >	read_bytes (uint8_t a_register)
template<size_t N>
optional< std::array< uint8_t, N > >	read_bytes_raw ()
bool	read_bytes_16 (uint8_t a_register, uint16_t *data, uint8_t len)
bool	read_byte (uint8_t a_register, uint8_t *data)
optional< uint8_t >	read_byte (uint8_t a_register)
bool	read_byte_16 (uint8_t a_register, uint16_t *data)
bool	write_bytes (uint8_t a_register, const uint8_t *data, uint8_t len) const
bool	write_bytes (uint8_t a_register, const std::vector< uint8_t > &data) const
template<size_t N>
bool	write_bytes (uint8_t a_register, const std::array< uint8_t, N > &data)
bool	write_bytes_16 (uint8_t a_register, const uint16_t *data, uint8_t len) const
bool	write_byte (uint8_t a_register, uint8_t data) const
bool	write_byte_16 (uint8_t a_register, uint16_t data) const
	ESPDEPRECATED ("The stop argument is no longer used. This will be removed from ESPHome 2026.3.0", "2025.9.0") ErrorCode read_register(uint8_t a_register
	ESPDEPRECATED ("The stop argument is no longer used. This will be removed from ESPHome 2026.3.0", "2025.9.0") ErrorCode read_register16(uint16_t a_register
	ESPDEPRECATED ("The stop argument is no longer used; use write_read() for consecutive write and read. This will be " "removed from ESPHome 2026.3.0", "2025.9.0") ErrorCode write(const uint8_t *data
	ESPDEPRECATED ("The stop argument is no longer used; use write_read() for consecutive write and read. This will be " "removed from ESPHome 2026.3.0", "2025.9.0") ErrorCode write_register(uint8_t a_register
	ESPDEPRECATED ("The stop argument is no longer used; use write_read() for consecutive write and read. This will be " "removed from ESPHome 2026.3.0", "2025.9.0") ErrorCode write_register16(uint16_t a_register

Data Fields
uint8_t *	data
uint8_t size_t	len
uint8_t size_t bool	stop
size_t	len
size_t bool stop	const { return this->write(data, len)
const uint8_t *	data
const uint8_t size_t	len
const uint8_t size_t bool stop	const

Protected Attributes
uint8_t	address_ {0x00}
	store the address of the device on the bus
I2CBus *	bus_ {nullptr}
	pointer to I2CBus instance

Detailed Description

This Class provides the methods to read/write bytes from/to an i2c device.

Objects keep a list of devices found on bus as well as a pointer to the I2CBus in use.

Definition at line 133 of file i2c.h.

Constructor & Destructor Documentation

I2CDevice()

esphome::i2c::I2CDevice::I2CDevice ( )

default

we use the C++ default constructor

Member Function Documentation

ESPDEPRECATED() [1/5]

esphome::i2c::I2CDevice::ESPDEPRECATED	(	"The stop argument is no longer used. This will be removed from ESPHome 2026.3.0"	,
		"2025.9.0"	)

ESPDEPRECATED() [2/5]

esphome::i2c::I2CDevice::ESPDEPRECATED	(	"The stop argument is no longer used. This will be removed from ESPHome 2026.3.0"	,
		"2025.9.0"	)

ESPDEPRECATED() [3/5]

esphome::i2c::I2CDevice::ESPDEPRECATED	(	"The stop argument is no longer used; use write_read() for consecutive write and read. This will be " "removed from ESPHome 2026.3.0"	,
		"2025.9.0"	) const

ESPDEPRECATED() [4/5]

esphome::i2c::I2CDevice::ESPDEPRECATED	(	"The stop argument is no longer used; use write_read() for consecutive write and read. This will be " "removed from ESPHome 2026.3.0"	,
		"2025.9.0"	)

ESPDEPRECATED() [5/5]

esphome::i2c::I2CDevice::ESPDEPRECATED	(	"The stop argument is no longer used; use write_read() for consecutive write and read. This will be " "removed from ESPHome 2026.3.0"	,
		"2025.9.0"	)

get_i2c_address()

uint8_t esphome::i2c::I2CDevice::get_i2c_address ( ) const

inline

Returns the I2C address of the object.

Returns

the I2C address

Definition at line 144 of file i2c.h.

read()

ErrorCode esphome::i2c::I2CDevice::read ( uint8_t * data, size_t len ) const

inline

reads an array of bytes from the device using an I2CBus

Parameters

data	pointer to an array to store the bytes
len	length of the buffer = number of bytes to read

Returns

an i2c::ErrorCode

Definition at line 164 of file i2c.h.

read_byte() [1/2]

optional< uint8_t > esphome::i2c::I2CDevice::read_byte ( uint8_t a_register )

inline

Definition at line 243 of file i2c.h.

read_byte() [2/2]

bool esphome::i2c::I2CDevice::read_byte ( uint8_t a_register, uint8_t * data )

inline

Definition at line 241 of file i2c.h.

read_byte_16()

bool esphome::i2c::I2CDevice::read_byte_16 ( uint8_t a_register, uint16_t * data )

inline

Definition at line 250 of file i2c.h.

read_bytes() [1/2]

template<size_t N>

optional< std::array< uint8_t, N > > esphome::i2c::I2CDevice::read_bytes ( uint8_t a_register )

inline

Definition at line 224 of file i2c.h.

read_bytes() [2/2]

bool esphome::i2c::I2CDevice::read_bytes ( uint8_t a_register, uint8_t * data, uint8_t len )

inline

Compat APIs All methods below have been added for compatibility reasons.

They do not bring any functionality and therefore on new code it is not recommend to use them.

Definition at line 218 of file i2c.h.

read_bytes_16()

bool esphome::i2c::I2CDevice::read_bytes_16	(	uint8_t	a_register,
		uint16_t *	data,
		uint8_t	len )

Definition at line 63 of file i2c.cpp.

read_bytes_raw() [1/2]

template<size_t N>

optional< std::array< uint8_t, N > > esphome::i2c::I2CDevice::read_bytes_raw ( )

inline

Definition at line 231 of file i2c.h.

read_bytes_raw() [2/2]

bool esphome::i2c::I2CDevice::read_bytes_raw ( uint8_t * data, uint8_t len ) const

inline

Definition at line 222 of file i2c.h.

read_register()

ErrorCode esphome::i2c::I2CDevice::read_register	(	uint8_t	a_register,
		uint8_t *	data,
		size_t	len )

reads an array of bytes from a specific register in the I²C device

Parameters

a_register	an 8 bits internal address of the I²C register to read from
data	pointer to an array to store the bytes
len	length of the buffer = number of bytes to read

Returns

an i2c::ErrorCode

Definition at line 35 of file i2c.cpp.

read_register16()

ErrorCode esphome::i2c::I2CDevice::read_register16	(	uint16_t	a_register,
		uint8_t *	data,
		size_t	len )

reads an array of bytes from a specific register in the I²C device

Parameters

a_register	the 16 bits internal address of the I²C register to read from
data	pointer to an array of bytes to store the information
len	length of the buffer = number of bytes to read

Returns

an i2c::ErrorCode

Definition at line 39 of file i2c.cpp.

reg()

I2CRegister esphome::i2c::I2CDevice::reg ( uint8_t a_register )

inline

calls the I2CRegister constructor

Parameters

a_register

address of the I²C register

Returns

an I2CRegister proxy object

Definition at line 153 of file i2c.h.

reg16()

I2CRegister16 esphome::i2c::I2CDevice::reg16 ( uint16_t a_register )

inline

calls the I2CRegister16 constructor

Parameters

a_register

16 bits address of the I²C register

Returns

an I2CRegister16 proxy object

Definition at line 158 of file i2c.h.

set_i2c_address()

void esphome::i2c::I2CDevice::set_i2c_address ( uint8_t address )

inline

We store the address of the device on the bus.

Parameters

address

of the device

Definition at line 140 of file i2c.h.

set_i2c_bus()

void esphome::i2c::I2CDevice::set_i2c_bus ( I2CBus * bus )

inline

we store the pointer to the I2CBus to use

Parameters

bus	pointer to the I2CBus object

Definition at line 148 of file i2c.h.

write()

ErrorCode esphome::i2c::I2CDevice::write ( const uint8_t * data, size_t len ) const

inline

writes an array of bytes to a device using an I2CBus

Parameters

data	pointer to an array that contains the bytes to send
len	length of the buffer = number of bytes to write

Returns

an i2c::ErrorCode

Definition at line 184 of file i2c.h.

write_byte()

bool esphome::i2c::I2CDevice::write_byte ( uint8_t a_register, uint8_t data ) const

inline

Definition at line 266 of file i2c.h.

write_byte_16()

bool esphome::i2c::I2CDevice::write_byte_16 ( uint8_t a_register, uint16_t data ) const

inline

Definition at line 268 of file i2c.h.

write_bytes() [1/3]

template<size_t N>

bool esphome::i2c::I2CDevice::write_bytes ( uint8_t a_register, const std::array< uint8_t, N > & data )

inline

Definition at line 260 of file i2c.h.

write_bytes() [2/3]

bool esphome::i2c::I2CDevice::write_bytes ( uint8_t a_register, const std::vector< uint8_t > & data ) const

inline

Definition at line 256 of file i2c.h.

write_bytes() [3/3]

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

inline

Definition at line 252 of file i2c.h.

write_bytes_16()

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

Definition at line 71 of file i2c.cpp.

write_read()

ErrorCode esphome::i2c::I2CDevice::write_read ( const uint8_t * write_data, size_t write_len, uint8_t * read_data, size_t read_len ) const

inline

writes an array of bytes to a device, then reads an array, as a single transaction

Parameters

write_data	pointer to an array that contains the bytes to send
write_len	length of the buffer = number of bytes to write
read_data	pointer to an array to store the bytes read
read_len	length of the buffer = number of bytes to read

Returns

an i2c::ErrorCode

Definition at line 194 of file i2c.h.

write_register()

ErrorCode esphome::i2c::I2CDevice::write_register	(	uint8_t	a_register,
		const uint8_t *	data,
		size_t	len ) const

writes an array of bytes to a specific register in the I²C device

Parameters

a_register	the internal address of the register to read from
data	pointer to an array to store the bytes
len	length of the buffer = number of bytes to read

Returns

an i2c::ErrorCode

Definition at line 44 of file i2c.cpp.

write_register16()

ErrorCode esphome::i2c::I2CDevice::write_register16	(	uint16_t	a_register,
		const uint8_t *	data,
		size_t	len ) const

write an array of bytes to a specific register in the I²C device

Parameters

a_register	the 16 bits internal address of the register to read from
data	pointer to an array to store the bytes
len	length of the buffer = number of bytes to read

Returns

an i2c::ErrorCode

Definition at line 53 of file i2c.cpp.

Field Documentation

address_

uint8_t esphome::i2c::I2CDevice::address_ {0x00}

protected

store the address of the device on the bus

Definition at line 302 of file i2c.h.

bus_

I2CBus* esphome::i2c::I2CDevice::bus_ {nullptr}

protected

pointer to I2CBus instance

Definition at line 303 of file i2c.h.

const [1/2]

const uint8_t size_t bool stop esphome::i2c::I2CDevice::const { return this->write(data, len)

Definition at line 285 of file i2c.h.

const [2/2]

const uint8_t size_t bool stop esphome::i2c::I2CDevice::const

Initial value:

{
    return this->write_register(a_register, data, len)

Definition at line 290 of file i2c.h.

data [1/2]

const uint8_t * esphome::i2c::I2CDevice::data

Definition at line 273 of file i2c.h.

data [2/2]

const uint8_t* esphome::i2c::I2CDevice::data

Definition at line 290 of file i2c.h.

len [1/3]

const uint8_t size_t esphome::i2c::I2CDevice::len

Definition at line 273 of file i2c.h.

len [2/3]

size_t esphome::i2c::I2CDevice::len

Definition at line 285 of file i2c.h.

len [3/3]

const uint8_t size_t esphome::i2c::I2CDevice::len

Definition at line 290 of file i2c.h.

stop

uint8_t size_t bool esphome::i2c::I2CDevice::stop

Initial value:

{
    return this->read_register(a_register, data, len)

Definition at line 273 of file i2c.h.

---

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

• esphome/components/i2c/i2c.h
• esphome/components/i2c/i2c.cpp