i2c_master.h

Go to the documentation of this file.

/*****************************************************************************
 *   Copyright(C)2009-2026 by VSF Team                                       *
 *                                                                           *
 *  Licensed under the Apache License, Version 2.0 (the "License");          *
 *  you may not use this file except in compliance with the License.         *
 *  You may obtain a copy of the License at                                  *
 *                                                                           *
 *     http://www.apache.org/licenses/LICENSE-2.0                            *
 *                                                                           *
 *  Unless required by applicable law or agreed to in writing, software      *
 *  distributed under the License is distributed on an "AS IS" BASIS,        *
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
 *  See the License for the specific language governing permissions and      *
 *  limitations under the License.                                           *
 *                                                                           *
 ****************************************************************************/
 
/*
 * Clean-room re-implementation of ESP-IDF "driver/i2c_master.h" (new driver,
 * v5.2+).
 *
 * Authored from ESP-IDF v5.2 public API only. No code copied from the
 * ESP-IDF source tree. The VSF port bridges onto
 *
 *     hal/driver/common/template/vsf_template_i2c.h
 *
 * via a caller-supplied pool of vsf_i2c_t * instances (see
 *     vsf_espidf_cfg_t::i2c
 * ).
 *
 * The new ESP-IDF I2C driver uses a bus-device model:
 *   - Bus  = one I2C controller (port 0 / 1), mapped to a vsf_i2c_t*.
 *   - Device = a soft handle carrying (bus, address, speed).
 *
 * Only Master mode is implemented (matches the vast majority of ESP-IDF
 * application use cases). Slave mode can be added in a future i2c_slave.h.
 *
 * All transfer functions are synchronous / blocking, matching ESP-IDF
 * semantics. The timeout parameter is forwarded as a FreeRTOS tick limit.
 */
 
#ifndef __VSF_ESPIDF_DRIVER_I2C_MASTER_H__
#define __VSF_ESPIDF_DRIVER_I2C_MASTER_H__
 
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
 
#include "esp_err.h"
#include "driver/i2c_types.h"
#include "driver/gpio.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*============================ TYPES =========================================*/
 
typedef struct i2c_master_bus_t *i2c_master_bus_handle_t;
 
typedef struct i2c_master_dev_t *i2c_master_dev_handle_t;
 
typedef struct {
    i2c_clock_source_t  clk_source;         
    i2c_port_num_t      i2c_port;           
    gpio_num_t          scl_io_num;         
    gpio_num_t          sda_io_num;         
    uint8_t             glitch_ignore_cnt;  
    int                 intr_priority;      
    size_t              trans_queue_depth;   
    struct {
        uint32_t enable_internal_pullup : 1;
    } flags;
} i2c_master_bus_config_t;
 
typedef struct {
    i2c_addr_bit_len_t  dev_addr_length;    
    uint16_t            device_address;     
    uint32_t            scl_speed_hz;       
    uint32_t            scl_wait_us;        
    struct {
        uint32_t disable_ack_check : 1;     
    } flags;
} i2c_device_config_t;
 
/*============================ BUS LIFECYCLE =================================*/
 
extern esp_err_t i2c_new_master_bus(const i2c_master_bus_config_t *bus_config,
                                     i2c_master_bus_handle_t *ret_bus_handle);
 
extern esp_err_t i2c_del_master_bus(i2c_master_bus_handle_t bus_handle);
 
/*============================ DEVICE LIFECYCLE ==============================*/
 
extern esp_err_t i2c_master_bus_add_device(
                        i2c_master_bus_handle_t bus_handle,
                        const i2c_device_config_t *dev_config,
                        i2c_master_dev_handle_t *ret_handle);
 
extern esp_err_t i2c_master_bus_rm_device(i2c_master_dev_handle_t handle);
 
/*============================ DATA TRANSFER =================================*/
 
extern esp_err_t i2c_master_transmit(i2c_master_dev_handle_t i2c_dev,
                                      const uint8_t *write_buffer,
                                      size_t write_size,
                                      int xfer_timeout_ms);
 
extern esp_err_t i2c_master_receive(i2c_master_dev_handle_t i2c_dev,
                                     uint8_t *read_buffer,
                                     size_t read_size,
                                     int xfer_timeout_ms);
 
extern esp_err_t i2c_master_transmit_receive(
                        i2c_master_dev_handle_t i2c_dev,
                        const uint8_t *write_buffer,
                        size_t write_size,
                        uint8_t *read_buffer,
                        size_t read_size,
                        int xfer_timeout_ms);
 
/*============================ BUS UTILITIES =================================*/
 
extern esp_err_t i2c_master_probe(i2c_master_bus_handle_t bus_handle,
                                   uint16_t address,
                                   int xfer_timeout_ms);
 
extern esp_err_t i2c_master_bus_reset(i2c_master_bus_handle_t bus_handle);
 
extern esp_err_t i2c_master_bus_wait_all_done(
                        i2c_master_bus_handle_t bus_handle,
                        int timeout_ms);
 
#ifdef __cplusplus
}
#endif
 
#endif      /* __VSF_ESPIDF_DRIVER_I2C_MASTER_H__ */