diff --git a/components/esp_driver_i2c/i2c_master.c b/components/esp_driver_i2c/i2c_master.c index a9935d5a8c..319712ac9a 100644 --- a/components/esp_driver_i2c/i2c_master.c +++ b/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); diff --git a/components/esp_driver_i2c/include/driver/i2c_master.h b/components/esp_driver_i2c/include/driver/i2c_master.h index dcdd253316..6a76953413 100644 --- a/components/esp_driver_i2c/include/driver/i2c_master.h +++ b/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. diff --git a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst index e8f2a07243..7e75000f4d 100644 --- a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst +++ b/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 ------------------------------------ diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst index a48dd81a2a..1f560bd19e 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst +++ b/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`` + 旧版定时器组驱动被移除 ----------------------