I2C

The i2c component provides c++ wrappers / implementation build on ESP-IDF’s i2c drivers.

There are two versions of these drivers, supporting the different driver versions supported in ESP-IDF v5.x.

The two drivers cannot coexist at the same time, so you must select (via kconfig) which driver you want to use.

Legacy API

This driver is deprecated and will no longer be available for ESP-IDF >= v5.5 - so make sure you upgrade.

The I2C class provides a simple interface to the I2C bus. It is a wrapper around the esp-idf I2C driver.

A helper I2cMenu is also provided which can be used to interactively test I2C buses - scanning the bus, probing devices, reading and writing to devices.

API Reference

Header File

Header File

New API

This driver was introduced and has been refined in ESP-IDF v5. As of v5.5, it will be the only driver available.

The I2cMasterBus and I2cMasterDevice classes provide simple interfaces to manage and communicate with I2C peripherals on an I2C bus.

It should be noted that while the new ESP-IDF APIs can support asynchronous mode, these classes do not.

Helper I2cMasterMenu and I2cMasterDeviceMenu are also provided which can be used to interactively test I2C buses - scanning the bus, probing devices, and performing read/write operations with devices.

There are also I2cSlaveDevice and I2cSlaveMenu classes for developing your own I2C Slave device using ESP, though they are not currently tested / used as the upstream ESP-IDF is only recently stabilizing.

API Reference

Header File

Header File

Header File

Header File

Classes

class I2cSlaveDevice : public espp::BaseComponent

I2C Slave Device (C++ wrapper for ESP-IDF new I2C slave API)

This class is a wrapper around the ESP-IDF I2C slave device API. It provides thread-safe, modern C++ access to I2C slave device operations.

Example

Usage:

  • Construct with a config

  • Use read, write, and callback registration methods

  • All methods are thread-safe

Note

This class is intended for use with the new ESP-IDF I2C slave API (>=5.4.0)

Public Types

using RequestCallback = std::function<void(const uint8_t *data, size_t len)>

Callback for data requests.

using ReceiveCallback = std::function<void(const uint8_t *data, size_t len)>

Callback for data received.

Public Functions

explicit I2cSlaveDevice(const Config &config)

Construct I2C Slave Device.

Parameters:

config – Configuration for the device

~I2cSlaveDevice()

Destructor.

bool init(std::error_code &ec)

Initialize the device.

Parameters:

ec – Error code output

Returns:

True if successful

bool deinit(std::error_code &ec)

Deinitialize the device.

Parameters:

ec – Error code output

Returns:

True if successful

bool write(const uint8_t *data, size_t len, std::error_code &ec)

Write data to the master.

Parameters:

  • data – Pointer to data

  • len – Length of data

  • ec – Error code output

Returns:

True if successful

bool read(uint8_t *data, size_t len, std::error_code &ec)

Read data from the master.

Parameters:

  • data – Pointer to buffer

  • len – Length to read

  • ec – Error code output

Returns:

True if successful

bool register_callbacks(const Callbacks &callbacks, std::error_code &ec)

Register callbacks for slave events.

Parameters:

  • callbacks – Callbacks to register

  • ec – Error code output

Returns:

True if successful

const Config &config() const

Expose config for CLI menu.

Returns:

Reference to config

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:

A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:

tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:

The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:

level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:

level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:

The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:

rate_limit – The rate limit to use for the logger

struct Callbacks

Callbacks for I2C slave events.

Public Members

RequestCallback on_request = nullptr

Callback for data request from master.

ReceiveCallback on_receive = nullptr

Callback for data received from master.

struct Config

Configuration for I2C Slave Device.

Public Members

int port = 0

I2C port number.

int sda_io_num = -1

SDA pin.

int scl_io_num = -1

SCL pin.

uint16_t slave_address = 0

I2C slave address.

i2c_addr_bit_len_t addr_bit_len = I2C_ADDR_BIT_LEN_7

Address bit length.

uint32_t clk_speed = 100000

I2C clock speed in hertz.

bool enable_internal_pullup = true

Enable internal pullups.

int intr_priority = 0

Interrupt priority.

Logger::Verbosity log_level = Logger::Verbosity::WARN

Logger verbosity.

Header File