diff --git a/docs/en/api-guides/unit-tests.rst b/docs/en/api-guides/unit-tests.rst index de436d226c..83ada64a01 100644 --- a/docs/en/api-guides/unit-tests.rst +++ b/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. diff --git a/docs/en/api-reference/system/console.rst b/docs/en/api-reference/system/console.rst index 107be3695d..ea59f229d2 100644 --- a/docs/en/api-reference/system/console.rst +++ b/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 ------------- diff --git a/docs/en/api-reference/system/esp_event.rst b/docs/en/api-reference/system/esp_event.rst index 8bf7dfb507..7cb522f772 100644 --- a/docs/en/api-reference/system/esp_event.rst +++ b/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 -------------------- +Application Examples +-------------------- -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. +- :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. -Other examples which also adopt ``esp_event`` library: - - * :example:`NMEA 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 ------------- diff --git a/docs/en/api-reference/system/esp_timer.rst b/docs/en/api-reference/system/esp_timer.rst index eb2d7456e3..3984692dd4 100644 --- a/docs/en/api-reference/system/esp_timer.rst +++ b/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 diff --git a/docs/en/api-reference/system/freertos.rst b/docs/en/api-reference/system/freertos.rst index 92a5ef0932..0633d8641d 100644 --- a/docs/en/api-reference/system/freertos.rst +++ b/docs/en/api-reference/system/freertos.rst @@ -140,3 +140,10 @@ Vanilla FreeRTOS provides its own `selection of heap implementations `，该示例将解码从 GPS 接收到的语句。 +- :example:`system/esp_event/user_event_loops` 演示了如何在 {IDF_TARGET_NAME} 上创建和使用用户事件循环，包括创建和运行事件循环、注册和注销处理程序、以及发布事件，能够处理超出默认事件循环的不同示例。 API 参考 ------------- diff --git a/docs/zh_CN/api-reference/system/freertos.rst b/docs/zh_CN/api-reference/system/freertos.rst index f1ebb9d867..bccfb14da3 100644 --- a/docs/zh_CN/api-reference/system/freertos.rst +++ b/docs/zh_CN/api-reference/system/freertos.rst @@ -140,3 +140,10 @@ FreeRTOS 堆 - 使用一个 ``...CreateWithCaps()`` API，如 :cpp:func:`xTaskCreateWithCaps` 和 :cpp:func:`xQueueCreateWithCaps` 来分配任务或对象（参见 :ref:`freertos-idf-additional-api` 获取更多详细信息）。 - 使用 :cpp:func:`heap_caps_malloc` 为这些对象手动分配外部内存，然后使用 FreeRTOS 的一个 ``...CreateStatic()`` 函数从分配的内存中创建对象。 + +应用示例 +-------------------- + +- :example:`system/freertos/basic_freertos_smp_usage` 演示了如何在 {IDF_TARGET_NAME} 的 SMP 架构中使用基本的 FreeRTOS API 进行任务创建、通信、同步和批处理。 + +- :example:`system/freertos/real_time_stats` 演示了如何使用 FreeRTOS 的 vTaskGetRunTimeStats() 函数来获取任务在指定时间段内的 CPU 使用统计信息，而不是整个 FreeRTOS 运行时间的统计信息。 diff --git a/docs/zh_CN/api-reference/system/heap_debug.rst b/docs/zh_CN/api-reference/system/heap_debug.rst index e9634c47b5..86c7cf18f7 100644 --- a/docs/zh_CN/api-reference/system/heap_debug.rst +++ b/docs/zh_CN/api-reference/system/heap_debug.rst @@ -510,6 +510,11 @@ ESP-IDF 集成了用于请求 :ref:`堆内存信息 `、:ref:` 要区分“真实”和“误报”的内存泄漏，可以在堆内存跟踪运行时多次调用可疑代码，并在堆内存跟踪输出中查找重复出现的内存分配情况。 +应用示例 +-------------------- + +- :example:`system/heap_task_tracking` 演示了如何使用堆任务跟踪功能跟踪分配给每个任务的堆内存。 + API 参考 - 堆内存跟踪 ---------------------------- diff --git a/docs/zh_CN/api-reference/system/himem.rst b/docs/zh_CN/api-reference/system/himem.rst index 4fb404ccbb..34322c4b57 100644 --- a/docs/zh_CN/api-reference/system/himem.rst +++ b/docs/zh_CN/api-reference/system/himem.rst @@ -17,11 +17,10 @@ ESP32 仍可使用大于等于 4 MiB 大小的 SPI RAM 芯片。不过，这些 Himem API 可以看作是存储体切换方案的一个抽象。具体而言，该 API 允许声明一个或多个地址空间存储体（在 API 中称为“regions”），以及一个或多个需映射到此范围的内存存储体。 -示例 -------- - -ESP-IDF 中提供了对大内存范围进行简单内存测试的示例，请前往 :example:`system/himem` 查看。 +应用示例 +-------------------- +- :example:`system/himem` 演示了如何在 {IDF_TARGET_NAME} 上使用 Himem API 对 8 MiB PSRAM 芯片的上部 4 MiB 进行内存测试，展示了如何分配地址空间、分配物理内存，并在分配的地址空间中切换内存。 API 参考 ------------- diff --git a/docs/zh_CN/api-reference/system/ipc.rst b/docs/zh_CN/api-reference/system/ipc.rst index 946d6afaac..24cbd6f09c 100644 --- a/docs/zh_CN/api-reference/system/ipc.rst +++ b/docs/zh_CN/api-reference/system/ipc.rst @@ -146,6 +146,17 @@ IPC 功能提供了下列 API，以在高优先级中断的上下文中执行回 :CONFIG_IDF_TARGET_ARCH_XTENSA: - :cpp:func:`esp_ipc_isr_stall_other_cpu`：暂停目标内核。调用内核禁用 3 级及以下级别的中断，而目标内核将在 5 级及以下的中断被禁用的情况下进入忙等待。在调用 :cpp:func:`esp_ipc_isr_release_other_cpu` 前，目标内核会保持忙等待。 - :cpp:func:`esp_ipc_isr_release_other_cpu`：恢复目标内核。 +应用示例 +-------------------- + +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA + + - :example:`system/ipc/ipc_isr/xtensa` 演示了如何在高优先级中断的上下文中使用 IPC ISR 功能运行 IPC，允许用户快速获取另一个 CPU 的状态，包括两个汇编回调函数，这些回调函数返回另一个核心的 PS 寄存器并在执行基于输入参数的任务时保存/恢复寄存器。 + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + - :example:`system/ipc/ipc_isr/riscv` 演示了如何在 {IDF_TARGET_NAME} 上使用 IPC ISR 功能在高优先级中断的上下文中运行 IPC，包括如何快速获取另一个 CPU 的状态以及如何从回调函数返回多个值。 + API 参考 ------------- diff --git a/docs/zh_CN/api-reference/system/perfmon.rst b/docs/zh_CN/api-reference/system/perfmon.rst index 69f50fa966..f0ea7d336e 100644 --- a/docs/zh_CN/api-reference/system/perfmon.rst +++ b/docs/zh_CN/api-reference/system/perfmon.rst @@ -8,7 +8,7 @@ 应用示例 ------------------- -在目录 ``examples/system/perfmon`` 下提供了一个结合性能监视器的示例。此示例初始化并执行了性能监视器，同时打印了统计信息。 +- :example:`system/perfmon` 演示了如何使用 `perfmon` API 来监控和分析函数性能。 高级 API 参考 ------------------------ diff --git a/docs/zh_CN/api-reference/system/pthread.rst b/docs/zh_CN/api-reference/system/pthread.rst index 989f154553..0f39db1b30 100644 --- a/docs/zh_CN/api-reference/system/pthread.rst +++ b/docs/zh_CN/api-reference/system/pthread.rst @@ -195,13 +195,12 @@ ESP-IDF 扩展 此配置的作用范围是调用线程或 FreeRTOS 任务，这意味着 :cpp:func:`esp_pthread_set_cfg` 可以在不同的线程或任务中独立调用。如果在当前配置中设置了 ``inherit_cfg`` 标志，那么当一个线程递归调用 ``pthread_create()`` 时，任何新创建的线程都会继承该线程的配置，否则新线程将采用默认配置。 -示例 --------- +应用示例 +------------------- - :example:`system/pthread` 演示了如何使用 pthread API 创建线程。 - :example:`cxx/pthread` 演示了如何通过线程使用 C++ 标准库函数。 - API 参考 ------------- diff --git a/docs/zh_CN/api-reference/system/ulp-lp-core.rst b/docs/zh_CN/api-reference/system/ulp-lp-core.rst index 4b57b746e9..545024ee67 100644 --- a/docs/zh_CN/api-reference/system/ulp-lp-core.rst +++ b/docs/zh_CN/api-reference/system/ulp-lp-core.rst @@ -224,11 +224,18 @@ ULP LP-Core 中断 应用示例 -------- -* 在示例 :example:`system/ulp/lp_core/gpio` 中，ULP LP-Core 协处理器在主 CPU 深度睡眠时轮询 GPIO。 -* 在示例 :example:`system/ulp/lp_core/lp_i2c` 中，ULP LP-Core 协处理器在主 CPU 深度睡眠时读取外部 I2C 环境光传感器 (BH1750)，并在达到阈值时唤醒主 CPU。 -* 在示例 :example:`system/ulp/lp_core/lp_uart/lp_uart_echo` 中，低功耗内核上运行的 LP UART 驱动程序读取并回显写入串行控制台的数据。 +* :example:`system/ulp/lp_core/gpio` 展示了 ULP LP-Core 协处理器在主 CPU 深度睡眠时轮询 GPIO。 + +.. only:: esp32c6 + + * :example:`system/ulp/lp_core/lp_i2c` 展示了 ULP LP-Core 协处理器在主 CPU 深度睡眠时读取外部 I2C 环境光传感器 (BH1750)，并在达到阈值时唤醒主 CPU。 + +* :example:`system/ulp/lp_core/lp_uart/lp_uart_echo` 展示了低功耗内核上运行的 LP UART 驱动程序如何读取并回显写入串行控制台的数据。 + * :example:`system/ulp/lp_core/lp_uart/lp_uart_print` 展示了如何在低功耗内核上使用串口打印功能。 + * :example:`system/ulp/lp_core/interrupt` 展示了如何在 LP 内核上注册中断处理程序，接收由主 CPU 触发的中断。 + * :example:`system/ulp/lp_core/gpio_intr_pulse_counter` 展示了如何在主 CPU 处于 Deep-sleep 模式时，使用 GPIO 中断为脉冲计数。 API 参考 diff --git a/docs/zh_CN/api-reference/system/ulp-risc-v.rst b/docs/zh_CN/api-reference/system/ulp-risc-v.rst index 56d42d6371..f3ab1123c2 100644 --- a/docs/zh_CN/api-reference/system/ulp-risc-v.rst +++ b/docs/zh_CN/api-reference/system/ulp-risc-v.rst @@ -243,11 +243,23 @@ ULP RISC-V 的中断处理尚在开发中，还不支持针对内部中断源的 应用示例 -------------------- -* 主 CPU 处于 Deep-sleep 状态时，ULP RISC-V 协处理器轮询 GPIO：:example:`system/ulp/ulp_riscv/gpio`。 -* ULP RISC-V 协处理器使用 bit-banged UART 驱动程序打印：:example:`system/ulp/ulp_riscv/uart_print`. -* 主 CPU 处于 Deep-sleep 状态时，ULP RISC-V 协处理器读取外部温度传感器：:example:`system/ulp/ulp_riscv/ds18b20_onewire`。 -* 主 CPU 处于 Deep-sleep 状态时，ULP RISC-V 协处理器读取外部 I2C 温度和湿度传感器 (BMP180)，达到阈值时唤醒主 CPU：:example:`system/ulp/ulp_riscv/i2c`. -* 使用 ULP RISC-V 协处理器处理软件中断和 RTC IO 中断：:example:`system/ulp/ulp_riscv/interrupts`. +* :example:`system/ulp/ulp_riscv/gpio` 演示了如何通过 ULP-RISC-V 协处理器监控 GPIO 引脚，并在其状态发生变化时唤醒主 CPU。 + +* :example:`system/ulp/ulp_riscv/uart_print` 演示了如何在开发板上使用 ULP-RISC-V 协处理器通过 bitbang 实现 UART 发射，即使在主 CPU 处于深度睡眠状态时也能直接从 ULP-RISC-V 协处理器输出日志。 + +.. only:: esp32s2 + + * :example:`system/ulp/ulp_riscv/ds18b20_onewire` 演示了如何使用 ULP-RISC-V 协处理器通过 1-Wire 协议读取 DS18B20 传感器的温度，并在温度超过阈值时唤醒主 CPU。 + +* :example:`system/ulp/ulp_riscv/i2c` 演示了如何在深度睡眠模式下使用 ULP RISC-V 协处理器的 RTC I2C 外设定期测量 BMP180 传感器的温度和压力值，并在这些值超过阈值时唤醒主 CPU。 + +* :example:`system/ulp/ulp_riscv/interrupts` 演示了 ULP-RISC-V 协处理器如何注册和处理软件中断和 RTC IO 触发的中断，记录软件中断的计数，并在达到某个阈值后或按下按钮时唤醒主 CPU。 + +* :example:`system/ulp/ulp_riscv/adc` 演示了如何使用 ULP-RISC-V 协处理器定期测量输入电压，并在电压超过设定阈值时唤醒系统。 + +* :example:`system/ulp/ulp_riscv/gpio_interrupt` 演示了如何使用 ULP-RISC-V 协处理器以通过 RTC IO 中断从深度睡眠中唤醒，使用 GPIO0 作为输入信号，并配置和运行协处理器，将芯片置于深度睡眠模式，直到唤醒源引脚被拉低。 + +* :example:`system/ulp/ulp_riscv/touch` 演示了如何使用 ULP RISC-V 协处理器定期扫描和读取触摸传感器，并在触摸传感器被激活时唤醒主 CPU。 API 参考 ------------- diff --git a/docs/zh_CN/api-reference/system/ulp.rst b/docs/zh_CN/api-reference/system/ulp.rst index a553620663..3ea2bdf5ce 100644 --- a/docs/zh_CN/api-reference/system/ulp.rst +++ b/docs/zh_CN/api-reference/system/ulp.rst @@ -176,8 +176,11 @@ ULP FSM 协处理器代码由汇编语言编写，使用 `binutils-esp32ulp 工 应用示例 -------------------- -* 主处理器处于 Deep-sleep 状态时，ULP FSM 协处理器对 IO 脉冲进行计数：:example:`system/ulp/ulp_fsm/ulp`。 -* 主处理器处于 Deep-sleep 状态时，ULP FSM 协处理器轮询 ADC：:example:`system/ulp/ulp_fsm/ulp_adc`。 +* :example:`system/ulp/ulp_fsm/ulp` 展示了主处理器运行其他代码或处于 Deep-sleep 状态时，使用 ULP FSM 协处理器对 IO 脉冲进行计数，脉冲计数会在唤醒时保存到 NVS 中。 + +.. only:: esp32 or esp32s3 + + * :example:`system/ulp/ulp_fsm/ulp_adc` 展示了主处理器处于 Deep-sleep 状态时，ULP FSM 协处理器测量特定 ADC 通道上的输入电压，将其与设定的阈值进行比较，电压超出阈值时唤醒系统。 API 参考 ------------- diff --git a/docs/zh_CN/api-reference/system/wdts.rst b/docs/zh_CN/api-reference/system/wdts.rst index 3352cc5572..482112b91e 100644 --- a/docs/zh_CN/api-reference/system/wdts.rst +++ b/docs/zh_CN/api-reference/system/wdts.rst @@ -174,13 +174,12 @@ JTAG & 看门狗 在使用 OpenOCD 进行调试时，CPU 会在每次达到断点时停止运行。然而，如果遇到断点后看门狗定时器继续运行，就会最终触发复位，为调试代码带来巨大的困难。因此， OpenOCD 会在每个断点处禁用中断和任务的看门狗的硬件定时器。此外，在离开断点时，OpenOCD 也不会重新启用定时器，也就是说，中断看门狗和任务看门狗实际上被禁用。当 {IDF_TARGET_NAME} 通过 JTAG 连接到 OpenOCD 时，看门狗不会打印任何警告或出现严重错误。 +应用示例 +-------------------- + +- :example:`system/task_watchdog` 演示了如何初始化、订阅和取消订阅任务看门狗的任务和用户，以及任务和用户如何重置任务看门狗。 API 参考 ------------- -任务看门狗 -^^^^^^^^^^^^^ - -在 ESP-IDF 中使用任务看门狗的完整示例：:example:`system/task_watchdog` - .. include-build-file:: inc/esp_task_wdt.inc