I2C 

See also

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

See also

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

See also

See also

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

See also

See also

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

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 Config

Configuration for I2C.

Public Members

int isr_core_id = -1: The core to install the I2C interrupt on. If -1, then the I2C interrupt is installed on the core that this constructor is called on. If 0 or 1, then the I2C interrupt is installed on the specified core.

i2c_port_t port = I2C_NUM_0: I2C port.

gpio_num_t sda_io_num = GPIO_NUM_NC: SDA pin.

gpio_num_t scl_io_num = GPIO_NUM_NC: SCL pin.

gpio_pullup_t sda_pullup_en = GPIO_PULLUP_DISABLE: SDA pullup.

gpio_pullup_t scl_pullup_en = GPIO_PULLUP_DISABLE: SCL pullup.

uint32_t timeout_ms = 10: I2C timeout in milliseconds.

uint32_t clk_speed = 400 * 1000: I2C clock speed in hertz.

bool auto_init = true: Automatically initialize I2C on construction.

espp::Logger::Verbosity log_level = espp::Logger::Verbosity::WARN : Verbosity of logger.

Header File

components/i2c/include/i2c_menu.hpp

Classes

class I2cMenu

A CLI menu for interacting with an I2c bus.

This class provides a CLI menu for interacting with an I2c bus. It provides options for setting the log verbosity, scanning the bus for devices, probing for a device at a specific address, reading from a device, and writing to a device.

Example

    espp::I2c i2c({
        .port = I2C_NUM_0,
        .sda_io_num = (gpio_num_t)CONFIG_EXAMPLE_I2C_SDA_GPIO,
        .scl_io_num = (gpio_num_t)CONFIG_EXAMPLE_I2C_SCL_GPIO,
        .sda_pullup_en = GPIO_PULLUP_ENABLE,
        .scl_pullup_en = GPIO_PULLUP_ENABLE,
        .clk_speed = CONFIG_EXAMPLE_I2C_CLOCK_SPEED_HZ,
        .log_level = espp::Logger::Verbosity::INFO,
    });
    // now make a menu for it
    espp::I2cMenu i2c_menu(i2c);
    cli::Cli cli(i2c_menu.get());
    cli::SetColor();
    cli.ExitAction([](auto &out) { out << "Goodbye and thanks for all the fish.\n"; });
    espp::Cli input(cli);
    input.SetInputHistorySize(10);

    input.Start();

Public Functions

inline explicit I2cMenu(std::reference_wrapper<espp::I2c> i2c)

Construct a new I2cMenu object.

Parameters:: i2c – A reference to the I2c bus to interact with.

inline std::unique_ptr<cli::Menu> get(std::string_view name = "i2c", std::string_view description = "I2c menu")

Get the I2c menu.

Parameters:

name – The name of the menu.
description – The description of the menu.

Returns:

A unique pointer to the I2c menu that you can use to add to a CLI.

New API

This driver was introduced and has been refined in ESP-IDF v5. As of v6.0, 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.

I2C Example
- How to use example
  - Hardware Required
  - Build and Flash
- Example Output

API Reference

Header File

components/i2c/include/i2c_master.hpp

Classes

template<typename RegisterType = uint8_t> class I2cMasterDevice : public espp::BaseComponent 

I2C Master Device (C++ wrapper for ESP-IDF new I2C master API)

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

Create a device

    // Create a device (using uint8_t as the size for its register addresses)
    auto dev = bus.add_device<uint8_t>(
        espp::I2cMasterDevice<uint8_t>::Config{
            .device_address = CONFIG_EXAMPLE_I2C_DEVICE_ADDR,
            .scl_speed_hz = CONFIG_EXAMPLE_I2C_CLOCK_SPEED_HZ,
            .log_level = espp::Logger::Verbosity::DEBUG,
        },
        ec);
    if (!dev) {
      logger.error("[NEW API] Failed to add device: {}", ec.message());
      return;
    }
    logger.info("[NEW API] Created device with address {:#02x}", dev->get_device_address());

Read from a device

    static constexpr uint8_t device_address = CONFIG_EXAMPLE_I2C_DEVICE_ADDR;
    static constexpr uint8_t register_address = CONFIG_EXAMPLE_I2C_DEVICE_REG_ADDR;
    bool device_found = bus.probe(device_address, ec);
    if (device_found) {
      logger.info("Found device with address {:#02x}", device_address);
      std::vector<uint8_t> read_data(CONFIG_EXAMPLE_I2C_DEVICE_REG_SIZE, 0);
      bool success = dev->read_register(register_address, read_data, ec);
      if (success) {
        logger.info("read data: {::#02x}", read_data);
      } else {
        logger.error("read failed");
      }
    } else {
      logger.error("Could not find device with address {:#02x}", device_address);
    }

Usage:

Construct with a bus handle and config
Use read, write, write_read, and register-based access methods
Use probe() to check for device presence
All methods are thread-safe

Note

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

Public Functions

explicit I2cMasterDevice(i2c_master_bus_handle_t bus_handle, const Config &config)

Construct I2C Master Device.

Parameters:

bus_handle – I2C master bus handle
config – Configuration for the device

~I2cMasterDevice(): 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

inline int get_timeout_ms() const: Get the configured timeout (ms)

inline void set_timeout_ms(int timeout_ms): Set the timeout (ms)

inline uint16_t get_device_address() const

Get the device address.

Returns:: Device address (7-bit or 10-bit)

void set_device_address(uint16_t device_address, i2c_addr_bit_len_t addr_bit_len = I2C_ADDR_BIT_LEN_7)

Set the device address.

Parameters:

device_address – Device address (7-bit or 10-bit)
addr_bit_len – Address bit length (default is 7-bit)

bool probe(std::error_code &ec)

Probe for the device on the bus.

Parameters:: ec – Error code output
Returns:: True if device responds

bool probe(int32_t timeout_ms, std::error_code &ec)

Probe for the device with a custom timeout.

Parameters:

timeout_ms – Timeout in ms
ec – Error code output

Returns:

True if device responds

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

Write data to the device.

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 device.

Parameters:

data – Pointer to buffer
len – Length to read
ec – Error code output

Returns:

True if successful

bool write_read(const uint8_t *wdata, size_t wlen, uint8_t *rdata, size_t rlen, std::error_code &ec)

Write then read from the device.

Parameters:

wdata – Write data pointer
wlen – Write data length
rdata – Read buffer pointer
rlen – Read buffer length
ec – Error code output

Returns:

True if successful

bool write(const std::vector<uint8_t> &data, std::error_code &ec)

Write data to the device (vector overload)

Parameters:

data – Data vector
ec – Error code output

Returns:

True if successful

bool read(std::vector<uint8_t> &data, std::error_code &ec)

Read data from the device (vector overload)

Parameters:

data – Data vector (output)
ec – Error code output

Returns:

True if successful

bool write_read(const std::vector<uint8_t> &wdata, std::vector<uint8_t> &rdata, std::error_code &ec)

Write then read from the device (vector overload)

Parameters:

wdata – Write data vector
rdata – Read data vector (output)
ec – Error code output

Returns:

True if successful

bool write_register(RegisterType reg, const uint8_t *data, size_t len, std::error_code &ec)

Write to a register.

Parameters:

reg – Register address
data – Data pointer
len – Data length
ec – Error code output

Returns:

True if successful

bool write_register(RegisterType reg, const std::vector<uint8_t> &data, std::error_code &ec)

Write to a register (vector overload)

Parameters:

reg – Register address
data – Data vector
ec – Error code output

Returns:

True if successful

bool read_register(RegisterType reg, uint8_t *data, size_t len, std::error_code &ec)

Read from a register.

Parameters:

reg – Register address
data – Data pointer (output)
len – Data length
ec – Error code output

Returns:

True if successful

bool read_register(RegisterType reg, std::vector<uint8_t> &data, std::error_code &ec)

Read from a register (vector overload)

Parameters:

reg – Register address
data – Data vector (output)
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

See also

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

See also

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

See also

See also

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

See also

See also

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

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 Config

Configuration for I2C Master Device.

Public Members

uint16_t device_address = 0: I2C device address (7-bit or 10-bit)

int timeout_ms = 10: Timeout for I2C operations (ms)

i2c_addr_bit_len_t addr_bit_len = I2C_ADDR_BIT_LEN_7: Address bit length.

uint32_t scl_speed_hz = 400000: I2C clock speed in hertz.

bool auto_init = true: Automatically initialize on construction.

Logger::Verbosity log_level = Logger::Verbosity::WARN : Logger verbosity.

class I2cMasterBus : public espp::BaseComponent 

I2C Master Bus (C++ wrapper for ESP-IDF new I2C master API)

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

Construct

    logger.info("[NEW API] Starting I2C MasterBus/Device CLI example");
    using espp::I2cMasterBus;
    using espp::I2cMasterDevice;
    std::error_code ec;
    I2cMasterBus bus({
        .port = -1, // auto-select
        .sda_io_num = CONFIG_EXAMPLE_I2C_SDA_GPIO,
        .scl_io_num = CONFIG_EXAMPLE_I2C_SCL_GPIO,
        .clk_speed = CONFIG_EXAMPLE_I2C_CLOCK_SPEED_HZ,
        .log_level = espp::Logger::Verbosity::DEBUG,
    });
    if (!bus.init(ec)) {
      logger.error("[NEW API] Failed to init bus: {}", ec.message());
      return;
    }

Create a device

    // Create a device (using uint8_t as the size for its register addresses)
    auto dev = bus.add_device<uint8_t>(
        espp::I2cMasterDevice<uint8_t>::Config{
            .device_address = CONFIG_EXAMPLE_I2C_DEVICE_ADDR,
            .scl_speed_hz = CONFIG_EXAMPLE_I2C_CLOCK_SPEED_HZ,
            .log_level = espp::Logger::Verbosity::DEBUG,
        },
        ec);
    if (!dev) {
      logger.error("[NEW API] Failed to add device: {}", ec.message());
      return;
    }
    logger.info("[NEW API] Created device with address {:#02x}", dev->get_device_address());

Probe for device(s)

    // NOTE: we turn off logging for this so we don't spam the console
    bus.set_log_level(espp::Logger::Verbosity::ERROR);
    std::vector<uint8_t> found_addresses;
    for (uint8_t address = 0; address < 128; address++) {
      static constexpr int timeout_ms = 50; // timeout for probing each address
      if (bus.probe(address, timeout_ms, ec)) {
        found_addresses.push_back(address);
      }
    }
    bus.set_log_level(espp::Logger::Verbosity::DEBUG);
    logger.info("Found devices at addresses: {::#02x}", found_addresses);

Usage:

Construct with a config
Use init() and deinit() to manage the bus
Use add_device() to create I2cMasterDevice objects
Use probe() to check for device presence
All methods are thread-safe

Note

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

Public Functions

explicit I2cMasterBus(const Config &config)

Construct I2C Master Bus.

Parameters:: config – Configuration for the bus

~I2cMasterBus(): Destructor.

bool init(std::error_code &ec)

Initialize the bus.

Parameters:: ec – Error code output
Returns:: True if successful

bool deinit(std::error_code &ec)

Deinitialize the bus.

Parameters:: ec – Error code output
Returns:: True if successful

template<typename RegisterType> inline std::shared_ptr<I2cMasterDevice<RegisterType>> add_device(const typename I2cMasterDevice<RegisterType>::Config &dev_config, std::error_code &ec)

Add a device to the bus.

Template Parameters:

RegisterType – Register address type

Parameters:

dev_config – Device configuration
ec – Error code output

Returns:

Shared pointer to the created device

bool probe(uint16_t device_address, std::error_code &ec)

Probe for a device on the bus.

Parameters:

device_address – I2C device address
ec – Error code output

Returns:

True if device responds

bool probe(uint16_t device_address, int32_t timeout_ms, std::error_code &ec)

Probe for a device with a custom timeout.

Parameters:

device_address – I2C device address
timeout_ms – Timeout in ms
ec – Error code output

Returns:

True if device responds

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

See also

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

See also

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

See also

See also

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

See also

See also

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

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 Config

Configuration for I2C Master Bus.

Public Members

int port = 0: I2C port number.

int sda_io_num = -1: SDA pin.

int scl_io_num = -1: SCL pin.

uint32_t clk_speed = 400000: 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

components/i2c/include/i2c_master_menu.hpp

Classes

class I2cMasterMenu

A CLI menu for interacting with an I2c master bus (new API).

This class provides a CLI menu for interacting with an I2c master bus using the new ESP-IDF I2C master API. It provides options for setting the log verbosity, scanning the bus for devices, probing for a device at a specific address, reading from a device, and writing to a device.

Example

    using espp::I2cMasterDeviceMenu;
    using espp::I2cMasterMenu;
    // Launch CLI menu for the new driver
    auto root_menu = std::make_unique<cli::Menu>("main", "I2C Main Menu");
    I2cMasterMenu i2c_menu(bus);
    I2cMasterDeviceMenu<uint8_t> i2c_device_menu(dev);
    root_menu->Insert(i2c_menu.get());
    root_menu->Insert(i2c_device_menu.get());
    cli::Cli cli(std::move(root_menu));
    cli::SetColor();
    cli.ExitAction([](auto &out) { out << "Goodbye and thanks for all the fish.\n"; });
    espp::Cli input(cli);
    input.SetInputHistorySize(10);
    input.Start();

Public Functions

inline explicit I2cMasterMenu(std::reference_wrapper<espp::I2cMasterBus> bus)

Construct a new I2cMasterMenu object.

Parameters:: bus – A reference to the I2cMasterBus to interact with.

inline std::unique_ptr<cli::Menu> get(std::string_view name = "i2c_master", std::string_view description = "I2c Master menu")

Get the I2c master menu.

Parameters:

name – The name of the menu.
description – The description of the menu.

Returns:

A unique pointer to the I2c menu that you can use to add to a CLI.

Header File

components/i2c/include/i2c_master_device_menu.hpp

Classes

template<typename RegisterType = uint8_t> class I2cMasterDeviceMenu

A CLI menu for interacting with a single I2c master device (new API).

This class provides a CLI menu for interacting with a single I2c master device using the new ESP-IDF I2C master API. It provides options for setting the log verbosity, probing the device, reading from a register, and writing to a register.

Example

    using espp::I2cMasterDeviceMenu;
    using espp::I2cMasterMenu;
    // Launch CLI menu for the new driver
    auto root_menu = std::make_unique<cli::Menu>("main", "I2C Main Menu");
    I2cMasterMenu i2c_menu(bus);
    I2cMasterDeviceMenu<uint8_t> i2c_device_menu(dev);
    root_menu->Insert(i2c_menu.get());
    root_menu->Insert(i2c_device_menu.get());
    cli::Cli cli(std::move(root_menu));
    cli::SetColor();
    cli.ExitAction([](auto &out) { out << "Goodbye and thanks for all the fish.\n"; });
    espp::Cli input(cli);
    input.SetInputHistorySize(10);
    input.Start();

Usage:

Construct with a shared_ptr to an I2cMasterDevice
Use get() to obtain a CLI menu for the device

Note

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

Public Functions

inline explicit I2cMasterDeviceMenu(std::shared_ptr<espp::I2cMasterDevice<RegisterType>> device)

Construct a new I2cMasterDeviceMenu object.

Parameters:: device – A shared_ptr to the I2cMasterDevice to interact with.

inline std::unique_ptr<cli::Menu> get(std::string_view name = "i2c_device", std::string_view description = "I2c Device menu")

Get the I2c master device menu.

Parameters:

name – The name of the menu.
description – The description of the menu.

Returns:

A unique pointer to the I2c device menu that you can use to add to a CLI.

Header File

components/i2c/include/i2c_slave.hpp

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.

Usage:

Construct with a config
Use read, write, and callback registration methods
All methods are thread-safe

Note

There is no example for this yet as this code is untested.

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

See also

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

See also

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

See also

See also

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

See also

See also

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