LibXR::ESP32I2C Class Reference

Inheritance diagram for LibXR::ESP32I2C:

Collaboration diagram for LibXR::ESP32I2C:

Public Member Functions
	ESP32I2C (i2c_port_t port_num, int scl_pin, int sda_pin, uint32_t clock_speed=400000U, bool enable_internal_pullup=true, uint32_t timeout_ms=100U, uint32_t isr_enable_min_size=32U)
ErrorCode	Read (uint16_t slave_addr, RawData read_data, ReadOperation &op, bool in_isr=false) override
	读取 I2C 设备的数据。 Reads data from an I2C device.
ErrorCode	Write (uint16_t slave_addr, ConstRawData write_data, WriteOperation &op, bool in_isr=false) override
	向 I2C 设备写入数据。 Writes data to an I2C device.
ErrorCode	SetConfig (Configuration config) override
	配置 I2C 设备参数。 Configures the I2C device settings.
ErrorCode	MemRead (uint16_t slave_addr, uint16_t mem_addr, RawData read_data, ReadOperation &op, MemAddrLength mem_addr_size=MemAddrLength::BYTE_8, bool in_isr=false) override
	从 I2C 设备指定寄存器读取数据。 Reads data from a specific register of an I2C device.
ErrorCode	MemWrite (uint16_t slave_addr, uint16_t mem_addr, ConstRawData write_data, WriteOperation &op, MemAddrLength mem_addr_size=MemAddrLength::BYTE_8, bool in_isr=false) override
	向 I2C 设备指定寄存器写入数据。 Writes data to a specific register of an I2C device.
i2c_port_t	Port () const
Public Member Functions inherited from LibXR::I2C
	I2C ()
	默认构造函数。 Default constructor.

Static Public Attributes
static constexpr int	PIN_NO_CHANGE = -1

Additional Inherited Members
Public Types inherited from LibXR::I2C
enum class	MemAddrLength : uint8_t { BYTE_8 , BYTE_16 }

Detailed Description

Definition at line 20 of file esp_i2c.hpp.

Constructor & Destructor Documentation

ESP32I2C()

LibXR::ESP32I2C::ESP32I2C	(	i2c_port_t	port_num,
		int	scl_pin,
		int	sda_pin,
		uint32_t	clock_speed = 400000U,
		bool	enable_internal_pullup = true,
		uint32_t	timeout_ms = 100U,
		uint32_t	isr_enable_min_size = 32U )

Definition at line 135 of file esp_i2c.cpp.

    : port_num_(port_num),
      scl_pin_(scl_pin),
      sda_pin_(sda_pin),
      enable_internal_pullup_(enable_internal_pullup),
      timeout_ms_(timeout_ms),
      isr_enable_min_size_(isr_enable_min_size),
      config_{clock_speed}
{
  ASSERT(port_num_ >= 0);
  ASSERT(port_num_ < SOC_I2C_NUM);
  ASSERT(GPIO_IS_VALID_OUTPUT_GPIO(static_cast<gpio_num_t>(scl_pin_)));
  ASSERT(GPIO_IS_VALID_OUTPUT_GPIO(static_cast<gpio_num_t>(sda_pin_)));
  ASSERT(config_.clock_speed > 0U);
  static_assert(FIFO_LEN > 2U);
 
  if (InitHardware() != ErrorCode::OK)
  {
    REQUIRE(false);
    return;
  }
}

Member Function Documentation

MemRead()

ErrorCode LibXR::ESP32I2C::MemRead ( uint16_t slave_addr, uint16_t mem_addr, RawData read_data, ReadOperation & op, MemAddrLength mem_addr_size = MemAddrLength::BYTE_8, bool in_isr = false )

overridevirtual

从 I2C 设备指定寄存器读取数据。 Reads data from a specific register of an I2C device.

该函数从指定 I2C 从设备的寄存器地址读取数据，并存储到 read_data 中。 This function reads data from the specified register of the I2C slave and stores it in read_data.

Parameters

slave_addr	目标 I2C 从设备地址，不带 R/W 位。 Target I2C slave address, no R/W bit included.
mem_addr	寄存器地址（通常为 8 位或 16 位）。 Register address (typically 8-bit or 16-bit).
read_data	用于存储读取数据的 RawData 对象。 RawData object to store read data.
op	异步或同步的读取操作对象。 Read operation object (sync or async).
mem_addr_size	寄存器地址长度。 Size of register address in bytes.
in_isr	是否在中断中进行操作 / Whether the operation is performed in an ISR.

Returns

返回 ErrorCode，表示是否读取成功。 Returns ErrorCode indicating success or failure.

Implements LibXR::I2C.

Definition at line 1273 of file esp_i2c.cpp.

{
  const ErrorCode init_ec = EnsureInitialized(in_isr);
  if (init_ec != ErrorCode::OK)
  {
    return Complete(op, in_isr, init_ec);
  }
 
  if (!IsValid7BitAddr(slave_addr))
  {
    return Complete(op, in_isr, ErrorCode::ARG_ERR);
  }
 
  if ((read_data.size_ > 0U) && (read_data.addr_ == nullptr))
  {
    return Complete(op, in_isr, ErrorCode::PTR_NULL);
  }
 
  const size_t mem_len = MemAddrBytes(mem_addr_size);
  if (mem_len > MAX_WRITE_READ_PREFIX)
  {
    return Complete(op, in_isr, ErrorCode::SIZE_ERR);
  }
 
  if (!Acquire())
  {
    return Complete(op, in_isr, ErrorCode::BUSY);
  }
 
  std::array<uint8_t, 2> mem_raw = {};
  EncodeMemAddr(mem_addr, mem_len, mem_raw.data());
 
  auto* dst = static_cast<uint8_t*>(read_data.addr_);
  const size_t total_size = mem_len + read_data.size_;
  if ((read_data.size_ > 0U) && ShouldUseInterruptAsync(total_size))
  {
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      block_wait_.Start(*op.data.sem_info.sem);
    }
    const ErrorCode ans =
        StartAsyncTransaction(slave_addr, mem_raw.data(), mem_len, nullptr, 0U, dst,
                              read_data.size_, op, in_isr);
    if (ans != ErrorCode::OK)
    {
      if (op.type == ReadOperation::OperationType::BLOCK)
      {
        block_wait_.Cancel();
      }
      Release();
      return Complete(op, in_isr, ans);
    }
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      ASSERT(!in_isr);
      return block_wait_.Wait(op.data.sem_info.timeout);
    }
    return ErrorCode::OK;
  }
 
  size_t offset = 0U;
  ErrorCode ans = ErrorCode::OK;
 
  while (offset < read_data.size_)
  {
    const size_t chunk = std::min(read_data.size_ - offset, MAX_READ_PAYLOAD);
    const uint16_t cur_mem = static_cast<uint16_t>(mem_addr + offset);
    EncodeMemAddr(cur_mem, mem_len, mem_raw.data());
 
    ans = ExecuteTransaction(slave_addr, mem_raw.data(), mem_len, dst + offset, chunk,
                             in_isr);
    if (ans != ErrorCode::OK)
    {
      break;
    }
    offset += chunk;
  }
 
  Release();
  return Complete(op, in_isr, ans);
}

MemWrite()

ErrorCode LibXR::ESP32I2C::MemWrite ( uint16_t slave_addr, uint16_t mem_addr, ConstRawData write_data, WriteOperation & op, MemAddrLength mem_addr_size = MemAddrLength::BYTE_8, bool in_isr = false )

overridevirtual

向 I2C 设备指定寄存器写入数据。 Writes data to a specific register of an I2C device.

该函数将 write_data 写入指定 I2C 从设备的寄存器地址。 This function writes write_data to the specified register of the I2C slave.

Parameters

slave_addr	目标 I2C 从设备地址，不带 R/W 位。 Target I2C slave address, no R/W bit included.
mem_addr	寄存器地址（通常为 8 位或 16 位）。 Register address (typically 8-bit or 16-bit).
write_data	要写入的数据，ConstRawData 类型。 Data to be written, of type ConstRawData.
op	异步或同步的写入操作对象。 Write operation object (sync or async).
mem_addr_size	寄存器地址长度。 Size of register address in bytes.
in_isr	是否在中断中进行操作 / Whether the operation is performed in an ISR.

Returns

返回 ErrorCode，表示是否写入成功。 Returns ErrorCode indicating success or failure.

Implements LibXR::I2C.

Definition at line 1178 of file esp_i2c.cpp.

{
  const ErrorCode init_ec = EnsureInitialized(in_isr);
  if (init_ec != ErrorCode::OK)
  {
    return Complete(op, in_isr, init_ec);
  }
 
  if (!IsValid7BitAddr(slave_addr))
  {
    return Complete(op, in_isr, ErrorCode::ARG_ERR);
  }
 
  if ((write_data.size_ > 0U) && (write_data.addr_ == nullptr))
  {
    return Complete(op, in_isr, ErrorCode::PTR_NULL);
  }
 
  const size_t mem_len = MemAddrBytes(mem_addr_size);
  if (mem_len > MAX_WRITE_PAYLOAD)
  {
    return Complete(op, in_isr, ErrorCode::SIZE_ERR);
  }
 
  if (!Acquire())
  {
    return Complete(op, in_isr, ErrorCode::BUSY);
  }
 
  std::array<uint8_t, 2> mem_raw = {};
  EncodeMemAddr(mem_addr, mem_len, mem_raw.data());
 
  const size_t total_size = mem_len + write_data.size_;
  if (ShouldUseInterruptAsync(total_size))
  {
    if (op.type == WriteOperation::OperationType::BLOCK)
    {
      block_wait_.Start(*op.data.sem_info.sem);
    }
    const ErrorCode ans =
        StartAsyncTransaction(slave_addr, mem_raw.data(), mem_len,
                              static_cast<const uint8_t*>(write_data.addr_),
                              write_data.size_, nullptr, 0U, op, in_isr);
    if (ans != ErrorCode::OK)
    {
      if (op.type == WriteOperation::OperationType::BLOCK)
      {
        block_wait_.Cancel();
      }
      Release();
      return Complete(op, in_isr, ans);
    }
    if (op.type == WriteOperation::OperationType::BLOCK)
    {
      ASSERT(!in_isr);
      return block_wait_.Wait(op.data.sem_info.timeout);
    }
    return ErrorCode::OK;
  }
 
  std::array<uint8_t, FIFO_LEN> staging = {};
  const size_t max_chunk = MAX_WRITE_PAYLOAD - mem_len;
  auto* src = static_cast<const uint8_t*>(write_data.addr_);
  size_t offset = 0U;
  ErrorCode ans = ErrorCode::OK;
 
  if (write_data.size_ == 0U)
  {
    EncodeMemAddr(mem_addr, mem_len, staging.data());
    ans = ExecuteTransaction(slave_addr, staging.data(), mem_len, nullptr, 0U, in_isr);
  }
  else
  {
    while (offset < write_data.size_)
    {
      const size_t chunk = std::min(write_data.size_ - offset, max_chunk);
      const uint16_t cur_mem = static_cast<uint16_t>(mem_addr + offset);
      EncodeMemAddr(cur_mem, mem_len, staging.data());
      Memory::FastCopy(staging.data() + mem_len, src + offset, chunk);
      ans = ExecuteTransaction(slave_addr, staging.data(), mem_len + chunk, nullptr, 0U,
                               in_isr);
      if (ans != ErrorCode::OK)
      {
        break;
      }
      offset += chunk;
    }
  }
 
  Release();
  return Complete(op, in_isr, ans);
}

Port()

i2c_port_t LibXR::ESP32I2C::Port ( ) const

inline

Definition at line 47 of file esp_i2c.hpp.

{ return port_num_; }

Read()

ErrorCode LibXR::ESP32I2C::Read ( uint16_t slave_addr, RawData read_data, ReadOperation & op, bool in_isr = false )

overridevirtual

读取 I2C 设备的数据。 Reads data from an I2C device.

该函数从指定的 I2C 从设备地址读取数据，并存储到 read_data 中。 This function reads data from the specified I2C slave address and stores it in read_data.

Parameters

slave_addr	目标 I2C 从设备地址，不带 R/W 位。 Target I2C slave address, no R/W bit included.
read_data	存储读取数据的 RawData 对象。 A RawData object to store the read data.
op	读取操作对象，包含同步或异步操作模式。 Read operation object containing synchronous or asynchronous operation mode.
in_isr	是否在中断中进行操作 / Whether the operation is performed in an ISR.

Returns

返回 ErrorCode，指示操作是否成功。 Returns an ErrorCode indicating whether the operation was successful.

Implements LibXR::I2C.

Definition at line 1120 of file esp_i2c.cpp.

{
  const ErrorCode init_ec = EnsureInitialized(in_isr);
  if (init_ec != ErrorCode::OK)
  {
    return Complete(op, in_isr, init_ec);
  }
 
  if (!IsValid7BitAddr(slave_addr))
  {
    return Complete(op, in_isr, ErrorCode::ARG_ERR);
  }
 
  if ((read_data.size_ > 0U) && (read_data.addr_ == nullptr))
  {
    return Complete(op, in_isr, ErrorCode::PTR_NULL);
  }
 
  if (!Acquire())
  {
    return Complete(op, in_isr, ErrorCode::BUSY);
  }
 
  const size_t total_size = read_data.size_;
  if (ShouldUseInterruptAsync(total_size))
  {
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      block_wait_.Start(*op.data.sem_info.sem);
    }
    const ErrorCode ans = StartAsyncTransaction(slave_addr, nullptr, 0U, nullptr, 0U,
                                                static_cast<uint8_t*>(read_data.addr_),
                                                read_data.size_, op, in_isr);
    if (ans != ErrorCode::OK)
    {
      if (op.type == ReadOperation::OperationType::BLOCK)
      {
        block_wait_.Cancel();
      }
      Release();
      return Complete(op, in_isr, ans);
    }
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      ASSERT(!in_isr);
      return block_wait_.Wait(op.data.sem_info.timeout);
    }
    return ErrorCode::OK;
  }
 
  const ErrorCode ans =
      ExecuteTransaction(slave_addr, nullptr, 0U, static_cast<uint8_t*>(read_data.addr_),
                         read_data.size_, in_isr);
  Release();
  return Complete(op, in_isr, ans);
}

SetConfig()

ErrorCode LibXR::ESP32I2C::SetConfig ( Configuration config )

overridevirtual

配置 I2C 设备参数。 Configures the I2C device settings.

该函数用于设置 I2C 设备的参数，例如通信速率等。 This function sets the parameters of the I2C device, such as the communication speed.

Parameters

config

包含 I2C 设置信息的 Configuration 结构体。 A Configuration structure containing I2C settings.

Returns

返回 ErrorCode，指示配置是否成功。 Returns an ErrorCode indicating whether the configuration was successful.

Implements LibXR::I2C.

Definition at line 1024 of file esp_i2c.cpp.

{
  if (config.clock_speed == 0U)
  {
    return ErrorCode::ARG_ERR;
  }
 
  if (!initialized_)
  {
    const ErrorCode init_err = InitHardware();
    if (init_err != ErrorCode::OK)
    {
      return init_err;
    }
  }
 
  if (!Acquire())
  {
    return ErrorCode::BUSY;
  }
 
  if (i2c_ll_is_bus_busy(hal_.dev))
  {
    Release();
    return ErrorCode::BUSY;
  }
 
  const Configuration previous_config = config_;
  config_ = config;
  const ErrorCode ans = ApplyConfig();
  if (ans != ErrorCode::OK)
  {
    config_ = previous_config;
  }
  Release();
  return ans;
}

Write()

ErrorCode LibXR::ESP32I2C::Write ( uint16_t slave_addr, ConstRawData write_data, WriteOperation & op, bool in_isr = false )

overridevirtual

向 I2C 设备写入数据。 Writes data to an I2C device.

该函数将 write_data 写入指定的 I2C 从设备地址。 This function writes write_data to the specified I2C slave address.

Parameters

slave_addr	目标 I2C 从设备地址，不带 R/W 位。 Target I2C slave address, no R/W bit included.
write_data	需要写入的数据，ConstRawData 类型。 The data to be written, of type ConstRawData.
op	写入操作对象，包含同步或异步操作模式。 Write operation object containing synchronous or asynchronous operation mode.
in_isr	是否在中断中进行操作 / Whether the operation is performed in an ISR.

Returns

返回 ErrorCode，指示操作是否成功。 Returns an ErrorCode indicating whether the operation was successful.

Implements LibXR::I2C.

Definition at line 1062 of file esp_i2c.cpp.

{
  const ErrorCode init_ec = EnsureInitialized(in_isr);
  if (init_ec != ErrorCode::OK)
  {
    return Complete(op, in_isr, init_ec);
  }
 
  if (!IsValid7BitAddr(slave_addr))
  {
    return Complete(op, in_isr, ErrorCode::ARG_ERR);
  }
 
  if ((write_data.size_ > 0U) && (write_data.addr_ == nullptr))
  {
    return Complete(op, in_isr, ErrorCode::PTR_NULL);
  }
 
  if (!Acquire())
  {
    return Complete(op, in_isr, ErrorCode::BUSY);
  }
 
  const size_t total_size = write_data.size_;
  if (ShouldUseInterruptAsync(total_size))
  {
    if (op.type == WriteOperation::OperationType::BLOCK)
    {
      block_wait_.Start(*op.data.sem_info.sem);
    }
    const ErrorCode ans = StartAsyncTransaction(
        slave_addr, nullptr, 0U, static_cast<const uint8_t*>(write_data.addr_),
        write_data.size_, nullptr, 0U, op, in_isr);
    if (ans != ErrorCode::OK)
    {
      if (op.type == WriteOperation::OperationType::BLOCK)
      {
        block_wait_.Cancel();
      }
      Release();
      return Complete(op, in_isr, ans);
    }
    if (op.type == WriteOperation::OperationType::BLOCK)
    {
      ASSERT(!in_isr);
      return block_wait_.Wait(op.data.sem_info.timeout);
    }
    return ErrorCode::OK;
  }
 
  const ErrorCode ans =
      ExecuteTransaction(slave_addr, static_cast<const uint8_t*>(write_data.addr_),
                         write_data.size_, nullptr, 0U, in_isr);
  Release();
  return Complete(op, in_isr, ans);
}

Member Data Documentation

PIN_NO_CHANGE

int LibXR::ESP32I2C::PIN_NO_CHANGE = -1

staticconstexpr

Definition at line 23 of file esp_i2c.hpp.

---

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

• driver/esp/esp_i2c.hpp
• driver/esp/esp_i2c.cpp