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	write_registers (const I2CRegValue *table, size_t count) const
	Write each register and value of `table` in order, stopping at the first failure.

template<size_t N>
bool	write_registers (const I2CRegValue(&table)[N]) const

bool	check_chip_id (Component *component, uint8_t a_register, uint8_t expected, uint8_t mask=0xFF)
	Read the 8-bit ID at `a_register` and accept it when it matches `expected` in the bits set in `mask`.

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	read_bytes_16_le (uint8_t a_register, uint16_t *data, uint8_t len)
	Read len 16-bit values stored least significant byte first; no conversion is compiled on little-endian hosts.

bool	read_bytes_16_le (uint8_t a_register, int16_t *data, uint8_t len)

bool	read_byte_16_le (uint8_t a_register, uint16_t *data)
	Read a 16-bit value stored least significant byte first.

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

bool	write_byte_16_le (uint8_t a_register, uint16_t data) const
	Write a 16-bit value least significant byte first.

bool	update_register (uint8_t a_register, uint8_t mask, uint8_t value)
	Read a register, replace the bits in `mask` with those of `value` and write it back.

Protected Attributes
I2CBus *	bus_ {nullptr}
	pointer to I2CBus instance

uint8_t	address_ {0x00}
	store the address of the device on the bus

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 144 of file i2c.h.

Constructor & Destructor Documentation

◆ I2CDevice()

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

default

we use the C++ default constructor

Member Function Documentation

◆ check_chip_id()

bool esphome::i2c::I2CDevice::check_chip_id	(	Component *	component,
		uint8_t	a_register,
		uint8_t	expected,
		uint8_t	mask = 0xFF )

inline

Read the 8-bit ID at a_register and accept it when it matches expected in the bits set in mask.

Otherwise mark component failed and return false.

Definition at line 232 of file i2c.h.

◆ 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 155 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 175 of file i2c.h.

◆ read_byte() [1/2]

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

inline

Definition at line 274 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 272 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 281 of file i2c.h.

◆ read_byte_16_le()

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

inline

Read a 16-bit value stored least significant byte first.

Definition at line 296 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 255 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 249 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 70 of file i2c.cpp.

◆ read_bytes_16_le() [1/2]

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

inline

Definition at line 291 of file i2c.h.

◆ read_bytes_16_le() [2/2]

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

inline

Read len 16-bit values stored least significant byte first; no conversion is compiled on little-endian hosts.

Definition at line 284 of file i2c.h.

◆ 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 262 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 253 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 28 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 32 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 164 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 169 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 151 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 159 of file i2c.h.

◆ update_register()

bool esphome::i2c::I2CDevice::update_register	(	uint8_t	a_register,
		uint8_t	mask,
		uint8_t	value )

Read a register, replace the bits in mask with those of value and write it back.

The write always happens; bits of value outside mask are ignored. Logs both values at VERBOSE.

Returns: false if the read or the write failed (nothing is written after a failed read)

Definition at line 78 of file i2c.cpp.

◆ 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 195 of file i2c.h.

◆ write_byte()

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

inline

Definition at line 312 of file i2c.h.

◆ write_byte_16()

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

Definition at line 101 of file i2c.cpp.

◆ write_byte_16_le()

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

Write a 16-bit value least significant byte first.

Definition at line 106 of file i2c.cpp.

◆ 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 306 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 302 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 298 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 87 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 205 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 37 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 46 of file i2c.cpp.

◆ write_registers() [1/2]

bool esphome::i2c::I2CDevice::write_registers	(	const I2CRegValue *	table,
		size_t	count ) const

Write each register and value of table in order, stopping at the first failure.

The table may be in PROGMEM.

Definition at line 56 of file i2c.cpp.

◆ write_registers() [2/2]

template<size_t N>

bool esphome::i2c::I2CDevice::write_registers ( const I2CRegValue(&) table[N] ) const

inline

Definition at line 226 of file i2c.h.

Field Documentation

◆ address_

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

protected

store the address of the device on the bus

Definition at line 327 of file i2c.h.

◆ bus_

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

protected

pointer to I2CBus instance

Definition at line 325 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

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ I2CDevice()

Member Function Documentation

◆ check_chip_id()

◆ get_i2c_address()

◆ read()

◆ read_byte() [1/2]

◆ read_byte() [2/2]

◆ read_byte_16()

◆ read_byte_16_le()

◆ read_bytes() [1/2]

◆ read_bytes() [2/2]

◆ read_bytes_16()

◆ read_bytes_16_le() [1/2]

◆ read_bytes_16_le() [2/2]

◆ read_bytes_raw() [1/2]

◆ read_bytes_raw() [2/2]

◆ read_register()

◆ read_register16()

◆ reg()

◆ reg16()

◆ set_i2c_address()

◆ set_i2c_bus()

◆ update_register()

◆ write()

◆ write_byte()

◆ write_byte_16()

◆ write_byte_16_le()

◆ write_bytes() [1/3]

◆ write_bytes() [2/3]

◆ write_bytes() [3/3]

◆ write_bytes_16()

◆ write_read()

◆ write_register()

◆ write_register16()

◆ write_registers() [1/2]

◆ write_registers() [2/2]

Field Documentation

◆ address_

◆ bus_