feat(i2c): Add api for customize i2c transaction interface for un-standard i2c device

components/esp_driver_i2c/include/driver/i2c_master.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -36,12 +36,14 @@ typedef struct {
     } flags;                              /*!< I2C master config flags */
 } i2c_master_bus_config_t;
 
+#define I2C_DEVICE_ADDRESS_NOT_USED    (0xffff) /*!< Skip carry address bit in driver transmit and receive */
+
 /**
  * @brief I2C device configuration
  */
 typedef struct {
     i2c_addr_bit_len_t dev_addr_length;         /*!< Select the address length of the slave device. */
-    uint16_t device_address;                    /*!< I2C device raw address. (The 7/10 bit address without read/write bit) */
+    uint16_t device_address;                    /*!< I2C device raw address. (The 7/10 bit address without read/write bit). Macro I2C_DEVICE_ADDRESS_NOT_USED (0xFFFF) stands for skip the address config inside driver. */
     uint32_t scl_speed_hz;                      /*!< I2C SCL line frequency. */
     uint32_t scl_wait_us;                      /*!< Timeout value. (unit: us). Please note this value should not be so small that it can handle stretch/disturbance properly. If 0 is set, that means use the default reg value*/
     struct {
@@ -49,6 +51,38 @@ typedef struct {
     } flags;                                    /*!< I2C device config flags */
 } i2c_device_config_t;
 
+/**
+ * @brief Structure representing an I2C operation job
+ *
+ * This structure is used to define individual I2C operations (write or read)
+ * within a sequence of I2C master transactions.
+ */
+typedef struct {
+    i2c_master_command_t command; /**< I2C command indicating the type of operation (START, WRITE, READ, or STOP) */
+    union {
+        /**
+         * @brief Structure for WRITE command
+         *
+         * Used when the `command` is set to `I2C_MASTER_CMD_WRITE`.
+         */
+        struct {
+            bool ack_check;        /**< Whether to enable ACK check during WRITE operation */
+            uint8_t *data;         /**< Pointer to the data to be written */
+            size_t total_bytes;    /**< Total number of bytes to write */
+        } write;
+        /**
+         * @brief Structure for READ command
+         *
+         * Used when the `command` is set to `I2C_MASTER_CMD_READ`.
+         */
+        struct {
+            i2c_ack_value_t ack_value; /**< ACK value to send after the read (ACK or NACK) */
+            uint8_t *data;                    /**< Pointer to the buffer for storing the data read from the bus */
+            size_t total_bytes;               /**< Total number of bytes to read */
+        } read;
+    };
+} i2c_operation_job_t;
+
 /**
  * @brief Group of I2C master callbacks, can be used to get status during transaction or doing other small things. But take care potential concurrency issues.
  * @note The callbacks are all running under ISR context
@@ -189,6 +223,30 @@ esp_err_t i2c_master_receive(i2c_master_dev_handle_t i2c_dev, uint8_t *read_buff
  */
 esp_err_t i2c_master_probe(i2c_master_bus_handle_t bus_handle, uint16_t address, int xfer_timeout_ms);
 
+/**
+ * @brief Execute a series of pre-defined I2C operations.
+ *
+ * This function processes a list of I2C operations, such as start, write, read, and stop,
+ * according to the user-defined `i2c_operation_job_t` array. It performs these operations
+ * sequentially on the specified I2C master device.
+ *
+ * @param[in] i2c_dev           Handle to the I2C master device.
+ * @param[in] i2c_operation     Pointer to an array of user-defined I2C operation jobs.
+ *                              Each job specifies a command and associated parameters.
+ * @param[in] operation_list_num The number of operations in the `i2c_operation` array.
+ * @param[in] xfer_timeout_ms   Timeout for the transaction, in milliseconds.
+ *
+ * @return
+ *  - ESP_OK: Transaction completed successfully.
+ *  - ESP_ERR_INVALID_ARG: One or more arguments are invalid.
+ *  - ESP_ERR_TIMEOUT: Transaction timed out.
+ *  - ESP_FAIL: Other error during transaction.
+ *
+ * @note The `ack_value` field in the READ operation must be set to `I2C_NACK_VAL` if the next
+ *       operation is a STOP command.
+ */
+esp_err_t i2c_master_execute_defined_operations(i2c_master_dev_handle_t i2c_dev, i2c_operation_job_t *i2c_operation, size_t operation_list_num, int xfer_timeout_ms);
+
 /**
  * @brief Register I2C transaction callbacks for a master device
  *

components/esp_driver_i2c/include/driver/i2c_types.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -44,6 +44,29 @@ typedef enum {
     I2C_EVENT_TIMEOUT,    /*!< i2c bus timeout */
 } i2c_master_event_t;
 
+/**
+ * @brief Enum for I2C master commands
+ *
+ * These commands are used to define the I2C master operations.
+ * They correspond to hardware-level commands supported by the I2C peripheral.
+ */
+typedef enum {
+    I2C_MASTER_CMD_START,    /**< Start or Restart condition */
+    I2C_MASTER_CMD_WRITE,    /**< Write operation */
+    I2C_MASTER_CMD_READ,     /**< Read operation */
+    I2C_MASTER_CMD_STOP,     /**< Stop condition */
+} i2c_master_command_t;
+
+/**
+ * @brief Enum for I2C master ACK values
+ *
+ * These values define the acknowledgment (ACK) behavior during read operations.
+ */
+typedef enum {
+    I2C_ACK_VAL = 0,  /**< Acknowledge (ACK) signal */
+    I2C_NACK_VAL = 1, /**< Not Acknowledge (NACK) signal */
+}  __attribute__((packed)) i2c_ack_value_t;
+
 /**
  * @brief Type of I2C master bus handle
  */