Merge branch 'docs/add_application_examples_system_component' into 'm…

…aster'

docs: add or update application examples of system component

See merge request espressif/esp-idf!32004

docs/en/api-guides/unit-tests.rst

@@ -368,3 +368,8 @@ The unit test needs to inform the cmake build system to mock dependent component
 Both methods will override existing components in ESP-IDF with the component mock. The latter is particularly convenient if you use component mocks that are already supplied by IDF.
 
 Users can refer to the ``esp_event`` host-based unit test and its :component_file:`esp_event/host_test/esp_event_unit_test/CMakeLists.txt` as an example of a component mock.
+
+Application Examples
+--------------------
+
+:example:`system/unit_test` demonstrates how to use the Unity library to add unit tests to custom components in an {IDF_TARGET_NAME} development environment, showcasing features such as assertions, test registration, and the use of UNITY_BEGIN() and UNITY_END() macros.

docs/en/api-reference/system/console.rst

@@ -186,13 +186,16 @@ After that, you can register your own commands with :cpp:func:`esp_console_cmd_r
 
     Likewise, if your REPL environment is based on USB_SERIAL_JTAG device, you only need to call :cpp:func:`esp_console_new_repl_usb_serial_jtag` at first step. Then call other functions as usual.
 
-Application Example
--------------------
+Application Examples
+--------------------
 
-Example application illustrating usage of the ``console`` component is available in :example:`system/console` directory. This example shows how to initialize UART and VFS functions, set up linenoise library, read and handle commands from UART, and store command history in Flash. See README.md in the example directory for more details.
+- :example:`system/console/basic` demonstrates how to use the REPL (Read-Eval-Print Loop) APIs of the Console Component to create an interactive shell on {IDF_TARGET_NAME}, which can be controlled over a serial interface, supporting UART and USB interfaces, and can serve as a basis for applications requiring a command-line interface.
 
-Besides that, ESP-IDF contains several useful examples which are based on the ``console`` component and can be treated as "tools" when developing applications. For example, :example:`peripherals/i2c/i2c_tools`, :example:`wifi/iperf`.
+- :example:`system/console/advanced` demonstrates how to use the Console Component to create an interactive shell on {IDF_TARGET_NAME}, which can be controlled over a serial port, providing a basis for applications that require a command-line interface.
 
+.. only:: esp32s3
+
+    - :example:`system/console/advanced_usb_cdc` demonstrates how to create and interact with an interactive shell with a command-line interface, over the {IDF_TARGET_NAME}'s USB_OTG peripheral.
 
 API Reference
 -------------

docs/en/api-reference/system/esp_event.rst

@@ -212,14 +212,12 @@ Event Loop Profiling
 
 A configuration option :ref:`CONFIG_ESP_EVENT_LOOP_PROFILING` can be enabled in order to activate statistics collection for all event loops created. The function :cpp:func:`esp_event_dump` can be used to output the collected statistics to a file stream. More details on the information included in the dump can be found in the :cpp:func:`esp_event_dump` API Reference.
 
-Application Example
--------------------
-
-Examples of using the ``esp_event`` library can be found in :example:`system/esp_event`. The examples cover event declaration, loop creation, handler registration and deregistration, and event posting.
+Application Examples
+--------------------
 
-Other examples which also adopt ``esp_event`` library:
+- :example:`system/esp_event/default_event_loop` demonstrates how to use the default event loop system of {IDF_TARGET_NAME} to post and handle events, including declaring and defining events, creating the default event loop, posting events to the loop, and registering/unregistering event handlers.
 
-    * :example:`NMEA Parser <peripherals/uart/nmea0183_parser>`, which decodes the statements received from GPS.
+- :example:`system/esp_event/user_event_loops` demonstrates how to create and use user event loops on {IDF_TARGET_NAME}, including creating and running event loops, registering and unregistering handlers, and posting events, with the ability to handle different use cases beyond the default event loop.
 
 API Reference
 -------------

docs/en/api-reference/system/esp_timer.rst

@@ -314,7 +314,7 @@ If you see a stack overflow error when executing a callback function, consider r
 Application Examples
 --------------------
 
-* :example:`system/esp_timer` creates and starts one-shot and periodic software timers, shows how they work with Light-sleep mode, and then stops and deletes the timers
+- :example:`system/esp_timer` creates and starts one-shot and periodic software timers, shows how they work with Light-sleep mode, and then stops and deletes the timers.
 
 
 API Reference

docs/en/api-reference/system/freertos.rst

@@ -140,3 +140,10 @@ Vanilla FreeRTOS provides its own `selection of heap implementations <https://ww
 
     - Allocate the task or object using one of the ``...CreateWithCaps()`` API, such as :cpp:func:`xTaskCreateWithCaps` and :cpp:func:`xQueueCreateWithCaps` (see :ref:`freertos-idf-additional-api` for more details).
     - Manually allocate external memory for those objects using :cpp:func:`heap_caps_malloc`, then create the objects from the allocated memory using on of the ``...CreateStatic()`` FreeRTOS functions.
+
+Application Examples
+--------------------
+
+- :example:`system/freertos/basic_freertos_smp_usage` demonstrates how to use basic FreeRTOS APIs for task creation, communication, synchronization, and batch processing within an SMP architecture on {IDF_TARGET_NAME}.
+
+- :example:`system/freertos/real_time_stats` demonstrates how to use FreeRTOS's function `vTaskGetRunTimeStats()` to obtain CPU usage statistics of tasks with respect to a specified duration, rather than over the entire runtime of FreeRTOS.

docs/en/api-reference/system/heap_debug.rst

@@ -510,6 +510,11 @@ Not everything printed by :cpp:func:`heap_trace_dump` is necessarily a memory le
 
 One way to differentiate between "real" and "false positive" memory leaks is to call the suspect code multiple times while tracing is running, and look for patterns (multiple matching allocations) in the heap trace output.
 
+Application Examples
+--------------------
+
+- :example:`system/heap_task_tracking` demonstrates the use of the heap task tracking feature to track heap memory allocated on a per-task basis.
+
 API Reference - Heap Tracing
 ----------------------------
 

docs/en/api-reference/system/himem.rst

@@ -17,11 +17,10 @@ In order to use the Himem API, you have to enable it in the menuconfig using :re
 
 The Himem API is more-or-less an abstraction of the bank switching scheme: it allows you to claim one or more banks of address space (called 'regions' in the API) as well as one or more of banks of memory to map into the ranges.
 
-Example
--------
-
-An example doing a simple memory test of the high memory range is available in ESP-IDF: :example:`system/himem`
+Application Examples
+--------------------
 
+- :example:`system/himem` demonstrates how to use the Himem API on {IDF_TARGET_NAME} to run a memory test of the upper 4 MiB of an 8 MiB PSRAM chip, illustrating how to allocate address space, allocate the physical memory, and switch it in or out of the allocated address space.
 
 API Reference
 -------------

docs/en/api-reference/system/ipc.rst

@@ -146,6 +146,17 @@ The High Priority Interrupt IPC API also provides the following convenience func
     :CONFIG_IDF_TARGET_ARCH_XTENSA: - :cpp:func:`esp_ipc_isr_stall_other_cpu` stalls the target core. The calling core disables interrupts of level 3 and lower while the target core will busy-wait with interrupts of level 5 and lower disabled. The target core will busy-wait until :cpp:func:`esp_ipc_isr_release_other_cpu` is called.
     - :cpp:func:`esp_ipc_isr_release_other_cpu` resumes the target core.
 
+Application Examples
+--------------------
+
+.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
+
+    - :example:`system/ipc/ipc_isr/xtensa` demonstrates how to use the IPC ISR feature to run an IPC in the context of a High Priority Interrupt, allowing users to quickly get the state of the other CPU, with two assembly callbacks that return the PS register of the other core and save/restore registers while performing tasks based on input arguments.
+
+.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
+
+    - :example:`system/ipc/ipc_isr/riscv` demonstrates how to use the IPC ISR feature on {IDF_TARGET_NAME} to run an IPC in the context of a High Priority Interrupt, including how to quickly get the state of the other CPU and how to return multiple values from the callback function.
+
 API Reference
 -------------
 

docs/en/api-reference/system/perfmon.rst

@@ -5,10 +5,10 @@ Performance Monitor
 
 The Performance Monitor component provides APIs to use {IDF_TARGET_NAME} internal performance counters to profile functions and applications.
 
-Application Example
--------------------
+Application Examples
+--------------------
 
-An example which combines performance monitor is provided in ``examples/system/perfmon`` directory. This example initializes the performance monitor structure and execute them with printing the statistics.
+- :example:`system/perfmon` demonstrates how to use the `perfmon` APIs to monitor and profile functions.
 
 High-Level API Reference
 ------------------------

docs/en/api-reference/system/pthread.rst

@@ -252,13 +252,12 @@ The API :cpp:func:`esp_pthread_set_cfg` defined in the ``esp_pthreads.h`` header
 
 This configuration is scoped to the calling thread (or FreeRTOS task), meaning that :cpp:func:`esp_pthread_set_cfg` can be called independently in different threads or tasks. If the ``inherit_cfg`` flag is set in the current configuration then any new thread created will inherit the creator's configuration (if that thread calls ``pthread_create()`` recursively), otherwise the new thread will have the default configuration.
 
-Examples
---------
+Application Examples
+--------------------
 
 - :example:`system/pthread` demonstrates using the pthreads API to create threads.
 - :example:`cxx/pthread` demonstrates using C++ Standard Library functions with threads.
 
-
 API Reference
 -------------
 

docs/en/api-reference/system/ulp-lp-core.rst

@@ -227,10 +227,17 @@ Application Examples
 --------------------
 
 * :example:`system/ulp/lp_core/gpio` polls GPIO while main CPU is in Deep-sleep.
-* :example:`system/ulp/lp_core/lp_i2c` reads external I2C ambient light sensor (BH1750) while the main CPU is in Deep-sleep and wakes up the main CPU once a threshold is met.
+
+.. only:: esp32c6
+
+    * :example:`system/ulp/lp_core/lp_i2c` reads external I2C ambient light sensor (BH1750) while the main CPU is in Deep-sleep and wakes up the main CPU once a threshold is met.
+
 * :example:`system/ulp/lp_core/lp_uart/lp_uart_echo` reads data written to a serial console and echoes it back. This example demonstrates the usage of the LP UART driver running on the LP core.
+
 * :example:`system/ulp/lp_core/lp_uart/lp_uart_print` shows how to print various statements from a program running on the LP core.
+
 * :example:`system/ulp/lp_core/interrupt` shows how to register an interrupt handler on the LP core to receive an interrupt triggered by the main CPU.
+
 * :example:`system/ulp/lp_core/gpio_intr_pulse_counter` shows how to use GPIO interrupts to count pulses while the main CPU is in Deep-sleep mode.
 
 API Reference

docs/en/api-reference/system/ulp-risc-v.rst

@@ -243,11 +243,23 @@ Keeping this in mind, here are some ways that may help you debug your ULP RISC-V
 Application Examples
 --------------------
 
-* ULP RISC-V Coprocessor polls GPIO while main CPU is in deep sleep: :example:`system/ulp/ulp_riscv/gpio`.
-* ULP RISC-V Coprocessor uses bit-banged UART driver to print: :example:`system/ulp/ulp_riscv/uart_print`.
-* ULP RISC-V Coprocessor reads external temperature sensor while main CPU is in deep sleep: :example:`system/ulp/ulp_riscv/ds18b20_onewire`.
-* ULP RISC-V Coprocessor reads external I2C temperature and humidity sensor (BMP180) while the main CPU is in Deep-sleep and wakes up the main CPU once a threshold is met: :example:`system/ulp/ulp_riscv/i2c`.
-* ULP RISC-V Coprocessor handles software interrupt and RTC IO interrupt: :example:`system/ulp/ulp_riscv/interrupts`.
+* :example:`system/ulp/ulp_riscv/gpio` demonstrates how to program the ULP-RISC-V coprocessor to monitor a GPIO pin and wake up the main CPU when its state changes.
+
+* :example:`system/ulp/ulp_riscv/uart_print` demonstrates how to program the ULP-RISC-V coprocessor on the development board to bitbang a UART TX line, allowing for output logging directly from the ULP-RISC-V coprocessor even when the main CPU is in deep sleep.
+
+.. only:: esp32s2
+
+    * :example:`system/ulp/ulp_riscv/ds18b20_onewire` demonstrates how to use the ULP-RISC-V co-processor to read temperature from a DS18B20 sensor over 1-Wire, and wake up the main CPU from deep-sleep when the temperature exceeds a set limit.
+
+* :example:`system/ulp/ulp_riscv/i2c` demonstrates how to use the RTC I2C peripheral from the ULP RISC-V coprocessor in deep sleep mode to periodically measure temperature and pressure values from the BMP180 sensor and wake up the main CPU when these values exceed a certain threshold.
+
+* :example:`system/ulp/ulp_riscv/interrupts` demonstrates how the ULP-RISC-V coprocessor can register and handle software and RTC IO triggered interrupts, keeping a count of the software interrupts and waking up the main processor from deep sleep after a certain threshold or when a button is pressed.
+
+* :example:`system/ulp/ulp_riscv/adc` demonstrates how to use the ULP-RISC-V coprocessor to periodically measure input voltage and wake up the system from deep sleep if the voltage exceeds a set threshold.
+
+* :example:`system/ulp/ulp_riscv/gpio_interrupt` demonstrates how to program the ULP-RISC-V coprocessor to wake up from a RTC IO interrupt using GPIO0 as the input signal, and how to configure and run the coprocessor, putting the chip into deep sleep mode until the wakeup source pin is pulled low.
+
+* :example:`system/ulp/ulp_riscv/touch` demonstrates how to program the ULP RISC-V coprocessor to periodically scan and read touch pad sensors, and wake up the main CPU when a touch pad is active.
 
 API Reference
 -------------

docs/en/api-reference/system/ulp.rst

@@ -19,7 +19,7 @@ If you have already set up ESP-IDF with CMake build system according to the :doc
 Programming ULP FSM
 -------------------
 
-The ULP FSM can be programmed using the supported instruction set. Alternatively, the ULP FSM coprocessor can also be programmed using C Macros on the main CPU. Theses two methods are described in the following section:
+The ULP FSM can be programmed using the supported instruction set. Alternatively, the ULP FSM coprocessor can also be programmed using C Macros on the main CPU. These two methods are described in the following section:
 
 .. toctree::
    :maxdepth: 1
@@ -176,8 +176,11 @@ Declaration of the entry point symbol comes from the generated header file menti
 Application Examples
 --------------------
 
-* ULP FSM Coprocessor counts pulses on an IO while main CPU is in Deep-sleep: :example:`system/ulp/ulp_fsm/ulp`.
-* ULP FSM Coprocessor polls ADC in while main CPU is in Deep-sleep: :example:`system/ulp/ulp_fsm/ulp_adc`.
+* :example:`system/ulp/ulp_fsm/ulp` demonstrates how to program the ULP FSM coprocessor to count pulses on an IO while the main CPUs are running other code or are in deep sleep, with the pulse count saved into NVS upon wakeup.
+
+.. only:: esp32 or esp32s3
+
+    * :example:`system/ulp/ulp_fsm/ulp_adc` demonstrates how to use the ULP FSM coprocessor to periodically measure input voltage on a specific ADC channel during deep sleep, compare it to the set threshold, and wake up the system if the voltage is outside the threshold.
 
 API Reference
 -------------

docs/en/api-reference/system/wdts.rst

@@ -174,13 +174,12 @@ JTAG & Watchdogs
 
 While debugging using OpenOCD, the CPUs are halted every time a breakpoint is reached. However if the watchdog timers continue to run when a breakpoint is encountered, they will eventually trigger a reset making it very difficult to debug code. Therefore OpenOCD will disable the hardware timers of both the interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not re-enable them upon leaving the breakpoint. This means that interrupt watchdog and task watchdog functionality will essentially be disabled. No warnings or panics from either watchdogs will be generated when the {IDF_TARGET_NAME} is connected to OpenOCD via JTAG.
 
+Application Examples
+--------------------
+
+- :example:`system/task_watchdog` demonstrates how to initialize, subscribe and unsubscribe tasks and users to the task watchdog, and how tasks and users can reset (feed) the task watchdog.
 
 API Reference
 -------------
 
-Task Watchdog
-^^^^^^^^^^^^^
-
-A full example using the Task Watchdog is available in esp-idf: :example:`system/task_watchdog`
-
 .. include-build-file:: inc/esp_task_wdt.inc

docs/zh_CN/api-guides/unit-tests.rst

@@ -368,3 +368,8 @@ Mocks
 这两种方法都会让组件模拟覆盖 ESP-IDF 中的现有组件。如果你使用的是 ESP-IDF 提供的组件模拟，则第二个方法更加方便。
 
 可参考 ``esp_event`` 基于主机的单元测试及其 :component_file:`esp_event/host_test/esp_event_unit_test/CMakeLists.txt` 作为组件模拟的示例。
+
+应用示例
+--------------------
+
+:example:`system/unit_test` 演示了如何在 {IDF_TARGET_NAME} 开发环境中使用 Unity 库为自定义组件添加单元测试，展示了如断言、测试注册等功能，以及如何使用 UNITY_BEGIN() 和 UNITY_END() 宏。

docs/zh_CN/api-reference/system/console.rst

@@ -186,13 +186,16 @@ Linenoise 库不需要显式地初始化，但是在调用行编辑函数之前
 
     同样，如果 REPL 环境是构建在 USB_SERIAL_JTAG 设备基础上，你只需要先调用 :cpp:func:`esp_console_new_repl_usb_serial_jtag` 函数进行初始化，然后再照常调用其它函数。
 
-应用程序示例
+应用示例
 ------------
 
-:example:`system/console` 目录下提供了 ``console`` 组件的示例应用程序，展示了具体的使用方法。该示例介绍了如何初始化 UART 和 VFS 的功能，设置 linenoise 库，从 UART 中读取命令并加以处理，然后将历史命令存储到 flash 中。更多信息，请参阅示例代码目录中的 README.md 文件。
+- :example:`system/console/basic` 演示了如何使用控制台组件的 REPL（读-评估-打印循环）API 在 {IDF_TARGET_NAME} 上创建一个交互式 Shell，该 Shell 可以通过串行接口控制，支持 UART 和 USB 接口，并可以作为需要命令行接口的应用程序的基础。
 
-此外，ESP-IDF 还提供了众多基于 ``console`` 组件的示例程序，它们可以辅助应用程序的开发。例如，:example:`peripherals/i2c/i2c_tools`，:example:`wifi/iperf` 等等。
+- :example:`system/console/advanced` 演示了如何使用控制台组件在 {IDF_TARGET_NAME} 上创建一个交互式 Shell，该 Shell 可以通过串行端口控制，为需要命令行接口的应用程序提供基础。
 
+.. only:: esp32s3
+
+    - :example:`system/console/advanced_usb_cdc` 演示了如何通过 {IDF_TARGET_NAME} 的 USB_OTG 外设创建并与具有命令行接口的交互式 Shell 进行交互。
 
 API 参考
 --------

docs/zh_CN/api-reference/system/esp_event.rst

@@ -215,11 +215,9 @@
 应用示例
 -------------------
 
-使用 ``esp_event`` 库的示例存放在 :example:`system/esp_event` 中，涵盖事件声明、循环创建、处理程序注册和注销以及事件发布。
+- :example:`system/esp_event/default_event_loop` 演示了如何使用 {IDF_TARGET_NAME} 的默认事件循环系统来发布和处理事件，包括声明和定义事件、创建默认事件循环、将事件发布到循环中，以及注册/注销事件处理程序。
 
-其他使用 ``esp_event`` 库的示例:
-
-    * :example:`NMEA Parser <peripherals/uart/nmea0183_parser>`，该示例将解码从 GPS 接收到的语句。
+- :example:`system/esp_event/user_event_loops` 演示了如何在 {IDF_TARGET_NAME} 上创建和使用用户事件循环，包括创建和运行事件循环、注册和注销处理程序、以及发布事件，能够处理超出默认事件循环的不同示例。
 
 API 参考
 -------------