Merge branch 'add_application_examples_peripherals' into 'master'

April-Yjj · April-Yjj · commit 91ad4bcbce2e · 2024-09-18T17:31:59.000+08:00
Add application examples for i2c, jpeg, temp_sensor and usb_serial-jtag-console

See merge request espressif/esp-idf!33274
diff --git a/docs/en/api-guides/usb-serial-jtag-console.rst b/docs/en/api-guides/usb-serial-jtag-console.rst
@@ -122,3 +122,9 @@ Automatic and Manual Sleep Entry
 If users enter sleep manually (via :cpp:func:`esp_light_sleep_start` or :cpp:func:`esp_deep_sleep_start`), users should be cognizant of the fact that USB Serial/JTAG controller does not work during sleep. ESP-IDF **does not add any safety check to reject entry to sleep** even if the USB Serial/JTAG controller is connected. In the case where sleep is entered while the USB Serial/JTAG controller is connected, the connection can be re-established by unplugging and re-plugging the USB cable.
 
 If users enter sleep automatically (via :cpp:func:`esp_pm_configure`), enabling the :ref:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` option allows the {IDF_TARGET_NAME} to automatically detect whether the USB Serial/JTAG controller is currently connected to a host, and prevent automatic entry to sleep as long as the connection persists. However, note that this option increases power consumption.
+
+
+Application Examples
+====================
+
+- :example:`peripherals/usb_serial_jtag/usb_serial_jtag_echo` demonstrates how to use the USB_SERIAL_JTAG interfaces to echo back any data received on it.
diff --git a/docs/en/api-reference/peripherals/i2c.rst b/docs/en/api-reference/peripherals/i2c.rst
@@ -649,10 +649,10 @@ Kconfig Options
 Application Examples
 --------------------
 
-.. list::
+- :example:`peripherals/i2c/i2c_eeprom` demonstrates how to use the I2C master mode to read and write data from a connected EEPROM.
+
+- :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_eeprom` demonstrates the basic usage of I2C driver by reading and writing from an I2C connected EEPROM.
-    - :example:`peripherals/i2c/i2c_tools` implements some basic features of I2C tools based on the ESP32 console component.
 
 API Reference
 -------------
diff --git a/docs/en/api-reference/peripherals/jpeg.rst b/docs/en/api-reference/peripherals/jpeg.rst
@@ -448,8 +448,10 @@ The JPEG driver usage of hardware resources and its dependency status are shown
 Application Examples
 --------------------
 
-* JPEG decoder application example: :example:`peripherals/jpeg/jpeg_decode`.
-* JPEG encoder application example: :example:`peripherals/jpeg/jpeg_encode`.
+- :example:`peripherals/jpeg/jpeg_decode` demonstrates how to use the JPEG hardware decoder to decode JPEG pictures of different sizes (1080p and 720p) into RGB format, showcasing the flexibility and speed of hardware decoding.
+
+- :example:`peripherals/jpeg/jpeg_encode` demonstrates how to use the JPEG hardware encoder to encode a 1080p picture, specifically converting `*.rgb` files to `*.jpg` files.
+
 
 API Reference
 -------------
diff --git a/docs/en/api-reference/peripherals/temp_sensor.rst b/docs/en/api-reference/peripherals/temp_sensor.rst
@@ -203,13 +203,15 @@ Unexpected Behaviors
     (1) Totally out of range, like 200 °C ~ 300 °C.
     (2) Cross the boundary of each predefined measurement. like 40 °C ~ 110 °C.
 
-Application Example
--------------------
+Application Examples
+--------------------
 
-.. list::
+* :example:`peripherals/temperature_sensor/temp_sensor` demonstrates how to use the built-in temperature sensor, showcasing the measurement range and error based on different DAC levels and offsets.
+
+.. only:: SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
+
+  * :example:`peripherals/temperature_sensor/temp_sensor_monitor` demonstrates how to use the temperature sensor to automatically monitor temperature values continuously, triggering an interrupt when a specific value is reached or when the change between two consecutive samplings is larger/smaller than the settings.
 
-    * Temperature sensor reading example: :example:`peripherals/temperature_sensor/temp_sensor`.
-    :SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: * Temperature sensor value monitor example: :example:`peripherals/temperature_sensor/temp_sensor_monitor`.
 
 API Reference
 ----------------------------------
diff --git a/docs/zh_CN/api-guides/usb-serial-jtag-console.rst b/docs/zh_CN/api-guides/usb-serial-jtag-console.rst
@@ -122,3 +122,9 @@ Light-sleep
 如果通过 :cpp:func:`esp_light_sleep_start` 或 :cpp:func:`esp_deep_sleep_start` 手动进入睡眠模式，需注意，USB 串行/JTAG 控制器在睡眠期间不工作。ESP-IDF **没有添加任何拒绝进入睡眠的安全检查**，即使 USB 串行/JTAG 控制器已连接，也会进入睡眠模式。如果在连接了 USB 串行/JTAG 控制器的情况下进入睡眠，可以通过拔出并重新插入 USB 电缆来重新建立连接。
 
 如果通过 :cpp:func:`esp_pm_configure` 自动进入睡眠模式，请启用 :ref:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` 选项，该选项支持 {IDF_TARGET_NAME} 自动检测 USB 串行/JTAG 控制器与主机的连接情况，并在连接持续时，阻止程序自动进入睡眠模式。注意，此选项会增加功耗。
+
+
+应用示例
+====================
+
+- :example:`peripherals/usb_serial_jtag/usb_serial_jtag_echo` 演示了使用 USB_SERIAL_JTAG 接口回显其接收到的数据。
diff --git a/docs/zh_CN/api-reference/peripherals/i2c.rst b/docs/zh_CN/api-reference/peripherals/i2c.rst
@@ -649,10 +649,10 @@ Kconfig 选项
 应用示例
 --------
 
-.. list::
+- :example:`peripherals/i2c/i2c_eeprom` 演示了如何使用 I2C 主机模式从连接的 EEPROM 读取和写入数据。
+
+- :example:`peripherals/i2c/i2c_tools` 演示了如何使用 I2C 工具开发 I2C 相关的应用程序，提供了用于配置 I2C 总线、扫描设备、读取、设置和检查寄存器的命令行工具。
 
-    - :example:`peripherals/i2c/i2c_eeprom` 通过读取和写入 I2C 连接的 EEPROM 展示了 I2C 驱动程序的使用方法。
-    - :example:`peripherals/i2c/i2c_tools` 基于 ESP32 控制台组件实现了一些 I2C 工具的基本功能。
 
 API 参考
 --------
diff --git a/docs/zh_CN/api-reference/peripherals/jpeg.rst b/docs/zh_CN/api-reference/peripherals/jpeg.rst
@@ -448,8 +448,10 @@ Kconfig 选项
 应用程序示例
 ------------
 
-* JPEG 编码器应用程序示例： :example:`peripherals/jpeg/jpeg_decode`。
-* JPEG 解码器应用程序示例： :example:`peripherals/jpeg/jpeg_encode`。
+- :example:`peripherals/jpeg/jpeg_decode` 演示了如何使用 JPEG 硬件解码器将不同大小的 JPEG 图片（1080p 和 720p）解码为 RGB 格式，展示了硬件解码的速度和灵活性。
+
+- :example:`peripherals/jpeg/jpeg_encode` 演示了如何使用 JPEG 硬件编码器编码一张 1080p 的图像，即将 `*.rgb` 文件转换为 `*.jpg` 文件。
+
 
 API 参考
 --------
diff --git a/docs/zh_CN/api-reference/peripherals/temp_sensor.rst b/docs/zh_CN/api-reference/peripherals/temp_sensor.rst
@@ -206,10 +206,12 @@
 应用示例
 -------------------
 
-.. list::
+    * :example:`peripherals/temperature_sensor/temp_sensor` 演示了如何使用内置温度传感器，并展示了 DAC 电平和偏移量不同时的测量范围和误差。
+
+.. only:: SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
+
+  * :example:`peripherals/temperature_sensor/temp_sensor_monitor` 演示了如何使用温度传感器连续自动监测温度值，当温度达到特定值或或两个连续的采样之间的变化大于/小于设置时，触发中断。
 
-    * 读取温度传感器测量值：:example:`peripherals/temperature_sensor/temp_sensor`。
-    :SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: * 监测温度传感器测量值：:example:`peripherals/temperature_sensor/temp_sensor_monitor`。
 
 API 参考
 ----------------------------------
