i2c_bus.h

Go to the documentation of this file.

#pragma once
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <memory>
#include <utility>
#include <vector>
 
#include "esphome/core/helpers.h"
 
namespace esphome {
namespace i2c {
 
enum ErrorCode {
  NO_ERROR = 0,                
  ERROR_OK = 0,                
  ERROR_INVALID_ARGUMENT = 1,  
  ERROR_NOT_ACKNOWLEDGED = 2,  
  ERROR_TIMEOUT = 3,           
  ERROR_NOT_INITIALIZED = 4,   
  ERROR_TOO_LARGE = 5,         
  ERROR_UNKNOWN = 6,           
  ERROR_CRC = 7,               
};
 
struct ReadBuffer {
  uint8_t *data;  
  size_t len;     
};
 
struct WriteBuffer {
  const uint8_t *data;  
  size_t len;           
};
 
class I2CBus {
 public:
  virtual ~I2CBus() = default;
 
  virtual ErrorCode write_readv(uint8_t address, const uint8_t *write_buffer, size_t write_count, uint8_t *read_buffer,
                                size_t read_count) = 0;
 
  // Legacy functions for compatibility
 
  ErrorCode read(uint8_t address, uint8_t *buffer, size_t len) {
    return this->write_readv(address, nullptr, 0, buffer, len);
  }
 
  ErrorCode write(uint8_t address, const uint8_t *buffer, size_t len, bool stop = true) {
    return this->write_readv(address, buffer, len, nullptr, 0);
  }
 
  ESPDEPRECATED("This method is deprecated and will be removed in ESPHome 2026.3.0. Use write_readv() instead.",
                "2025.9.0")
  ErrorCode readv(uint8_t address, ReadBuffer *read_buffers, size_t count) {
    size_t total_len = 0;
    for (size_t i = 0; i != count; i++) {
      total_len += read_buffers[i].len;
    }
 
    SmallBufferWithHeapFallback<128> buffer_alloc(total_len);  // Most I2C reads are small
    uint8_t *buffer = buffer_alloc.get();
 
    auto err = this->write_readv(address, nullptr, 0, buffer, total_len);
    if (err != ERROR_OK)
      return err;
    size_t pos = 0;
    for (size_t i = 0; i != count; i++) {
      if (read_buffers[i].len != 0) {
        std::memcpy(read_buffers[i].data, buffer + pos, read_buffers[i].len);
        pos += read_buffers[i].len;
      }
    }
    return ERROR_OK;
  }
 
  ESPDEPRECATED("This method is deprecated and will be removed in ESPHome 2026.3.0. Use write_readv() instead.",
                "2025.9.0")
  ErrorCode writev(uint8_t address, const WriteBuffer *write_buffers, size_t count, bool stop = true) {
    size_t total_len = 0;
    for (size_t i = 0; i != count; i++) {
      total_len += write_buffers[i].len;
    }
 
    SmallBufferWithHeapFallback<128> buffer_alloc(total_len);  // Most I2C writes are small
    uint8_t *buffer = buffer_alloc.get();
 
    size_t pos = 0;
    for (size_t i = 0; i != count; i++) {
      std::memcpy(buffer + pos, write_buffers[i].data, write_buffers[i].len);
      pos += write_buffers[i].len;
    }
 
    return this->write_readv(address, buffer, total_len, nullptr, 0);
  }
 
 protected:
  void i2c_scan_();
  std::vector<std::pair<uint8_t, bool>> scan_results_;  
  bool scan_{false};                                    
};
 
class InternalI2CBus : public I2CBus {
 public:
  virtual int get_port() const = 0;
};
 
}  // namespace i2c
}  // namespace esphome