ESPHome  2022.8.0
i2c_bus_esp_idf.cpp
Go to the documentation of this file.
1 #ifdef USE_ESP_IDF
2 
3 #include "i2c_bus_esp_idf.h"
4 #include "esphome/core/hal.h"
5 #include "esphome/core/log.h"
6 #include "esphome/core/helpers.h"
7 #include <cstring>
8 
9 namespace esphome {
10 namespace i2c {
11 
12 static const char *const TAG = "i2c.idf";
13 
15  static i2c_port_t next_port = 0;
16  port_ = next_port++;
17 
18  recover_();
19 
20  i2c_config_t conf{};
21  memset(&conf, 0, sizeof(conf));
22  conf.mode = I2C_MODE_MASTER;
23  conf.sda_io_num = sda_pin_;
24  conf.sda_pullup_en = sda_pullup_enabled_;
25  conf.scl_io_num = scl_pin_;
26  conf.scl_pullup_en = scl_pullup_enabled_;
27  conf.master.clk_speed = frequency_;
28  esp_err_t err = i2c_param_config(port_, &conf);
29  if (err != ESP_OK) {
30  ESP_LOGW(TAG, "i2c_param_config failed: %s", esp_err_to_name(err));
31  this->mark_failed();
32  return;
33  }
34  err = i2c_driver_install(port_, I2C_MODE_MASTER, 0, 0, ESP_INTR_FLAG_IRAM);
35  if (err != ESP_OK) {
36  ESP_LOGW(TAG, "i2c_driver_install failed: %s", esp_err_to_name(err));
37  this->mark_failed();
38  return;
39  }
40  initialized_ = true;
41  if (this->scan_) {
42  ESP_LOGV(TAG, "Scanning i2c bus for active devices...");
43  this->i2c_scan_();
44  }
45 }
47  ESP_LOGCONFIG(TAG, "I2C Bus:");
48  ESP_LOGCONFIG(TAG, " SDA Pin: GPIO%u", this->sda_pin_);
49  ESP_LOGCONFIG(TAG, " SCL Pin: GPIO%u", this->scl_pin_);
50  ESP_LOGCONFIG(TAG, " Frequency: %u Hz", this->frequency_);
51  switch (this->recovery_result_) {
52  case RECOVERY_COMPLETED:
53  ESP_LOGCONFIG(TAG, " Recovery: bus successfully recovered");
54  break;
56  ESP_LOGCONFIG(TAG, " Recovery: failed, SCL is held low on the bus");
57  break;
59  ESP_LOGCONFIG(TAG, " Recovery: failed, SDA is held low on the bus");
60  break;
61  }
62  if (this->scan_) {
63  ESP_LOGI(TAG, "Results from i2c bus scan:");
64  if (scan_results_.empty()) {
65  ESP_LOGI(TAG, "Found no i2c devices!");
66  } else {
67  for (const auto &s : scan_results_) {
68  if (s.second) {
69  ESP_LOGI(TAG, "Found i2c device at address 0x%02X", s.first);
70  } else {
71  ESP_LOGE(TAG, "Unknown error at address 0x%02X", s.first);
72  }
73  }
74  }
75  }
76 }
77 
78 ErrorCode IDFI2CBus::readv(uint8_t address, ReadBuffer *buffers, size_t cnt) {
79  // logging is only enabled with vv level, if warnings are shown the caller
80  // should log them
81  if (!initialized_) {
82  ESP_LOGVV(TAG, "i2c bus not initialized!");
83  return ERROR_NOT_INITIALIZED;
84  }
85  i2c_cmd_handle_t cmd = i2c_cmd_link_create();
86  esp_err_t err = i2c_master_start(cmd);
87  if (err != ESP_OK) {
88  ESP_LOGVV(TAG, "RX from %02X master start failed: %s", address, esp_err_to_name(err));
89  i2c_cmd_link_delete(cmd);
90  return ERROR_UNKNOWN;
91  }
92  err = i2c_master_write_byte(cmd, (address << 1) | I2C_MASTER_READ, true);
93  if (err != ESP_OK) {
94  ESP_LOGVV(TAG, "RX from %02X address write failed: %s", address, esp_err_to_name(err));
95  i2c_cmd_link_delete(cmd);
96  return ERROR_UNKNOWN;
97  }
98  for (size_t i = 0; i < cnt; i++) {
99  const auto &buf = buffers[i];
100  if (buf.len == 0)
101  continue;
102  err = i2c_master_read(cmd, buf.data, buf.len, i == cnt - 1 ? I2C_MASTER_LAST_NACK : I2C_MASTER_ACK);
103  if (err != ESP_OK) {
104  ESP_LOGVV(TAG, "RX from %02X data read failed: %s", address, esp_err_to_name(err));
105  i2c_cmd_link_delete(cmd);
106  return ERROR_UNKNOWN;
107  }
108  }
109  err = i2c_master_stop(cmd);
110  if (err != ESP_OK) {
111  ESP_LOGVV(TAG, "RX from %02X stop failed: %s", address, esp_err_to_name(err));
112  i2c_cmd_link_delete(cmd);
113  return ERROR_UNKNOWN;
114  }
115  err = i2c_master_cmd_begin(port_, cmd, 20 / portTICK_PERIOD_MS);
116  i2c_cmd_link_delete(cmd);
117  if (err == ESP_FAIL) {
118  // transfer not acked
119  ESP_LOGVV(TAG, "RX from %02X failed: not acked", address);
120  return ERROR_NOT_ACKNOWLEDGED;
121  } else if (err == ESP_ERR_TIMEOUT) {
122  ESP_LOGVV(TAG, "RX from %02X failed: timeout", address);
123  return ERROR_TIMEOUT;
124  } else if (err != ESP_OK) {
125  ESP_LOGVV(TAG, "RX from %02X failed: %s", address, esp_err_to_name(err));
126  return ERROR_UNKNOWN;
127  }
128 
129 #ifdef ESPHOME_LOG_HAS_VERY_VERBOSE
130  char debug_buf[4];
131  std::string debug_hex;
132 
133  for (size_t i = 0; i < cnt; i++) {
134  const auto &buf = buffers[i];
135  for (size_t j = 0; j < buf.len; j++) {
136  snprintf(debug_buf, sizeof(debug_buf), "%02X", buf.data[j]);
137  debug_hex += debug_buf;
138  }
139  }
140  ESP_LOGVV(TAG, "0x%02X RX %s", address, debug_hex.c_str());
141 #endif
142 
143  return ERROR_OK;
144 }
145 ErrorCode IDFI2CBus::writev(uint8_t address, WriteBuffer *buffers, size_t cnt, bool stop) {
146  // logging is only enabled with vv level, if warnings are shown the caller
147  // should log them
148  if (!initialized_) {
149  ESP_LOGVV(TAG, "i2c bus not initialized!");
150  return ERROR_NOT_INITIALIZED;
151  }
152 
153 #ifdef ESPHOME_LOG_HAS_VERY_VERBOSE
154  char debug_buf[4];
155  std::string debug_hex;
156 
157  for (size_t i = 0; i < cnt; i++) {
158  const auto &buf = buffers[i];
159  for (size_t j = 0; j < buf.len; j++) {
160  snprintf(debug_buf, sizeof(debug_buf), "%02X", buf.data[j]);
161  debug_hex += debug_buf;
162  }
163  }
164  ESP_LOGVV(TAG, "0x%02X TX %s", address, debug_hex.c_str());
165 #endif
166 
167  i2c_cmd_handle_t cmd = i2c_cmd_link_create();
168  esp_err_t err = i2c_master_start(cmd);
169  if (err != ESP_OK) {
170  ESP_LOGVV(TAG, "TX to %02X master start failed: %s", address, esp_err_to_name(err));
171  i2c_cmd_link_delete(cmd);
172  return ERROR_UNKNOWN;
173  }
174  err = i2c_master_write_byte(cmd, (address << 1) | I2C_MASTER_WRITE, true);
175  if (err != ESP_OK) {
176  ESP_LOGVV(TAG, "TX to %02X address write failed: %s", address, esp_err_to_name(err));
177  i2c_cmd_link_delete(cmd);
178  return ERROR_UNKNOWN;
179  }
180  for (size_t i = 0; i < cnt; i++) {
181  const auto &buf = buffers[i];
182  if (buf.len == 0)
183  continue;
184  err = i2c_master_write(cmd, buf.data, buf.len, true);
185  if (err != ESP_OK) {
186  ESP_LOGVV(TAG, "TX to %02X data write failed: %s", address, esp_err_to_name(err));
187  i2c_cmd_link_delete(cmd);
188  return ERROR_UNKNOWN;
189  }
190  }
191  err = i2c_master_stop(cmd);
192  if (err != ESP_OK) {
193  ESP_LOGVV(TAG, "TX to %02X master stop failed: %s", address, esp_err_to_name(err));
194  i2c_cmd_link_delete(cmd);
195  return ERROR_UNKNOWN;
196  }
197  err = i2c_master_cmd_begin(port_, cmd, 20 / portTICK_PERIOD_MS);
198  i2c_cmd_link_delete(cmd);
199  if (err == ESP_FAIL) {
200  // transfer not acked
201  ESP_LOGVV(TAG, "TX to %02X failed: not acked", address);
202  return ERROR_NOT_ACKNOWLEDGED;
203  } else if (err == ESP_ERR_TIMEOUT) {
204  ESP_LOGVV(TAG, "TX to %02X failed: timeout", address);
205  return ERROR_TIMEOUT;
206  } else if (err != ESP_OK) {
207  ESP_LOGVV(TAG, "TX to %02X failed: %s", address, esp_err_to_name(err));
208  return ERROR_UNKNOWN;
209  }
210  return ERROR_OK;
211 }
212 
216 void IDFI2CBus::recover_() {
217  ESP_LOGI(TAG, "Performing I2C bus recovery");
218 
219  const gpio_num_t scl_pin = static_cast<gpio_num_t>(scl_pin_);
220  const gpio_num_t sda_pin = static_cast<gpio_num_t>(sda_pin_);
221 
222  // For the upcoming operations, target for a 60kHz toggle frequency.
223  // 1000kHz is the maximum frequency for I2C running in standard-mode,
224  // but lower frequencies are not a problem.
225  // Note: the timing that is used here is chosen manually, to get
226  // results that are close to the timing that can be archieved by the
227  // implementation for the Arduino framework.
228  const auto half_period_usec = 7;
229 
230  // Configure SCL pin for open drain input/output, with a pull up resistor.
231  gpio_set_level(scl_pin, 1);
232  gpio_config_t scl_config{};
233  scl_config.pin_bit_mask = 1ULL << scl_pin_;
234  scl_config.mode = GPIO_MODE_INPUT_OUTPUT_OD;
235  scl_config.pull_up_en = GPIO_PULLUP_ENABLE;
236  scl_config.pull_down_en = GPIO_PULLDOWN_DISABLE;
237  scl_config.intr_type = GPIO_INTR_DISABLE;
238  gpio_config(&scl_config);
239 
240  // Configure SDA pin for open drain input/output, with a pull up resistor.
241  gpio_set_level(sda_pin, 1);
242  gpio_config_t sda_conf{};
243  sda_conf.pin_bit_mask = 1ULL << sda_pin_;
244  sda_conf.mode = GPIO_MODE_INPUT_OUTPUT_OD;
245  sda_conf.pull_up_en = GPIO_PULLUP_ENABLE;
246  sda_conf.pull_down_en = GPIO_PULLDOWN_DISABLE;
247  sda_conf.intr_type = GPIO_INTR_DISABLE;
248  gpio_config(&sda_conf);
249 
250  // If SCL is pulled low on the I2C bus, then some device is interfering
251  // with the SCL line. In that case, the I2C bus cannot be recovered.
252  delayMicroseconds(half_period_usec);
253  if (gpio_get_level(scl_pin) == 0) {
254  ESP_LOGE(TAG, "Recovery failed: SCL is held LOW on the I2C bus");
255  recovery_result_ = RECOVERY_FAILED_SCL_LOW;
256  return;
257  }
258 
259  // From the specification:
260  // "If the data line (SDA) is stuck LOW, send nine clock pulses. The
261  // device that held the bus LOW should release it sometime within
262  // those nine clocks."
263  // We don't really have to detect if SDA is stuck low. We'll simply send
264  // nine clock pulses here, just in case SDA is stuck. Actual checks on
265  // the SDA line status will be done after the clock pulses.
266  for (auto i = 0; i < 9; i++) {
267  gpio_set_level(scl_pin, 0);
268  delayMicroseconds(half_period_usec);
269  gpio_set_level(scl_pin, 1);
270  delayMicroseconds(half_period_usec);
271 
272  // When SCL is kept LOW at this point, we might be looking at a device
273  // that applies clock stretching. Wait for the release of the SCL line,
274  // but not forever. There is no specification for the maximum allowed
275  // time. We'll stick to 500ms here.
276  auto wait = 20;
277  while (wait-- && gpio_get_level(scl_pin) == 0) {
278  delay(25);
279  }
280  if (gpio_get_level(scl_pin) == 0) {
281  ESP_LOGE(TAG, "Recovery failed: SCL is held LOW during clock pulse cycle");
282  recovery_result_ = RECOVERY_FAILED_SCL_LOW;
283  return;
284  }
285  }
286 
287  // By now, any stuck device ought to have sent all remaining bits of its
288  // transaction, meaning that it should have freed up the SDA line, resulting
289  // in SDA being pulled up.
290  if (gpio_get_level(sda_pin) == 0) {
291  ESP_LOGE(TAG, "Recovery failed: SDA is held LOW after clock pulse cycle");
292  recovery_result_ = RECOVERY_FAILED_SDA_LOW;
293  return;
294  }
295 
296  // From the specification:
297  // "I2C-bus compatible devices must reset their bus logic on receipt of
298  // a START or repeated START condition such that they all anticipate
299  // the sending of a target address, even if these START conditions are
300  // not positioned according to the proper format."
301  // While the 9 clock pulses from above might have drained all bits of a
302  // single byte within a transaction, a device might have more bytes to
303  // transmit. So here we'll generate a START condition to snap the device
304  // out of this state.
305  // SCL and SDA are already high at this point, so we can generate a START
306  // condition by making the SDA signal LOW.
307  delayMicroseconds(half_period_usec);
308  gpio_set_level(sda_pin, 0);
309 
310  // From the specification:
311  // "A START condition immediately followed by a STOP condition (void
312  // message) is an illegal format. Many devices however are designed to
313  // operate properly under this condition."
314  // Finally, we'll bring the I2C bus into a starting state by generating
315  // a STOP condition.
316  delayMicroseconds(half_period_usec);
317  gpio_set_level(sda_pin, 1);
318 
319  recovery_result_ = RECOVERY_COMPLETED;
320 }
321 
322 } // namespace i2c
323 } // namespace esphome
324 
325 #endif // USE_ESP_IDF
void dump_config() override
std::vector< std::pair< uint8_t, bool > > scan_results_
Definition: i2c_bus.h:64
ErrorCode writev(uint8_t address, WriteBuffer *buffers, size_t cnt, bool stop) override
ErrorCode readv(uint8_t address, ReadBuffer *buffers, size_t cnt) override
virtual void mark_failed()
Mark this component as failed.
Definition: component.cpp:111
Definition: a4988.cpp:4
void IRAM_ATTR HOT delayMicroseconds(uint32_t us)
Definition: core.cpp:29
stm32_cmd_t * cmd
Definition: stm32flash.h:96
void IRAM_ATTR HOT delay(uint32_t ms)
Definition: core.cpp:27