change(i2c_master): Change return value when NACK detected

components/esp_driver_i2c/i2c_master.c

@@ -701,7 +701,7 @@ static esp_err_t s_i2c_transaction_start(i2c_master_dev_handle_t i2c_dev, int xf
         s_i2c_send_commands(i2c_master, ticks_to_wait);
         // Wait event bits
         if (atomic_load(&i2c_master->status) != I2C_STATUS_DONE) {
-            ret = ESP_ERR_INVALID_STATE;
+            ret = ESP_ERR_INVALID_RESPONSE; // NACK is received
         }
         // Interrupt can be disabled when on transaction finishes.
         i2c_ll_disable_intr_mask(hal->dev, I2C_LL_MASTER_EVENT_INTR);

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
  */
@@ -162,7 +162,8 @@ esp_err_t i2c_master_bus_rm_device(i2c_master_dev_handle_t handle);
  * @param[in] write_size Size, in bytes, of the write buffer.
  * @param[in] xfer_timeout_ms Wait timeout, in ms. Note: -1 means wait forever.
  * @return
- *      - ESP_OK: I2C master transmit success
+ *      - ESP_OK: I2C master transmit success.
+ *      - ESP_ERR_INVALID_RESPONSE: I2C master transmit receives NACK.
  *      - ESP_ERR_INVALID_ARG: I2C master transmit parameter invalid.
  *      - ESP_ERR_TIMEOUT: Operation timeout(larger than xfer_timeout_ms) because the bus is busy or hardware crash.
  */
@@ -180,7 +181,8 @@ esp_err_t i2c_master_transmit(i2c_master_dev_handle_t i2c_dev, const uint8_t *wr
  * @param xfer_timeout_ms Wait timeout, in ms. Note: -1 means wait forever.
  *
  * @return
- *      - ESP_OK: I2C master transmit success
+ *      - ESP_OK: I2C master transmit success.
+ *      - ESP_ERR_INVALID_RESPONSE: I2C master transmit receives NACK.
  *      - ESP_ERR_INVALID_ARG: I2C master transmit parameter invalid.
  *      - ESP_ERR_TIMEOUT: Operation timeout(larger than xfer_timeout_ms) because the bus is busy or hardware crash.
  */
@@ -201,7 +203,8 @@ esp_err_t i2c_master_multi_buffer_transmit(i2c_master_dev_handle_t i2c_dev, i2c_
  * @param[in] read_size Size, in bytes, of the read buffer.
  * @param[in] xfer_timeout_ms Wait timeout, in ms. Note: -1 means wait forever.
  * @return
- *      - ESP_OK: I2C master transmit-receive success
+ *      - ESP_OK: I2C master transmit-receive success.
+ *      - ESP_ERR_INVALID_RESPONSE: I2C master transmit-receive receives NACK.
  *      - ESP_ERR_INVALID_ARG: I2C master transmit parameter invalid.
  *      - ESP_ERR_TIMEOUT: Operation timeout(larger than xfer_timeout_ms) because the bus is busy or hardware crash.
  */
@@ -246,7 +249,7 @@ esp_err_t i2c_master_receive(i2c_master_dev_handle_t i2c_dev, uint8_t *read_buff
  * So, if the on line data is strange and no ack/nack got respond. Please check the device datasheet.
  *
  * @return
- *      - ESP_OK: I2C device probe successfully
+ *      - ESP_OK: I2C device probed successfully.
  *      - ESP_ERR_NOT_FOUND: I2C probe failed, doesn't find the device with specific address you gave.
  *      - ESP_ERR_TIMEOUT: Operation timeout(larger than xfer_timeout_ms) because the bus is busy or hardware crash.
  */
@@ -267,9 +270,9 @@ esp_err_t i2c_master_probe(i2c_master_bus_handle_t bus_handle, uint16_t address,
  *
  * @return
  *  - ESP_OK: Transaction completed successfully.
+ *  - ESP_ERR_INVALID_RESPONSE: I2C master transaction receives NACK.
  *  - 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.

docs/en/migration-guides/release-6.x/6.0/peripherals.rst

@@ -86,8 +86,19 @@ Major Changes in Usage
 
 - ``i2c_slave_receive`` has been removed. In the new driver, data reception is handled via callbacks.
 - ``i2c_slave_transmit`` has been replaced by ``i2c_slave_write``.
-- ``i2c_slave_write_ram`` has been removed。
-- ``i2c_slave_read_ram`` has been removed。
+- ``i2c_slave_write_ram`` has been removed.
+- ``i2c_slave_read_ram`` has been removed.
+
+Meanwhile, I2C master also has some change in its APIs' definitions.
+
+Major Changes in Usage
+~~~~~~~~~~~~~~~~~~~~~~
+
+Following functions now will return ``ESP_ERR_INVALID_RESPONSE`` instead of ``ESP_ERR_INVALID_STATE`` when NACK from the bus is detected:
+- ``i2c_master_transmit``
+- ``i2c_master_multi_buffer_transmit``
+- ``i2c_master_transmit_receive``
+- ``i2c_master_execute_defined_operations``
 
 Legacy Timer Group Driver is Removed
 ------------------------------------

docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst

@@ -85,10 +85,21 @@ I2C 从机在 v5.4 上已经被重新设计。在当前版本上，老的 I2C
 ~~~~~~~~~~~~~~~~~~
 
 - ``i2c_slave_receive`` 被移除， 在新驱动中使用回调接收数据。
-- ``i2c_slave_transmit`` 已被 ``i2c_slave_write`` 取代.
+- ``i2c_slave_transmit`` 已被 ``i2c_slave_write`` 取代。
 - ``i2c_slave_write_ram`` 被移除。
 - ``i2c_slave_read_ram`` 被移除。
 
+同时，I2C的主机驱动也有一些API用法上的改动
+
+主要用法更新
+~~~~~~~~~~~~~~~~~~
+
+当主机在I2C总线上检测到NACK，以下的函数目前会返回 ``ESP_ERR_INVALID_RESPONSE``，而不是像之前一样返回 ``ESP_ERR_INVALID_STATE``：
+- ``i2c_master_transmit``
+- ``i2c_master_multi_buffer_transmit``
+- ``i2c_master_transmit_receive``
+- ``i2c_master_execute_defined_operations``
+
 旧版定时器组驱动被移除
 ----------------------