Merge branch 'docs/add_application_examples_system_component' into 'master'
docs: add or update application examples of system component See merge request espressif/esp-idf!32004
This commit is contained in:
Zhang Xiao Yan
@@ -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
|
||||
-------------
|
||||
|
||||
@@ -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 <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
|
||||
-------------
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
----------------------------
|
||||
|
||||
|
||||
@@ -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
|
||||
-------------
|
||||
|
||||
@@ -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
|
||||
-------------
|
||||
|
||||
|
||||
@@ -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
|
||||
------------------------
|
||||
|
||||
@@ -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
|
||||
-------------
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
-------------
|
||||
|
||||
@@ -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
|
||||
-------------
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user