From 7208dd25d0fd3df64e23bdf99b6ac4124ba03c97 Mon Sep 17 00:00:00 2001 From: X-Ryl669 Date: Fri, 8 Mar 2024 19:04:56 +0100 Subject: [PATCH] Add I2C ADF bus support --- esphome/components/i2c_adf/__init__.py | 153 +++++++ .../components/i2c_adf/i2c_bus_esp_adf.cpp | 400 ++++++++++++++++++ esphome/components/i2c_adf/i2c_bus_esp_adf.h | 50 +++ 3 files changed, 603 insertions(+) create mode 100644 esphome/components/i2c_adf/__init__.py create mode 100644 esphome/components/i2c_adf/i2c_bus_esp_adf.cpp create mode 100644 esphome/components/i2c_adf/i2c_bus_esp_adf.h diff --git a/esphome/components/i2c_adf/__init__.py b/esphome/components/i2c_adf/__init__.py new file mode 100644 index 0000000000..3835442ec3 --- /dev/null +++ b/esphome/components/i2c_adf/__init__.py @@ -0,0 +1,153 @@ +import esphome.codegen as cg +import esphome.config_validation as cv +import esphome.final_validate as fv +from esphome import pins +from esphome.const import ( + CONF_FREQUENCY, + CONF_ID, + CONF_INPUT, + CONF_OUTPUT, + CONF_SCAN, + CONF_SCL, + CONF_SDA, + CONF_ADDRESS, + CONF_I2C_ID, + PLATFORM_ESP32, + PLATFORM_ESP8266, + PLATFORM_RP2040, +) +from esphome.core import coroutine_with_priority, CORE +from esphome.components.i2c import I2CDevice, i2c_ns, I2CBus + +from pprint import pprint + +CODEOWNERS = ["@esphome/X-Ryl669"] +ADFI2CBus = i2c_ns.class_("ADFI2CBus", I2CBus, cg.Component) + + +CONF_SDA_PULLUP_ENABLED = "sda_pullup_enabled" +CONF_SCL_PULLUP_ENABLED = "scl_pullup_enabled" +MULTI_CONF = True + + +def _bus_declare_type(value): + if CORE.using_arduino: + raise cv.Invalid(f"Not supported on Arduino platform") + if CORE.using_esp_idf: + return cv.declare_id(ADFI2CBus)(value) + raise NotImplementedError + + +pin_with_input_and_output_support = cv.All( + pins.internal_gpio_pin_number({CONF_INPUT: True}), + pins.internal_gpio_pin_number({CONF_OUTPUT: True}), +) + + +CONFIG_SCHEMA = cv.All( + cv.Schema( + { + cv.GenerateID(): _bus_declare_type, + cv.Optional(CONF_SDA, default="SDA"): pin_with_input_and_output_support, + cv.SplitDefault(CONF_SDA_PULLUP_ENABLED, esp32_idf=True): cv.All( + cv.only_with_esp_idf, cv.boolean + ), + cv.Optional(CONF_SCL, default="SCL"): pin_with_input_and_output_support, + cv.SplitDefault(CONF_SCL_PULLUP_ENABLED, esp32_idf=True): cv.All( + cv.only_with_esp_idf, cv.boolean + ), + cv.Optional(CONF_FREQUENCY, default="100kHz"): cv.All( + cv.frequency, cv.Range(min=0, min_included=False) + ), + cv.Optional(CONF_SCAN, default=True): cv.boolean, + } + ).extend(cv.COMPONENT_SCHEMA), + cv.only_on([PLATFORM_ESP32]), +) + + +@coroutine_with_priority(1.0) +async def to_code(config): + cg.add_global(i2c_ns.using) + var = cg.new_Pvariable(config[CONF_ID]) + await cg.register_component(var, config) + + cg.add(var.set_sda_pin(config[CONF_SDA])) + if CONF_SDA_PULLUP_ENABLED in config: + cg.add(var.set_sda_pullup_enabled(config[CONF_SDA_PULLUP_ENABLED])) + cg.add(var.set_scl_pin(config[CONF_SCL])) + if CONF_SCL_PULLUP_ENABLED in config: + cg.add(var.set_scl_pullup_enabled(config[CONF_SCL_PULLUP_ENABLED])) + + cg.add(var.set_frequency(int(config[CONF_FREQUENCY]))) + cg.add(var.set_scan(config[CONF_SCAN])) + + +def i2c_device_schema(default_address): + """Create a schema for a i2c device. + + :param default_address: The default address of the i2c device, can be None to represent + a required option. + :return: The i2c device schema, `extend` this in your config schema. + """ + schema = { + cv.GenerateID(CONF_I2C_ID): cv.use_id(I2CBus), + cv.Optional("multiplexer"): cv.invalid( + "This option has been removed, please see " + "the tca9584a docs for the updated way to use multiplexers" + ), + } + if default_address is None: + schema[cv.Required(CONF_ADDRESS)] = cv.i2c_address + else: + schema[cv.Optional(CONF_ADDRESS, default=default_address)] = cv.i2c_address + return cv.Schema(schema) + + +async def register_i2c_device(var, config): + """Register an i2c device with the given config. + + Sets the i2c bus to use and the i2c address. + + This is a coroutine, you need to await it with a 'yield' expression! + """ + parent = await cg.get_variable(config[CONF_I2C_ID]) + cg.add(var.set_i2c_bus(parent)) + cg.add(var.set_i2c_address(config[CONF_ADDRESS])) + + +def final_validate_device_schema( + name: str, *, min_frequency: cv.frequency = None, max_frequency: cv.frequency = None +): + hub_schema = {} + if min_frequency is not None: + hub_schema[cv.Required(CONF_FREQUENCY)] = cv.Range( + min=cv.frequency(min_frequency), + min_included=True, + msg=f"Component {name} requires a minimum frequency of {min_frequency} for the I2C bus", + ) + + if max_frequency is not None: + hub_schema[cv.Required(CONF_FREQUENCY)] = cv.Range( + max=cv.frequency(max_frequency), + max_included=True, + msg=f"Component {name} cannot be used with a frequency of over {max_frequency} for the I2C bus", + ) + + return cv.Schema( + {cv.Required(CONF_I2C_ID): fv.id_declaration_match_schema(hub_schema)}, + extra=cv.ALLOW_EXTRA, + ) + +def validate_not_idfbus(config): + if not CORE.is_esp32: + raise cv.Invalid("Not supported on other CPU that ESP32") + + if ( + "i2c" in fv.full_config.get() +# and fv.full_config.get()["i2c"][0]["id"].type == "IDFI2CBus" + ): + raise cv.Invalid("Can't be used with default i2c component, remove it first to use i2c_adf") + return config + +FINAL_VALIDATE_SCHEMA = validate_not_idfbus diff --git a/esphome/components/i2c_adf/i2c_bus_esp_adf.cpp b/esphome/components/i2c_adf/i2c_bus_esp_adf.cpp new file mode 100644 index 0000000000..bab2b0d777 --- /dev/null +++ b/esphome/components/i2c_adf/i2c_bus_esp_adf.cpp @@ -0,0 +1,400 @@ +#include "i2c_bus_esp_adf.h" +#ifdef USE_ESP_ADF +// We need the i2c_bus.h header from the esp_peripherals component of ADF, not the one in this folder +#include "esphome/core/hal.h" +#include "esphome/core/log.h" +#include "esphome/core/helpers.h" +#include "esphome/core/application.h" +#include +#include + + +namespace esphome { +namespace i2c { + + +static const char *const TAG = "i2c.adf"; + +static void recover_i2c_hard(i2c_port_t, void* bus) { + ((ADFI2CBus*)bus)->recover_(); +} + +void ADFI2CBus::setup() { + ESP_LOGCONFIG(TAG, "Setting up I2C bus..."); + + static i2c_port_t next_port = I2C_NUM_0; + i2c_port_t port = next_port; +#if I2C_NUM_MAX > 1 + next_port = (next_port == I2C_NUM_0) ? I2C_NUM_1 : I2C_NUM_MAX; +#else + next_port = I2C_NUM_MAX; +#endif + if (port == I2C_NUM_MAX) { + ESP_LOGE(TAG, "Too many I2C buses configured"); this->mark_failed(); return; + } + + + i2c_config_t conf{}; + memset(&conf, 0, sizeof(conf)); + conf.mode = I2C_MODE_MASTER; + conf.sda_io_num = sda_pin_; + conf.sda_pullup_en = sda_pullup_enabled_; + conf.scl_io_num = scl_pin_; + conf.scl_pullup_en = scl_pullup_enabled_; + conf.master.clk_speed = frequency_; + this->handle_ = i2c_bus_create(port, &conf); + if (this->handle_ == NULL) { + ESP_LOGW(TAG, "i2c_bus_create failed"); + this->mark_failed(); + return; + } + if (i2c_bus_run_cb(this->handle_, &recover_i2c_hard, this) != ESP_OK) + ESP_LOGW(TAG, "i2c_bus_recover failed"); + this->mark_failed(); + return; + } + + if (this->scan_) { + ESP_LOGV(TAG, "Scanning i2c bus for active devices..."); + this->i2c_scan_(); + } +} +void ADFI2CBus::dump_config() { + ESP_LOGCONFIG(TAG, "I2C Bus:"); + ESP_LOGCONFIG(TAG, " SDA Pin: GPIO%u", this->sda_pin_); + ESP_LOGCONFIG(TAG, " SCL Pin: GPIO%u", this->scl_pin_); + ESP_LOGCONFIG(TAG, " Frequency: %" PRIu32 " Hz", this->frequency_); + switch (this->recovery_result_) { + case RECOVERY_COMPLETED: + ESP_LOGCONFIG(TAG, " Recovery: bus successfully recovered"); + break; + case RECOVERY_FAILED_SCL_LOW: + ESP_LOGCONFIG(TAG, " Recovery: failed, SCL is held low on the bus"); + break; + case RECOVERY_FAILED_SDA_LOW: + ESP_LOGCONFIG(TAG, " Recovery: failed, SDA is held low on the bus"); + break; + } + if (this->scan_) { + ESP_LOGI(TAG, "Results from i2c bus scan:"); + if (scan_results_.empty()) { + ESP_LOGI(TAG, "Found no i2c devices!"); + } else { + for (const auto &s : scan_results_) { + if (s.second) { + ESP_LOGI(TAG, "Found i2c device at address 0x%02X", s.first); + } else { + ESP_LOGE(TAG, "Unknown error at address 0x%02X", s.first); + } + } + } + } +} + + +struct ReadVCmd +{ + uint8_t address; + ReadBuffer * buffers; + size_t cnt; + ErrorCode code { ERROR_UNKNOWN }; + + ErrorCode read(i2c_port_t port) { + i2c_cmd_handle_t cmd = i2c_cmd_link_create(); + esp_err_t err = i2c_master_start(cmd); + if (err != ESP_OK) { + ESP_LOGVV(TAG, "RX from %02X master start failed: %s", address, esp_err_to_name(err)); + i2c_cmd_link_delete(cmd); + return ERROR_UNKNOWN; + } + err = i2c_master_write_byte(cmd, (address << 1) | I2C_MASTER_READ, true); + if (err != ESP_OK) { + ESP_LOGVV(TAG, "RX from %02X address write failed: %s", address, esp_err_to_name(err)); + i2c_cmd_link_delete(cmd); + return ERROR_UNKNOWN; + } + for (size_t i = 0; i < cnt; i++) { + const auto &buf = buffers[i]; + if (buf.len == 0) + continue; + err = i2c_master_read(cmd, buf.data, buf.len, i == cnt - 1 ? I2C_MASTER_LAST_NACK : I2C_MASTER_ACK); + if (err != ESP_OK) { + ESP_LOGVV(TAG, "RX from %02X data read failed: %s", address, esp_err_to_name(err)); + i2c_cmd_link_delete(cmd); + return ERROR_UNKNOWN; + } + } + err = i2c_master_stop(cmd); + if (err != ESP_OK) { + ESP_LOGVV(TAG, "RX from %02X stop failed: %s", address, esp_err_to_name(err)); + i2c_cmd_link_delete(cmd); + return ERROR_UNKNOWN; + } + + err = i2c_master_cmd_begin(port, cmd, 20 / portTICK_PERIOD_MS); + i2c_cmd_link_delete(cmd); + if (err == ESP_FAIL) { + // transfer not acked + ESP_LOGVV(TAG, "RX from %02X failed: not acked", address); + return ERROR_NOT_ACKNOWLEDGED; + } else if (err == ESP_ERR_TIMEOUT) { + ESP_LOGVV(TAG, "RX from %02X failed: timeout", address); + return ERROR_TIMEOUT; + } else if (err != ESP_OK) { + ESP_LOGVV(TAG, "RX from %02X failed: %s", address, esp_err_to_name(err)); + return ERROR_UNKNOWN; + } + +#ifdef ESPHOME_LOG_HAS_VERY_VERBOSE + char debug_buf[4]; + std::string debug_hex; + + for (size_t i = 0; i < cnt; i++) { + const auto &buf = buffers[i]; + for (size_t j = 0; j < buf.len; j++) { + snprintf(debug_buf, sizeof(debug_buf), "%02X", buf.data[j]); + debug_hex += debug_buf; + } + } + ESP_LOGVV(TAG, "0x%02X RX %s", address, debug_hex.c_str()); +#endif + + return ERROR_OK; + } + +}; +// Calling stub for I2C port +static void i2c_readv(i2c_port_t port, void* arg) { + ReadVCmd * args = (ReadVCmd*)arg; + args->code = args->read(port); +} + +ErrorCode ADFI2CBus::readv(uint8_t address, ReadBuffer *buffers, size_t cnt) { + // logging is only enabled with vv level, if warnings are shown the caller + // should log them + if (!this->handle_) { + ESP_LOGVV(TAG, "i2c bus not initialized!"); + return ERROR_NOT_INITIALIZED; + } + ReadVCmd cmd { address, buffers, cnt }; + if (i2c_bus_run_cb(this->handle_, &i2c_readv, &cmd) != ESP_OK || cmd.code != ERROR_OK) { + ESP_LOGVV(TAG, "i2c readv failed!"); + return cmd.code; + } + return ERROR_OK; +} + +struct WriteVCmd +{ + uint8_t address; + WriteBuffer * buffers; + size_t cnt; + bool stop; + ErrorCode code { ERROR_UNKNOWN }; + + ErrorCode write(i2c_port_t port) { +#ifdef ESPHOME_LOG_HAS_VERY_VERBOSE + char debug_buf[4]; + std::string debug_hex; + + for (size_t i = 0; i < cnt; i++) { + const auto &buf = buffers[i]; + for (size_t j = 0; j < buf.len; j++) { + snprintf(debug_buf, sizeof(debug_buf), "%02X", buf.data[j]); + debug_hex += debug_buf; + } + } + ESP_LOGVV(TAG, "0x%02X TX %s", address, debug_hex.c_str()); +#endif + + i2c_cmd_handle_t cmd = i2c_cmd_link_create(); + esp_err_t err = i2c_master_start(cmd); + if (err != ESP_OK) { + ESP_LOGVV(TAG, "TX to %02X master start failed: %s", address, esp_err_to_name(err)); + i2c_cmd_link_delete(cmd); + return ERROR_UNKNOWN; + } + err = i2c_master_write_byte(cmd, (address << 1) | I2C_MASTER_WRITE, true); + if (err != ESP_OK) { + ESP_LOGVV(TAG, "TX to %02X address write failed: %s", address, esp_err_to_name(err)); + i2c_cmd_link_delete(cmd); + return ERROR_UNKNOWN; + } + for (size_t i = 0; i < cnt; i++) { + const auto &buf = buffers[i]; + if (buf.len == 0) + continue; + err = i2c_master_write(cmd, buf.data, buf.len, true); + if (err != ESP_OK) { + ESP_LOGVV(TAG, "TX to %02X data write failed: %s", address, esp_err_to_name(err)); + i2c_cmd_link_delete(cmd); + return ERROR_UNKNOWN; + } + } + if (stop) { + err = i2c_master_stop(cmd); + if (err != ESP_OK) { + ESP_LOGVV(TAG, "TX to %02X master stop failed: %s", address, esp_err_to_name(err)); + i2c_cmd_link_delete(cmd); + return ERROR_UNKNOWN; + } + } + + err = i2c_master_cmd_begin(port, cmd, 20 / portTICK_PERIOD_MS); + if (err == ESP_FAIL) { + // transfer not acked + ESP_LOGVV(TAG, "TX to %02X failed: not acked", address); + return ERROR_NOT_ACKNOWLEDGED; + } else if (err == ESP_ERR_TIMEOUT) { + ESP_LOGVV(TAG, "TX to %02X failed: timeout", address); + return ERROR_TIMEOUT; + } else if (err != ESP_OK) { + ESP_LOGVV(TAG, "TX to %02X failed: %s", address, esp_err_to_name(err)); + return ERROR_UNKNOWN; + } + return ERROR_OK; + } +}; + +// Calling stub for I2C port +static void i2c_writev(i2c_port_t port, void* arg) { + WriteVCmd * args = (WriteVCmd*)arg; + args->code = args->write(port); +} + +ErrorCode ADFI2CBus::writev(uint8_t address, WriteBuffer *buffers, size_t cnt, bool stop) { + // logging is only enabled with vv level, if warnings are shown the caller + // should log them + if (!this->handle_) { + ESP_LOGVV(TAG, "i2c bus not initialized!"); + return ERROR_NOT_INITIALIZED; + } + + WriteVCmd cmd { address, buffers, cnt, stop }; + if (i2c_bus_run_cb(this->handle_, &i2c_writev, &cmd) != ESP_OK || cmd.code != ERROR_OK) { + ESP_LOGVV(TAG, "i2c writev failed!"); + return cmd.code; + } + return ERROR_OK; +} + + +/// Perform I2C bus recovery, see: +/// https://www.nxp.com/docs/en/user-guide/UM10204.pdf +/// https://www.analog.com/media/en/technical-documentation/application-notes/54305147357414AN686_0.pdf +void ADFI2CBus::recover_() { + ESP_LOGI(TAG, "Performing I2C bus recovery"); + + + const gpio_num_t scl_pin = static_cast(scl_pin_); + const gpio_num_t sda_pin = static_cast(sda_pin_); + + // For the upcoming operations, target for a 60kHz toggle frequency. + // 1000kHz is the maximum frequency for I2C running in standard-mode, + // but lower frequencies are not a problem. + // Note: the timing that is used here is chosen manually, to get + // results that are close to the timing that can be archieved by the + // implementation for the Arduino framework. + const auto half_period_usec = 7; + + // Configure SCL pin for open drain input/output, with a pull up resistor. + gpio_set_level(scl_pin, 1); + gpio_config_t scl_config{}; + scl_config.pin_bit_mask = 1ULL << scl_pin_; + scl_config.mode = GPIO_MODE_INPUT_OUTPUT_OD; + scl_config.pull_up_en = GPIO_PULLUP_ENABLE; + scl_config.pull_down_en = GPIO_PULLDOWN_DISABLE; + scl_config.intr_type = GPIO_INTR_DISABLE; + gpio_config(&scl_config); + + // Configure SDA pin for open drain input/output, with a pull up resistor. + gpio_set_level(sda_pin, 1); + gpio_config_t sda_conf{}; + sda_conf.pin_bit_mask = 1ULL << sda_pin_; + sda_conf.mode = GPIO_MODE_INPUT_OUTPUT_OD; + sda_conf.pull_up_en = GPIO_PULLUP_ENABLE; + sda_conf.pull_down_en = GPIO_PULLDOWN_DISABLE; + sda_conf.intr_type = GPIO_INTR_DISABLE; + gpio_config(&sda_conf); + + // If SCL is pulled low on the I2C bus, then some device is interfering + // with the SCL line. In that case, the I2C bus cannot be recovered. + delayMicroseconds(half_period_usec); + if (gpio_get_level(scl_pin) == 0) { + ESP_LOGE(TAG, "Recovery failed: SCL is held LOW on the I2C bus"); + recovery_result_ = RECOVERY_FAILED_SCL_LOW; + return; + } + + // From the specification: + // "If the data line (SDA) is stuck LOW, send nine clock pulses. The + // device that held the bus LOW should release it sometime within + // those nine clocks." + // We don't really have to detect if SDA is stuck low. We'll simply send + // nine clock pulses here, just in case SDA is stuck. Actual checks on + // the SDA line status will be done after the clock pulses. + for (auto i = 0; i < 9; i++) { + gpio_set_level(scl_pin, 0); + delayMicroseconds(half_period_usec); + gpio_set_level(scl_pin, 1); + delayMicroseconds(half_period_usec); + + // When SCL is kept LOW at this point, we might be looking at a device + // that applies clock stretching. Wait for the release of the SCL line, + // but not forever. There is no specification for the maximum allowed + // time. We yield and reset the WDT, so as to avoid triggering reset. + // No point in trying to recover the bus by forcing a uC reset. Bus + // should recover in a few ms or less else not likely to recovery at + // all. + auto wait = 250; + while (wait-- && gpio_get_level(scl_pin) == 0) { + App.feed_wdt(); + delayMicroseconds(half_period_usec * 2); + } + if (gpio_get_level(scl_pin) == 0) { + ESP_LOGE(TAG, "Recovery failed: SCL is held LOW during clock pulse cycle"); + recovery_result_ = RECOVERY_FAILED_SCL_LOW; + return; + } + } + + // By now, any stuck device ought to have sent all remaining bits of its + // transaction, meaning that it should have freed up the SDA line, resulting + // in SDA being pulled up. + if (gpio_get_level(sda_pin) == 0) { + ESP_LOGE(TAG, "Recovery failed: SDA is held LOW after clock pulse cycle"); + recovery_result_ = RECOVERY_FAILED_SDA_LOW; + return; + } + + // From the specification: + // "I2C-bus compatible devices must reset their bus logic on receipt of + // a START or repeated START condition such that they all anticipate + // the sending of a target address, even if these START conditions are + // not positioned according to the proper format." + // While the 9 clock pulses from above might have drained all bits of a + // single byte within a transaction, a device might have more bytes to + // transmit. So here we'll generate a START condition to snap the device + // out of this state. + // SCL and SDA are already high at this point, so we can generate a START + // condition by making the SDA signal LOW. + delayMicroseconds(half_period_usec); + gpio_set_level(sda_pin, 0); + + // From the specification: + // "A START condition immediately followed by a STOP condition (void + // message) is an illegal format. Many devices however are designed to + // operate properly under this condition." + // Finally, we'll bring the I2C bus into a starting state by generating + // a STOP condition. + delayMicroseconds(half_period_usec); + gpio_set_level(sda_pin, 1); + + recovery_result_ = RECOVERY_COMPLETED; +} + + +} // namespace i2c +} // namespace esphome + +#endif // USE_ESP_ADF diff --git a/esphome/components/i2c_adf/i2c_bus_esp_adf.h b/esphome/components/i2c_adf/i2c_bus_esp_adf.h new file mode 100644 index 0000000000..6d58dc2290 --- /dev/null +++ b/esphome/components/i2c_adf/i2c_bus_esp_adf.h @@ -0,0 +1,50 @@ +#pragma once +#include "esphome/core/defines.h" +#ifdef USE_ESP_ADF +#include +#include "esphome/components/i2c/i2c_bus.h" +#include "esphome/core/component.h" +#include + +namespace esphome { +namespace i2c { + +enum RecoveryCode { + RECOVERY_FAILED_SCL_LOW, + RECOVERY_FAILED_SDA_LOW, + RECOVERY_COMPLETED, +}; + +class ADFI2CBus : public I2CBus, public Component { + public: + void setup() override; + void dump_config() override; + ErrorCode readv(uint8_t address, ReadBuffer *buffers, size_t cnt) override; + ErrorCode writev(uint8_t address, WriteBuffer *buffers, size_t cnt, bool stop) override; + float get_setup_priority() const override { return setup_priority::BUS; } + + void set_scan(bool scan) { scan_ = scan; } + void set_sda_pin(uint8_t sda_pin) { sda_pin_ = sda_pin; } + void set_sda_pullup_enabled(bool sda_pullup_enabled) { sda_pullup_enabled_ = sda_pullup_enabled; } + void set_scl_pin(uint8_t scl_pin) { scl_pin_ = scl_pin; } + void set_scl_pullup_enabled(bool scl_pullup_enabled) { scl_pullup_enabled_ = scl_pullup_enabled; } + void set_frequency(uint32_t frequency) { frequency_ = frequency; } + + private: + void recover_(); + RecoveryCode recovery_result_; + + protected: + uint8_t sda_pin_; + bool sda_pullup_enabled_; + uint8_t scl_pin_; + bool scl_pullup_enabled_; + uint32_t frequency_; + + i2c_bus_t handle_; +}; + +} // namespace i2c +} // namespace esphome + +#endif // USE_ESP_IDF