1 // Copyright 2015-2020 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef _DRIVER_I2C_H_ 16 #define _DRIVER_I2C_H_ 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 #include <esp_types.h> 23 #include "esp_err.h" 24 #include "esp_intr_alloc.h" 25 #include "esp_osal/esp_osal.h" 26 #include "esp_osal/semphr.h" 27 #include "esp_osal/task.h" 28 #include "esp_osal/queue.h" 29 #include "ringbuf.h" 30 #include "driver/gpio.h" 31 #include "soc/soc_caps.h" 32 #include "hal/i2c_types.h" 33 34 #define I2C_APB_CLK_FREQ APB_CLK_FREQ /*!< I2C source clock is APB clock, 80MHz */ 35 36 #define I2C_NUM_0 (0) /*!< I2C port 0 */ 37 #define I2C_NUM_1 (1) /*!< I2C port 1 */ 38 #define I2C_NUM_MAX (SOC_I2C_NUM) /*!< I2C port max */ 39 40 typedef void *i2c_cmd_handle_t; /*!< I2C command handle */ 41 42 /** 43 * @brief I2C driver install 44 * 45 * @param i2c_num I2C port number 46 * @param mode I2C mode( master or slave ) 47 * @param slv_rx_buf_len receiving buffer size for slave mode 48 * @note 49 * Only slave mode will use this value, driver will ignore this value in master mode. 50 * @param slv_tx_buf_len sending buffer size for slave mode 51 * @note 52 * Only slave mode will use this value, driver will ignore this value in master mode. 53 * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) 54 * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. 55 * @note 56 * In master mode, if the cache is likely to be disabled(such as write flash) and the slave is time-sensitive, 57 * `ESP_INTR_FLAG_IRAM` is suggested to be used. In this case, please use the memory allocated from internal RAM in i2c read and write function, 58 * because we can not access the psram(if psram is enabled) in interrupt handle function when cache is disabled. 59 * 60 * @return 61 * - ESP_OK Success 62 * - ESP_ERR_INVALID_ARG Parameter error 63 * - ESP_FAIL Driver install error 64 */ 65 esp_err_t i2c_driver_install(i2c_port_t i2c_num, i2c_mode_t mode, size_t slv_rx_buf_len, size_t slv_tx_buf_len, int intr_alloc_flags); 66 67 /** 68 * @brief I2C driver delete 69 * 70 * @note This function does not guarantee thread safety. 71 * Please make sure that no thread will continuously hold semaphores before calling the delete function. 72 * 73 * @param i2c_num I2C port number 74 * 75 * @return 76 * - ESP_OK Success 77 * - ESP_ERR_INVALID_ARG Parameter error 78 */ 79 esp_err_t i2c_driver_delete(i2c_port_t i2c_num); 80 81 /** 82 * @brief I2C parameter initialization 83 * 84 * @param i2c_num I2C port number 85 * @param i2c_conf pointer to I2C parameter settings 86 * 87 * @return 88 * - ESP_OK Success 89 * - ESP_ERR_INVALID_ARG Parameter error 90 */ 91 esp_err_t i2c_param_config(i2c_port_t i2c_num, const i2c_config_t *i2c_conf); 92 93 /** 94 * @brief reset I2C tx hardware fifo 95 * 96 * @param i2c_num I2C port number 97 * 98 * @return 99 * - ESP_OK Success 100 * - ESP_ERR_INVALID_ARG Parameter error 101 */ 102 esp_err_t i2c_reset_tx_fifo(i2c_port_t i2c_num); 103 104 /** 105 * @brief reset I2C rx fifo 106 * 107 * @param i2c_num I2C port number 108 * 109 * @return 110 * - ESP_OK Success 111 * - ESP_ERR_INVALID_ARG Parameter error 112 */ 113 esp_err_t i2c_reset_rx_fifo(i2c_port_t i2c_num); 114 115 /** 116 * @brief I2C isr handler register 117 * 118 * @param i2c_num I2C port number 119 * @param fn isr handler function 120 * @param arg parameter for isr handler function 121 * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) 122 * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. 123 * @param handle handle return from esp_intr_alloc. 124 * 125 * @return 126 * - ESP_OK Success 127 * - ESP_ERR_INVALID_ARG Parameter error 128 */ 129 esp_err_t i2c_isr_register(i2c_port_t i2c_num, void (*fn)(void *), void *arg, int intr_alloc_flags, intr_handle_t *handle); 130 131 /** 132 * @brief to delete and free I2C isr. 133 * 134 * @param handle handle of isr. 135 * 136 * @return 137 * - ESP_OK Success 138 * - ESP_ERR_INVALID_ARG Parameter error 139 */ 140 esp_err_t i2c_isr_free(intr_handle_t handle); 141 142 /** 143 * @brief Configure GPIO signal for I2C sck and sda 144 * 145 * @param i2c_num I2C port number 146 * @param sda_io_num GPIO number for I2C sda signal 147 * @param scl_io_num GPIO number for I2C scl signal 148 * @param sda_pullup_en Whether to enable the internal pullup for sda pin 149 * @param scl_pullup_en Whether to enable the internal pullup for scl pin 150 * @param mode I2C mode 151 * 152 * @return 153 * - ESP_OK Success 154 * - ESP_ERR_INVALID_ARG Parameter error 155 */ 156 esp_err_t i2c_set_pin(i2c_port_t i2c_num, int sda_io_num, int scl_io_num, 157 bool sda_pullup_en, bool scl_pullup_en, i2c_mode_t mode); 158 159 /** 160 * @brief Create and init I2C command link 161 * @note 162 * Before we build I2C command link, we need to call i2c_cmd_link_create() to create 163 * a command link. 164 * After we finish sending the commands, we need to call i2c_cmd_link_delete() to 165 * release and return the resources. 166 * 167 * @return i2c command link handler 168 */ 169 i2c_cmd_handle_t i2c_cmd_link_create(void); 170 171 /** 172 * @brief Free I2C command link 173 * @note 174 * Before we build I2C command link, we need to call i2c_cmd_link_create() to create 175 * a command link. 176 * After we finish sending the commands, we need to call i2c_cmd_link_delete() to 177 * release and return the resources. 178 * 179 * @param cmd_handle I2C command handle 180 */ 181 void i2c_cmd_link_delete(i2c_cmd_handle_t cmd_handle); 182 183 /** 184 * @brief Queue command for I2C master to generate a start signal 185 * @note 186 * Only call this function in I2C master mode 187 * Call i2c_master_cmd_begin() to send all queued commands 188 * 189 * @param cmd_handle I2C cmd link 190 * 191 * @return 192 * - ESP_OK Success 193 * - ESP_ERR_INVALID_ARG Parameter error 194 */ 195 esp_err_t i2c_master_start(i2c_cmd_handle_t cmd_handle); 196 197 /** 198 * @brief Queue command for I2C master to write one byte to I2C bus 199 * @note 200 * Only call this function in I2C master mode 201 * Call i2c_master_cmd_begin() to send all queued commands 202 * 203 * @param cmd_handle I2C cmd link 204 * @param data I2C one byte command to write to bus 205 * @param ack_en enable ack check for master 206 * 207 * @return 208 * - ESP_OK Success 209 * - ESP_ERR_INVALID_ARG Parameter error 210 */ 211 esp_err_t i2c_master_write_byte(i2c_cmd_handle_t cmd_handle, uint8_t data, bool ack_en); 212 213 /** 214 * @brief Queue command for I2C master to write buffer to I2C bus 215 * @note 216 * Only call this function in I2C master mode 217 * Call i2c_master_cmd_begin() to send all queued commands 218 * 219 * @param cmd_handle I2C cmd link 220 * @param data data to send 221 * @note 222 * If the psram is enabled and intr_flag is `ESP_INTR_FLAG_IRAM`, please use the memory allocated from internal RAM. 223 * @param data_len data length 224 * @param ack_en enable ack check for master 225 * 226 * @return 227 * - ESP_OK Success 228 * - ESP_ERR_INVALID_ARG Parameter error 229 */ 230 esp_err_t i2c_master_write(i2c_cmd_handle_t cmd_handle, const uint8_t *data, size_t data_len, bool ack_en); 231 232 /** 233 * @brief Queue command for I2C master to read one byte from I2C bus 234 * @note 235 * Only call this function in I2C master mode 236 * Call i2c_master_cmd_begin() to send all queued commands 237 * 238 * @param cmd_handle I2C cmd link 239 * @param data pointer accept the data byte 240 * @note 241 * If the psram is enabled and intr_flag is `ESP_INTR_FLAG_IRAM`, please use the memory allocated from internal RAM. 242 * @param ack ack value for read command 243 * 244 * @return 245 * - ESP_OK Success 246 * - ESP_ERR_INVALID_ARG Parameter error 247 */ 248 esp_err_t i2c_master_read_byte(i2c_cmd_handle_t cmd_handle, uint8_t *data, i2c_ack_type_t ack); 249 250 /** 251 * @brief Queue command for I2C master to read data from I2C bus 252 * @note 253 * Only call this function in I2C master mode 254 * Call i2c_master_cmd_begin() to send all queued commands 255 * 256 * @param cmd_handle I2C cmd link 257 * @param data data buffer to accept the data from bus 258 * @note 259 * If the psram is enabled and intr_flag is `ESP_INTR_FLAG_IRAM`, please use the memory allocated from internal RAM. 260 * @param data_len read data length 261 * @param ack ack value for read command 262 * 263 * @return 264 * - ESP_OK Success 265 * - ESP_ERR_INVALID_ARG Parameter error 266 */ 267 esp_err_t i2c_master_read(i2c_cmd_handle_t cmd_handle, uint8_t *data, size_t data_len, i2c_ack_type_t ack); 268 269 /** 270 * @brief Queue command for I2C master to generate a stop signal 271 * @note 272 * Only call this function in I2C master mode 273 * Call i2c_master_cmd_begin() to send all queued commands 274 * 275 * @param cmd_handle I2C cmd link 276 * 277 * @return 278 * - ESP_OK Success 279 * - ESP_ERR_INVALID_ARG Parameter error 280 */ 281 esp_err_t i2c_master_stop(i2c_cmd_handle_t cmd_handle); 282 283 /** 284 * @brief I2C master send queued commands. 285 * This function will trigger sending all queued commands. 286 * The task will be blocked until all the commands have been sent out. 287 * The I2C APIs are not thread-safe, if you want to use one I2C port in different tasks, 288 * you need to take care of the multi-thread issue. 289 * @note 290 * Only call this function in I2C master mode 291 * 292 * @param i2c_num I2C port number 293 * @param cmd_handle I2C command handler 294 * @param ticks_to_wait maximum wait ticks. 295 * 296 * @return 297 * - ESP_OK Success 298 * - ESP_ERR_INVALID_ARG Parameter error 299 * - ESP_FAIL Sending command error, slave doesn't ACK the transfer. 300 * - ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode. 301 * - ESP_ERR_TIMEOUT Operation timeout because the bus is busy. 302 */ 303 esp_err_t i2c_master_cmd_begin(i2c_port_t i2c_num, i2c_cmd_handle_t cmd_handle, TickType_t ticks_to_wait); 304 305 /** 306 * @brief I2C slave write data to internal ringbuffer, when tx fifo empty, isr will fill the hardware 307 * fifo from the internal ringbuffer 308 * @note 309 * Only call this function in I2C slave mode 310 * 311 * @param i2c_num I2C port number 312 * @param data data pointer to write into internal buffer 313 * @param size data size 314 * @param ticks_to_wait Maximum waiting ticks 315 * 316 * @return 317 * - ESP_FAIL(-1) Parameter error 318 * - Others(>=0) The number of data bytes that pushed to the I2C slave buffer. 319 */ 320 int i2c_slave_write_buffer(i2c_port_t i2c_num, const uint8_t *data, int size, TickType_t ticks_to_wait); 321 322 /** 323 * @brief I2C slave read data from internal buffer. When I2C slave receive data, isr will copy received data 324 * from hardware rx fifo to internal ringbuffer. Then users can read from internal ringbuffer. 325 * @note 326 * Only call this function in I2C slave mode 327 * 328 * @param i2c_num I2C port number 329 * @param data data pointer to accept data from internal buffer 330 * @param max_size Maximum data size to read 331 * @param ticks_to_wait Maximum waiting ticks 332 * 333 * @return 334 * - ESP_FAIL(-1) Parameter error 335 * - Others(>=0) The number of data bytes that read from I2C slave buffer. 336 */ 337 int i2c_slave_read_buffer(i2c_port_t i2c_num, uint8_t *data, size_t max_size, TickType_t ticks_to_wait); 338 339 /** 340 * @brief set I2C master clock period 341 * 342 * @param i2c_num I2C port number 343 * @param high_period clock cycle number during SCL is high level, high_period is a 14 bit value 344 * @param low_period clock cycle number during SCL is low level, low_period is a 14 bit value 345 * 346 * @return 347 * - ESP_OK Success 348 * - ESP_ERR_INVALID_ARG Parameter error 349 */ 350 esp_err_t i2c_set_period(i2c_port_t i2c_num, int high_period, int low_period); 351 352 /** 353 * @brief get I2C master clock period 354 * 355 * @param i2c_num I2C port number 356 * @param high_period pointer to get clock cycle number during SCL is high level, will get a 14 bit value 357 * @param low_period pointer to get clock cycle number during SCL is low level, will get a 14 bit value 358 * 359 * @return 360 * - ESP_OK Success 361 * - ESP_ERR_INVALID_ARG Parameter error 362 */ 363 esp_err_t i2c_get_period(i2c_port_t i2c_num, int *high_period, int *low_period); 364 365 /** 366 * @brief enable hardware filter on I2C bus 367 * Sometimes the I2C bus is disturbed by high frequency noise(about 20ns), or the rising edge of 368 * the SCL clock is very slow, these may cause the master state machine broken. enable hardware 369 * filter can filter out high frequency interference and make the master more stable. 370 * @note 371 * Enable filter will slow the SCL clock. 372 * 373 * @param i2c_num I2C port number 374 * @param cyc_num the APB cycles need to be filtered(0<= cyc_num <=7). 375 * When the period of a pulse is less than cyc_num * APB_cycle, the I2C controller will ignore this pulse. 376 * 377 * @return 378 * - ESP_OK Success 379 * - ESP_ERR_INVALID_ARG Parameter error 380 */ 381 esp_err_t i2c_filter_enable(i2c_port_t i2c_num, uint8_t cyc_num); 382 383 /** 384 * @brief disable filter on I2C bus 385 * 386 * @param i2c_num I2C port number 387 * 388 * @return 389 * - ESP_OK Success 390 * - ESP_ERR_INVALID_ARG Parameter error 391 */ 392 esp_err_t i2c_filter_disable(i2c_port_t i2c_num); 393 394 /** 395 * @brief set I2C master start signal timing 396 * 397 * @param i2c_num I2C port number 398 * @param setup_time clock number between the falling-edge of SDA and rising-edge of SCL for start mark, it's a 10-bit value. 399 * @param hold_time clock num between the falling-edge of SDA and falling-edge of SCL for start mark, it's a 10-bit value. 400 * 401 * @return 402 * - ESP_OK Success 403 * - ESP_ERR_INVALID_ARG Parameter error 404 */ 405 esp_err_t i2c_set_start_timing(i2c_port_t i2c_num, int setup_time, int hold_time); 406 407 /** 408 * @brief get I2C master start signal timing 409 * 410 * @param i2c_num I2C port number 411 * @param setup_time pointer to get setup time 412 * @param hold_time pointer to get hold time 413 * 414 * @return 415 * - ESP_OK Success 416 * - ESP_ERR_INVALID_ARG Parameter error 417 */ 418 esp_err_t i2c_get_start_timing(i2c_port_t i2c_num, int *setup_time, int *hold_time); 419 420 /** 421 * @brief set I2C master stop signal timing 422 * 423 * @param i2c_num I2C port number 424 * @param setup_time clock num between the rising-edge of SCL and the rising-edge of SDA, it's a 10-bit value. 425 * @param hold_time clock number after the STOP bit's rising-edge, it's a 14-bit value. 426 * 427 * @return 428 * - ESP_OK Success 429 * - ESP_ERR_INVALID_ARG Parameter error 430 */ 431 esp_err_t i2c_set_stop_timing(i2c_port_t i2c_num, int setup_time, int hold_time); 432 433 /** 434 * @brief get I2C master stop signal timing 435 * 436 * @param i2c_num I2C port number 437 * @param setup_time pointer to get setup time. 438 * @param hold_time pointer to get hold time. 439 * 440 * @return 441 * - ESP_OK Success 442 * - ESP_ERR_INVALID_ARG Parameter error 443 */ 444 esp_err_t i2c_get_stop_timing(i2c_port_t i2c_num, int *setup_time, int *hold_time); 445 446 /** 447 * @brief set I2C data signal timing 448 * 449 * @param i2c_num I2C port number 450 * @param sample_time clock number I2C used to sample data on SDA after the rising-edge of SCL, it's a 10-bit value 451 * @param hold_time clock number I2C used to hold the data after the falling-edge of SCL, it's a 10-bit value 452 * 453 * @return 454 * - ESP_OK Success 455 * - ESP_ERR_INVALID_ARG Parameter error 456 */ 457 esp_err_t i2c_set_data_timing(i2c_port_t i2c_num, int sample_time, int hold_time); 458 459 /** 460 * @brief get I2C data signal timing 461 * 462 * @param i2c_num I2C port number 463 * @param sample_time pointer to get sample time 464 * @param hold_time pointer to get hold time 465 * 466 * @return 467 * - ESP_OK Success 468 * - ESP_ERR_INVALID_ARG Parameter error 469 */ 470 esp_err_t i2c_get_data_timing(i2c_port_t i2c_num, int *sample_time, int *hold_time); 471 472 /** 473 * @brief set I2C timeout value 474 * @param i2c_num I2C port number 475 * @param timeout timeout value for I2C bus (unit: APB 80Mhz clock cycle) 476 * @return 477 * - ESP_OK Success 478 * - ESP_ERR_INVALID_ARG Parameter error 479 */ 480 esp_err_t i2c_set_timeout(i2c_port_t i2c_num, int timeout); 481 482 /** 483 * @brief get I2C timeout value 484 * @param i2c_num I2C port number 485 * @param timeout pointer to get timeout value 486 * @return 487 * - ESP_OK Success 488 * - ESP_ERR_INVALID_ARG Parameter error 489 */ 490 esp_err_t i2c_get_timeout(i2c_port_t i2c_num, int *timeout); 491 492 /** 493 * @brief set I2C data transfer mode 494 * 495 * @param i2c_num I2C port number 496 * @param tx_trans_mode I2C sending data mode 497 * @param rx_trans_mode I2C receving data mode 498 * 499 * @return 500 * - ESP_OK Success 501 * - ESP_ERR_INVALID_ARG Parameter error 502 */ 503 esp_err_t i2c_set_data_mode(i2c_port_t i2c_num, i2c_trans_mode_t tx_trans_mode, i2c_trans_mode_t rx_trans_mode); 504 505 /** 506 * @brief get I2C data transfer mode 507 * 508 * @param i2c_num I2C port number 509 * @param tx_trans_mode pointer to get I2C sending data mode 510 * @param rx_trans_mode pointer to get I2C receiving data mode 511 * 512 * @return 513 * - ESP_OK Success 514 * - ESP_ERR_INVALID_ARG Parameter error 515 */ 516 esp_err_t i2c_get_data_mode(i2c_port_t i2c_num, i2c_trans_mode_t *tx_trans_mode, i2c_trans_mode_t *rx_trans_mode); 517 518 #ifdef __cplusplus 519 } 520 #endif 521 522 #endif /*_DRIVER_I2C_H_*/ 523