docs(i2c_slave): Update i2c slave programming guide for new changes

Author: mythbuster5

docs/en/api-reference/peripherals/i2c.rst

@@ -36,6 +36,14 @@ Typically, an I2C slave device has a 7-bit address or 10-bit address. {IDF_TARGE
 
     Keep in mind that the higher the frequency, the smaller the pull-up resistor should be (but not less than 1 kΩ). Indeed, large resistors will decline the current, which will increase the clock switching time and reduce the frequency. A range of 2 kΩ to 5 kΩ is recommended, but adjustments may also be necessary depending on their current draw requirements.
 
+.. toctree::
+    :hidden:
+
+    i2c_slave_v1
+
+.. note::
+
+    We realized that our first version of the I2C slave driver had some problems and was not easy to use, so we have prepared a second version of the I2C slave driver, which solves many of the problems with our current I2C slave and which will be the focus of our maintenance. We encourage and recommend that you use the second version of the I2C slave driver, which you can do by enabling :ref:`CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2`. This document focuses on the content of I2C slave v2.0. If you still want to read programming guide of I2C slave v1.0, please refer to :ref:`i2c-slave-v1`. The I2C slave v1.0 driver will be removed with the IDF v6.0 update.
 
 I2C Clock Configuration
 -----------------------
@@ -218,27 +226,26 @@ I2C slave requires the configuration specified by :cpp:type:`i2c_slave_config_t`
     - :cpp:member:`i2c_slave_config_t::sda_io_num` sets the GPIO number for serial data bus (SDA).
     - :cpp:member:`i2c_slave_config_t::scl_io_num` sets the GPIO number for serial clock bus (SCL).
     - :cpp:member:`i2c_slave_config_t::clk_source` selects the source clock for I2C bus. The available clocks are listed in :cpp:type:`i2c_clock_source_t`. For the effect on power consumption of different clock source, please refer to `Power Management <#power-management>`__  section.
-    - :cpp:member:`i2c_slave_config_t::send_buf_depth` sets the sending buffer length.
-    - :cpp:member:`i2c_slave_config_t::slave_addr` sets the slave address.
-    - :cpp:member:`i2c_master_bus_config_t::intr_priority` sets the priority of the interrupt. If set to ``0`` , then the driver will use a interrupt with low or medium priority (priority level may be one of 1, 2 or 3), otherwise use the priority indicated by :cpp:member:`i2c_master_bus_config_t::intr_priority`. Please use the number form (1, 2, 3), instead of the bitmask form ((1<<1), (1<<2), (1<<3)). Please pay attention that once the interrupt priority is set, it cannot be changed until :cpp:func:`i2c_del_master_bus` is called.
-    - :cpp:member:`i2c_slave_config_t::addr_bit_len`. Set this variable to ``I2C_ADDR_BIT_LEN_10`` if the slave should have a 10-bit address.
-    :SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::stretch_en`. Set this variable to true, then the slave controller stretch will work. Please refer to [`TRM <{IDF_TARGET_TRM_EN_URL}#i2c>`__] to learn how I2C stretch works.
-    :SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::broadcast_en`. Set this to true to enable the slave broadcast. When the slave receives the general call address 0x00 from the master and the R/W bit followed is 0, it responds to the master regardless of its own address.
-    :SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS: - :cpp:member:`i2c_slave_config_t::access_ram_en`. Set this to true to enable the non-FIFO mode. Thus the I2C data FIFO can be used as RAM, and double addressing will be synchronised opened.
-    :SOC_I2C_SLAVE_SUPPORT_SLAVE_UNMATCH: - :cpp:member:`i2c_slave_config_t::slave_unmatch_en`. Set this to true to enable the slave unmatch interrupt. If the command address sent by master can't match the slave address, then unmatch interrupt will be triggered.
+    - :cpp:member:`i2c_slave_config_t::send_buf_depth` sets the sending software buffer length.
+    - :cpp:member:`i2c_slave_config_t::receive_buf_depth` sets the receiving software buffer length.
+    - :cpp:member:`i2c_slave_config_t::intr_priority` sets the priority of the interrupt. If set to ``0`` , then the driver will use a interrupt with low or medium priority (priority level may be one of 1, 2 or 3), otherwise use the priority indicated by :cpp:member:`i2c_slave_config_t::intr_priority`. Please use the number form (1, 2, 3), instead of the bitmask form ((1<<1), (1<<2), (1<<3)). Please pay attention that once the interrupt priority is set, it cannot be changed until :cpp:func:`i2c_del_slave_device` is called.
+    - :cpp:member:`i2c_slave_config_t::addr_bit_len` Set this variable to ``I2C_ADDR_BIT_LEN_10`` if the slave should have a 10-bit address.
+    - :cpp:member:`i2c_slave_config_t::allow_pd` If set, the driver will backup/restore the I2C registers before/after entering/exist sleep mode. By this approach, the system can power off I2C's power domain. This can save power, but at the expense of more RAM being consumed.
+    :SOC_I2C_SLAVE_SUPPORT_BROADCAST: - :cpp:member:`i2c_slave_config_t::broadcast_en` Set this to true to enable the slave broadcast. When the slave receives the general call address 0x00 from the master and the R/W bit followed is 0, it responds to the master regardless of its own address.
+    - :cpp:member:`i2c_slave_config_t::enable_internal_pullup` Set this to enable internal pull-up. Even though, an output pull-up resistance is strongly recommended.
 
 Once the :cpp:type:`i2c_slave_config_t` structure is populated with mandatory parameters, :cpp:func:`i2c_new_slave_device` can be called to allocate and initialize an I2C master bus. This function will return an I2C bus handle if it runs correctly. Specifically, when there are no more I2C port available, this function will return :c:macro:`ESP_ERR_NOT_FOUND` error.
 
 .. code:: c
 
     i2c_slave_config_t i2c_slv_config = {
-        .addr_bit_len = I2C_ADDR_BIT_LEN_7,
+        .i2c_port = I2C_SLAVE_NUM,
         .clk_source = I2C_CLK_SRC_DEFAULT,
-        .i2c_port = TEST_I2C_PORT,
-        .send_buf_depth = 256,
         .scl_io_num = I2C_SLAVE_SCL_IO,
         .sda_io_num = I2C_SLAVE_SDA_IO,
-        .slave_addr = 0x58,
+        .slave_addr = ESP_SLAVE_ADDR,
+        .send_buf_depth = 100,
+        .receive_buf_depth = 100,
     };
 
     i2c_slave_dev_handle_t slave_handle;
@@ -437,142 +444,72 @@ I2C Slave Controller
 
 After installing the I2C slave driver by :cpp:func:`i2c_new_slave_device`, {IDF_TARGET_NAME} is ready to communicate with other I2C masters as a slave.
 
+The I2C slave is not as subjective as the I2C master which knows when it should send data and when it should receive data. The I2C slave is very passive in most cases, that means the I2C slave's ability to send and receive data is largely dependent on the master's actions. Therefore, we throw two callback functions in the driver that represent read requests and write requests from the I2C master.
+
 I2C Slave Write
 ~~~~~~~~~~~~~~~
 
-The send buffer of the I2C slave is used as a FIFO to store the data to be sent. The data will queue up until the master requests them. You can call :cpp:func:`i2c_slave_transmit` to transfer data.
+You can get I2C slave write event be register :cpp:member:`i2c_slave_event_callbacks_t::on_request` callback, and in a task when get the request event, you can call `i2c_slave_write` to send data.
 
-Simple example for writing data to FIFO:
+Simple example for transmitting data:
 
 .. code:: c
 
-    uint8_t *data_wr = (uint8_t *) malloc(DATA_LENGTH);
+    // Prepare a callback function
+    static bool i2c_slave_request_cb(i2c_slave_dev_handle_t i2c_slave, const i2c_slave_request_event_data_t *evt_data, void *arg)
+    {
+        i2c_slave_event_t evt = I2C_SLAVE_EVT_TX;
+        BaseType_t xTaskWoken = 0;
+        xQueueSendFromISR(context->event_queue, &evt, &xTaskWoken);
+        return xTaskWoken;
+    }
 
-    i2c_slave_config_t i2c_slv_config = {
-        .addr_bit_len = I2C_ADDR_BIT_LEN_7,   // 7-bit address
-        .clk_source = I2C_CLK_SRC_DEFAULT,    // set the clock source
-        .i2c_port = TEST_I2C_PORT,            // set I2C port number
-        .send_buf_depth = 256,                // set TX buffer length
-        .scl_io_num = I2C_SLAVE_SCL_IO,       // SCL GPIO number
-        .sda_io_num = I2C_SLAVE_SDA_IO,       // SDA GPIO number
-        .slave_addr = 0x58,                   // slave address
+    // Register callback in a task
+    i2c_slave_event_callbacks_t cbs = {
+        .on_request = i2c_slave_request_cb,
     };
+    ESP_ERROR_CHECK(i2c_slave_register_event_callbacks(context.handle, &cbs, &context));
 
-    i2c_slave_dev_handle_t slave_handle;
-    ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
-    for (int i = 0; i < DATA_LENGTH; i++) {
-        data_wr[i] = i;
+    // Waiting for request event and send data in a task
+    static void i2c_slave_task(void *arg)
+    {
+        uint8_t buffer_size = 64;
+        uint32_t write_len;
+        uint8_t *data_buffer;
+
+        while (true) {
+            i2c_slave_event_t evt;
+            if (xQueueReceive(context->event_queue, &evt, 10) == pdTRUE) {
+                ESP_ERROR_CHECK(i2c_slave_write(handle, data_buffer, buffer_size, &write_len, 1000));
+            }
+        }
+        vTaskDelete(NULL);
     }
 
-    ESP_ERROR_CHECK(i2c_slave_transmit(slave_handle, data_wr, DATA_LENGTH, 10000));
-
 I2C Slave Read
 ~~~~~~~~~~~~~~
 
-Whenever the master writes data to the slave, the slave will automatically store data in the receive buffer. This allows the slave application to call the function :cpp:func:`i2c_slave_receive` as its own discretion. As :cpp:func:`i2c_slave_receive` is designed as a non-blocking interface, users need to register callback :cpp:func:`i2c_slave_register_event_callbacks` to know when the receive has finished.
+Same as write, you can get I2C slave read event be register :cpp:member:`i2c_slave_event_callbacks_t::on_receive` callback, and in a task when get the request event, you can save the data and do what you want.
+
+Simple example for receiving data:
 
 .. code:: c
 
-    static IRAM_ATTR bool i2c_slave_rx_done_callback(i2c_slave_dev_handle_t channel, const i2c_slave_rx_done_event_data_t *edata, void *user_data)
+    // Prepare a callback function
+    static bool i2c_slave_receive_cb(i2c_slave_dev_handle_t i2c_slave, const i2c_slave_rx_done_event_data_t *evt_data, void *arg)
     {
-        BaseType_t high_task_wakeup = pdFALSE;
-        QueueHandle_t receive_queue = (QueueHandle_t)user_data;
-        xQueueSendFromISR(receive_queue, edata, &high_task_wakeup);
-        return high_task_wakeup == pdTRUE;
+        i2c_slave_event_t evt = I2C_SLAVE_EVT_RX;
+        BaseType_t xTaskWoken = 0;
+        // You can get data and length via i2c_slave_rx_done_event_data_t
+        xQueueSendFromISR(context->event_queue, &evt, &xTaskWoken);
+        return xTaskWoken;
     }
 
-    uint8_t *data_rd = (uint8_t *) malloc(DATA_LENGTH);
-    uint32_t size_rd = 0;
-
-    i2c_slave_config_t i2c_slv_config = {
-        .addr_bit_len = I2C_ADDR_BIT_LEN_7,
-        .clk_source = I2C_CLK_SRC_DEFAULT,
-        .i2c_port = TEST_I2C_PORT,
-        .send_buf_depth = 256,
-        .scl_io_num = I2C_SLAVE_SCL_IO,
-        .sda_io_num = I2C_SLAVE_SDA_IO,
-        .slave_addr = 0x58,
-    };
-
-    i2c_slave_dev_handle_t slave_handle;
-    ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
-
-    s_receive_queue = xQueueCreate(1, sizeof(i2c_slave_rx_done_event_data_t));
+    // Register callback in a task
     i2c_slave_event_callbacks_t cbs = {
-        .on_recv_done = i2c_slave_rx_done_callback,
+        .on_receive = i2c_slave_receive_cb,
     };
-    ESP_ERROR_CHECK(i2c_slave_register_event_callbacks(slave_handle, &cbs, s_receive_queue));
-
-    i2c_slave_rx_done_event_data_t rx_data;
-    ESP_ERROR_CHECK(i2c_slave_receive(slave_handle, data_rd, DATA_LENGTH));
-    xQueueReceive(s_receive_queue, &rx_data, pdMS_TO_TICKS(10000));
-    // Receive done.
-
-.. only:: SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS
-
-    Put Data In I2C Slave RAM
-    ~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    I2C slave FIFO mentioned above can be used as RAM, which means user can access the RAM directly via address fields. For example, write data to the third RAM block with following graph. Before using this, please note that :cpp:member:`i2c_slave_config_t::access_ram_en` needs to be set to true.
-
-    .. figure:: ../../../_static/diagrams/i2c/i2c_slave_write_slave_ram.png
-        :align: center
-        :alt: Put data in I2C slave RAM
-
-        Put data in I2C slave RAM
-
-    .. code:: c
-
-        uint8_t data_rd[DATA_LENGTH_RAM] = {0};
-
-        i2c_slave_config_t i2c_slv_config = {
-            .addr_bit_len = I2C_ADDR_BIT_LEN_7,
-            .clk_source = I2C_CLK_SRC_DEFAULT,
-            .i2c_port = TEST_I2C_PORT,
-            .send_buf_depth = 256,
-            .scl_io_num = I2C_SLAVE_SCL_IO,
-            .sda_io_num = I2C_SLAVE_SDA_IO,
-            .slave_addr = 0x58,
-            .flags.access_ram_en = true,
-        };
-
-        // Master writes to slave.
-
-        i2c_slave_dev_handle_t slave_handle;
-        ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
-        ESP_ERROR_CHECK(i2c_slave_read_ram(slave_handle, 0x5, data_rd, DATA_LENGTH_RAM));
-        ESP_ERROR_CHECK(i2c_del_slave_device(slave_handle));
-
-    Get Data From I2C Slave RAM
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Data can be stored in the RAM with a specific offset by the slave controller, and the master can read this data directly via the RAM address. For example, if the data is stored in the third RAM block, master can read this data by the following graph. Before using this, please note that :cpp:member:`i2c_slave_config_t::access_ram_en` needs to be set to true.
-
-    .. figure:: ../../../_static/diagrams/i2c/i2c_slave_read_slave_ram.png
-        :align: center
-        :alt: Get data from I2C slave RAM
-
-        Get data from I2C slave RAM
-
-    .. code:: c
-
-        uint8_t data_wr[DATA_LENGTH_RAM] = {0};
-
-        i2c_slave_config_t i2c_slv_config = {
-            .addr_bit_len = I2C_ADDR_BIT_LEN_7,
-            .clk_source = I2C_CLK_SRC_DEFAULT,
-            .i2c_port = TEST_I2C_PORT,
-            .send_buf_depth = 256,
-            .scl_io_num = I2C_SLAVE_SCL_IO,
-            .sda_io_num = I2C_SLAVE_SDA_IO,
-            .slave_addr = 0x58,
-            .flags.access_ram_en = true,
-        };
-
-        i2c_slave_dev_handle_t slave_handle;
-        ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
-        ESP_ERROR_CHECK(i2c_slave_write_ram(slave_handle, 0x2, data_wr, DATA_LENGTH_RAM));
-        ESP_ERROR_CHECK(i2c_del_slave_device(slave_handle));
+    ESP_ERROR_CHECK(i2c_slave_register_event_callbacks(context.handle, &cbs, &context));
 
 Register Event Callbacks
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -601,8 +538,8 @@ I2C slave event callbacks are listed in the :cpp:type:`i2c_slave_event_callbacks
 
 .. list::
 
-    - :cpp:member:`i2c_slave_event_callbacks_t::on_recv_done` sets a callback function for "receive-done" event. The function prototype is declared in :cpp:type:`i2c_slave_received_callback_t`.
-    :SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_event_callbacks_t::on_stretch_occur` sets a callback function for "stretch" cause. The function prototype is declared in :cpp:type:`i2c_slave_stretch_callback_t`.
+    - :cpp:member:`i2c_slave_event_callbacks_t::on_request` sets a callback function for request event.
+    - :cpp:member:`i2c_slave_event_callbacks_t::on_receive` sets a callback function for receive event. The function prototype is declared in :cpp:type:`i2c_slave_received_callback_t`.
 
 Power Management
 ^^^^^^^^^^^^^^^^
@@ -637,13 +574,28 @@ This will allow the interrupt to run while the cache is disabled but will come a
 Thread Safety
 ^^^^^^^^^^^^^
 
-The factory function :cpp:func:`i2c_new_master_bus` and :cpp:func:`i2c_new_slave_device` are guaranteed to be thread safe by the driver, which means that the functions can be called from different RTOS tasks without protection by extra locks. Other public I2C APIs are not thread safe, which means the user should avoid calling them from multiple tasks, if it is necessary to call them in multiple tasks, please add extra locks.
+The factory function :cpp:func:`i2c_new_master_bus` and :cpp:func:`i2c_new_slave_device` are guaranteed to be thread safe by the driver, which means that the functions can be called from different RTOS tasks without protection by extra locks.
+
+I2C master operation functions are also guaranteed to be thread safe by bus operation semaphore.
+
+- :cpp:func:`i2c_master_transmit`
+- :cpp:func:`i2c_master_multi_buffer_transmit`
+- :cpp:func:`i2c_master_transmit_receive`
+- :cpp:func:`i2c_master_receive`
+- :cpp:func:`i2c_master_probe`
+
+I2C slave operation functions are also guaranteed to be thread safe by bus operation semaphore.
+
+- :cpp:func:`i2c_slave_write`
+
+Other functions are not guaranteed to be thread-safe. Thus, you should avoid calling them in different tasks without mutex protection.
 
 Kconfig Options
 ^^^^^^^^^^^^^^^
 
 - :ref:`CONFIG_I2C_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see also `IRAM Safe <#iram-safe>`__ for more information.
 - :ref:`CONFIG_I2C_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
+- :ref:`CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2` is used to enable the I2C slave driver v2.0.
 
 Application Examples
 --------------------
@@ -652,6 +604,7 @@ Application Examples
 
 - :example:`peripherals/i2c/i2c_tools` demonstrates how to use the I2C Tools for developing I2C related applications, providing command-line tools for configuring the I2C bus, scanning for devices, reading and setting registers, and examining registers.
 
+- :example:`peripherals/i2c/i2c_slave_network_sensor` demonstrates how to use the I2C slave for developing I2C related applications, providing how I2C slave can behave as a network sensor, and use event callbacks to receive and send data.
 
 API Reference
 -------------