Merge branch 'docs/update_example_readme_template' into 'master'

docs: Update ESP Timer example README

See merge request espressif/esp-idf!29844
pull/13517/merge
Kirill Chalov 2024-04-16 10:40:11 +08:00
commit ddb6db4bb4
6 zmienionych plików z 197 dodań i 83 usunięć

Wyświetl plik

@ -11,8 +11,20 @@ Use actual documentation generated within about 20 minutes on each commit:
* English: https://docs.espressif.com/projects/esp-idf/en/latest/
* 中文: https://docs.espressif.com/projects/esp-idf/zh_CN/latest/
The above URLs are all for the master branch latest version. Click the drop-down in the bottom left to choose a stable version or to download a PDF.
After you click any link to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/index.html), go to the top of the sidebar, then make sure you have the correct Espressif chip (target) and ESP-IDF version selected in the dropdown menus. You can also find a link on the bottom right to download the PDF version.
# Building Documentation
The documentation is built using the python package `esp-docs`, which can be installed by running `pip install esp-docs`. Running `build-docs --help` will give a summary of available options. For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md
The documentation is built using the python package `esp-docs`, which can be installed by running:
```
pip install esp-docs
```
For a summary of available options, run:
```
build-docs --help
```
For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md

Wyświetl plik

@ -1,67 +1,138 @@
_Note that this is a template for an ESP-IDF example README.md file. When using this template, replace all these emphasised placeholders with example-specific content._
_Note that this is a template for an ESP-IDF example README.md file. When using this template, replace all the emphasized placeholders (in italics) with example-specific content._
| Supported Targets | _Supported target, e.g. ESP32_ | _Another supported target, e.g. ESP32-S3_ |
| ----------------- | ------------------------------ | ----------------------------------------- |
_For your reference and inspiration, the application README already following this template is [ESP Timer Example](../examples/system/esp_timer/README.md)._
_While creating your example, use this template in conjunction with the guidelines given in [Creating Examples](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/creating-examples.html)._
| Supported Targets | _ESP32_ | _ESP32-XX_ |
| ----------------- | ------- | ---------- |
_If the example supports all targets supported by ESP-IDF then the table can be omitted_
# _Example Title_
(See the README.md file in the upper level 'examples' directory for more information about examples.)
_Example Title should use the word "example" instead of "demo", "test" or any similar words._
(For general overview of examples and their usage, see the `README.md` file in the upper level 'examples' directory.)
> **Note**:
>
> After you click any link to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/index.html), go to the top of the sidebar, then make sure you have the appropriate **Espressif chip** (target) and **ESP-IDF version** selected in the dropdown menus.
_What is this example? What does it do?_
_What features of ESP-IDF does it use?_
_What feature(s) of ESP-IDF does this example use? Briefly introduce them and give a link to the API reference(s)._
_What could someone create based on this example? ie applications/use cases/etc_
_What could someone create based on this example? Think of applications, use cases, etc._
_If there are any acronyms or Espressif-only words used here, explain them or mention where in the datasheet/TRM this information can be found._
_If there are any acronyms or Espressif-only words used here, explain them or mention where in the hardware or software documentation this information can be found._
## Usage
The subsections below give only absolutely necessary information. For full steps to configure ESP-IDF and use it to build and run projects, see [ESP-IDF Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html#get-started).
## How to use example
### Hardware Required
_If possible, example should be able to run on any commonly available ESP32 development board. Otherwise, describe what specific hardware should be used._
_If possible, the example should be able to run on any commonly available development board based on a chip listed in the Supported Targets table. Otherwise, describe what specific hardware should be used._
_If any other items (server, BLE device, app, second chip, whatever) are needed, mention them here. Include links if applicable. Explain how to set them up._
_For beginner-friendly examples, provide a more detailed list of the required hardware. For more advanced examples, omit self-evident information._
### Configure the project
_If any other items (server, BLE device, app, second chip, whatever) are needed, mention them here. Include the links if applicable. Explain how to set them up._
_For examples where a chip is connected to some other hardware, include a table or schematics with connection details._
### Software Required _(optional)_
_If any additional software is needed, mention it here and include the links. Mention the software version required if applicable. Explain how to set it up._
### Set Chip Target
First of all, your target must be supported by both:
- **By your ESP-IDF version**: For the full list of supported targets, run:
```
idf.py --list-targets
```
- **By this example**: For the full list of supported targets, refer to the supported targets table at the top of this README.
After you make sure that your target is supported, go to your example project directory and [set the chip target](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tools/idf-py.html#select-the-target-chip-set-target):
```
idf.py set-target <target>
```
For example, to set esp32 as the chip target, run:
```
idf.py set-target esp32
```
### Configure the Project
_Set the required Kconfig options differing from the ESP-IDF defaults in [sdkconfig.defaults](./sdkconfig.defaults) and add comments there on WHY these options are needed. (Remember, WHAT these options do is already documented in the Project Configuration document, so no need to repeat this information.)_
_If the required Kconfig options are pre-set in `sdkconfig.defaults`, add the following sentences as a separate paragraph: This example does not need configuration. The required Kconfig options differing from the ESP-IDF defaults are pre-set for this particular example in [sdkconfig.defaults](./sdkconfig.defaults)._
For information about Kconfig options, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html) > _Name of relevant section(s)_.
To conveniently check or modify Kconfig options for this example in a project configuration menu, run:
```
idf.py menuconfig
```
* _If there is any project configuration that the user must set for this example, mention this here._
_If there is anything else that the user must configure for this example to work, mention it here._
### Build and Flash
Build the project and flash it to the board, then run monitor tool to view serial output:
Execute the following command to build the project, flash it to your development board, and run the monitor tool to view the serial output:
```
idf.py -p PORT flash monitor
idf.py build flash monitor
```
(Replace PORT with the name of the serial port to use.)
This command can be reduced to `idf.py flash monitor`.
(To exit the serial monitor, type ``Ctrl-]``.)
If the above command fails, check the log on the serial monitor which usually provides information on the possible cause of the issue.
To exit the serial monitor, use `Ctrl` + `]`.
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
## Example Output
_Include an example of the console output from the running example, here:_
_For different reasons, an example's console output might not be informative enough for the user to realize that something went wrong. To allow users to check that the example is running correctly on their side, be sure to include here the expected console output as given below._
If you see the following console output, your example should be running correctly:
```
Use this style for pasting the log.
Paste console output as a code snippet like this
```
_If the user is supposed to interact with the example at this point (read/write GATT attribute, send HTTP request, press button, etc. then mention it here)_
_If the user is supposed to interact with the example at this point, mention it here (read/write GATT attribute, send HTTP request, press button, etc.)_
## Example Breakdown _(optional)_
_If the example source code is lengthy, complex, or cannot be easily understood, use this section to break down and explain the source code. This can be done by breaking down the execution path step by step, or explaining what each major function/task/source file does. Add sub titles if necessary. Remove this section for very simple examples where the source code is self explanatory._
_For examples where ESP32 is connected with some other hardware, include a table or schematics with connection details._
## Troubleshooting
_If there are any likely problems or errors which many users might encounter, mention them here. Remove this section for very simple examples where nothing is likely to go wrong._
_Remove this section for very simple examples where nothing is likely to go wrong._
## Example Breakdown
_There might be typical issues or errors that the user is likely to encounter while working with this example. If the issue is related to the ESP-IDF feature in general, mention it in Troubleshooting of this feature's API reference. If the issue is related to this example only, mention such issue here._
_If the example source code is lengthy, complex, or cannot be easily understood, use this section to break down and explain the source code. This can be done by breaking down the execution path step by step, or explaining what each major function/task/source file does. Add sub titles if necessary. Remove this section for very simple examples where the source code is self explanatory._
For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub.
## Reference
_Provide references to important documents_
- Link to the ESP-IDF feature's API reference, for example [ESP-IDF: ESP Timer feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html)
- [ESP-IDF Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html#get-started)
- [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html) (Kconfig Options)

Wyświetl plik

@ -24,7 +24,6 @@ Checklist
Checklist before submitting a new example:
* Example project name (in ``README.md``) uses the word "example". Use "example" instead of "demo", "test" or similar words.
* Example does one distinct thing. If the example does more than one thing at a time, split it into two or more examples.
* Example has a ``README.md`` file which is similar to the :idf_file:`template example README <docs/TEMPLATE_EXAMPLE_README.md>`.
* Functions and variables in the example are named according to :ref:`naming section of the style guide <style-guide-naming>`. For non-static names which are only specific to the example's source files, you can use ``example`` or something similar as a prefix.

Wyświetl plik

@ -24,7 +24,6 @@
提交一个新的示例项目之前,需要检查以下内容:
- 示例项目的名字(包括 ``README.md`` 中)应使用 ``example``,而不要写 “demo”“test” 等词汇。
- 每个示例项目只能有一个主要功能。如果某个示例项目有多个主要功能,请将其拆分为两个或更多示例项目。
- 每个示例项目应包含一个 ``README.md`` 文件,建议使用 :idf_file:`示例项目 README 模板 <docs/TEMPLATE_EXAMPLE_README.md>`
- 示例项目中的函数和变量的命令要遵循 :ref:`命名规范 <style-guide-naming>` 中的要求。对于仅在示例项目源文件中使用的非静态变量/函数,请使用 ``example`` 或其他类似的前缀。

Wyświetl plik

@ -31,15 +31,56 @@ In addition to these examples, `commmon_components` directory contains code shar
## Using Examples
Before building an example, be sure to follow the [ESP-IDF Getting Started Guide](https://idf.espressif.com/) to ensure you have the required development environment.
Before building an example, follow the [ESP-IDF Getting Started](https://idf.espressif.com/) to ensure you have the required development environment.
Building an example is the same as building any other project:
### Set Chip Target
First of all, your target must be supported by both:
- **By your ESP-IDF version**: For the full list of supported targets, run:
```
idf.py --list-targets
```
- **By this example**: For the full list of supported targets, refer to the supported targets table at the top of this README.
After you make sure that your target is supported, go to your example project directory and [set the chip target](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tools/idf-py.html#select-the-target-chip-set-target):
```
idf.py set-target <target>
```
For example, to set esp32 as the chip target, run:
```
idf.py set-target esp32
```
### Configure the Project
For information about Kconfig options, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html) > ESP Timer (High Resolution Timer).
To conveniently check or modify Kconfig options for this example in a project configuration menu, run:
```
idf.py menuconfig
```
### Build and Flash
Execute the following command to build the project, flash it to your development board, and run the monitor tool to view the serial output:
```
idf.py build flash monitor
```
This command can be reduced to `idf.py flash monitor`.
If the above command fails, check the log on the serial monitor which usually provides information on the possible cause of the issue.
To exit the serial monitor, use `Ctrl` + `]`.
- Change into the directory of the new example you'd like to build.
- Run `idf.py set-target TARGET` to select the correct chip target to build before opening the project configuration menu. By default the target is `esp32`. For all options see `idf.py set-target --help`
- Run `idf.py menuconfig` to open the project configuration menu. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use).
- `idf.py build` to build the example.
- Follow the printed instructions to flash, or run `idf.py -p PORT flash`.
## Running Test Python Script (pytest)

Wyświetl plik

@ -3,18 +3,19 @@
# ESP Timer Example (High Resolution Timer)
(See the README.md file in the upper level 'examples' directory for more information about examples.)
(For general overview of examples and their usage, see the [README](../../README.md) file in the upper level `examples` directory.)
This example shows how to use the ESP Timer feature. For detailed information on the functions and procedures used in this example, see [ESP Timer API Reference](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html).
> **Note**:
>
> After you click any link to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/index.html), go to the top of the sidebar, then make sure you have the appropriate **Espressif chip** (target) and **ESP-IDF version** selected in the dropdown menus.
> **Note**: By default, all links to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/index.html) refer to the documentation for the ESP32. After clicking such a link, please remember to select your Espressif chip in the dropdown menu in the top-left corner.
This example shows how to use the [ESP Timer](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html) feature to create timers and execute callback functions. On the linked page, you will find detailed information about the feature as well as the functions and procedures used in this example.
In addition, the [Sleep Modes](https://docs.espressif.com/projects/esp-idf/en/stable/api-reference/system/sleep_modes.html) feature is used to briefly enter light sleep. This demonstrates that timekeeping continues correctly after light sleep.
## Overview
The example starts by creating and starting a periodic and a one-shot timer. Their callback functions print the time elapsed since the example was booted. Then the `oneshot_timer_callback()` function redefines the period of the periodic timer and restarts it.
The ESP Timer facilitates creation and handling of timers that invoke callback functions (dispatch callbacks) on timeout. ESP Timer is mainly used to perform delayed or periodic actions, such as delayed device start/stop or periodic sampling of sensor data.
ESP Timer hides the complexity associated with managing multiple timers, dispatching callbacks, accounting for clock frequency changes (if dynamic frequency scaling is enabled), and maintaining correct time after light sleep.
After that, the chip enters light sleep for 0.5 seconds. Once the chip wakes up, the timers execute a couple of more callback functions, then the timers are stopped and deleted to free up memory.
## Usage
@ -22,32 +23,43 @@ ESP Timer hides the complexity associated with managing multiple timers, dispatc
The subsections below give only absolutely necessary information. For full steps to configure ESP-IDF and use it to build and run projects, see [ESP-IDF Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html#get-started).
### Required Hardware
### Hardware Required
* An Espressif development board based on a chip listed in supported targets
* A USB cable for power supply and serial communication
* Computer with ESP-IDF installed and configured
* An Espressif development board
* USB A/micro USB B cable for power supply and serial communication
* Computer running Windows, Linux, or macOS
### Set Chip Target
In your example project directory, [set the chip target](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tools/idf-py.html#select-the-target-chip-set-target):
First of all, your target must be supported by both:
- **By your ESP-IDF version**: For the full list of supported targets, run:
```
idf.py --list-targets
```
- **By this example**: For the full list of supported targets, refer to the supported targets table at the top of this README.
After you make sure that your target is supported, go to your example project directory and [set the chip target](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tools/idf-py.html#select-the-target-chip-set-target):
```
idf.py set-target <target>
```
For example, to set esp32 as the chip target, run
For example, to set esp32 as the chip target, run:
```
idf.py set-target esp32
```
### Review Kconfig Options
### Configure the Project
This project has some Kconfig options set as default for this particular example in [sdkconfig.defaults](./sdkconfig.defaults). For more information about those and other Kconfig options, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html).
This example does not need configuration. The required Kconfig options differing from the ESP-IDF defaults are pre-set for this particular example in [sdkconfig.defaults](./sdkconfig.defaults).
To conveniently check or modify Kconfig options for this example, run:
For more information about those and other Kconfig options, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html#esp-timer-high-resolution-timer) > ESP Timer (High Resolution Timer).
To conveniently check or modify Kconfig options for this example in a project configuration menu, run:
```
idf.py menuconfig
@ -56,27 +68,22 @@ idf.py menuconfig
### Build and Flash
Build the project, flash it to your development board, then run the monitor tool to view serial output:
Execute the following command to build the project, flash it to your development board, and run the monitor tool to view the serial output:
```
idf.py build flash monitor
```
If the above command fails, try specifying your board's serial port name explicitly:
This command can be reduced to `idf.py flash monitor`.
```
# Replace PORT with your board's serial port name
idf.py -p PORT build flash monitor
```
### Exit the Serial Monitor
If the above command fails, check the log on the serial monitor which usually provides information on the possible cause of the issue.
To exit the serial monitor, use `Ctrl` + `]`.
## Example Output
If you see the following output log, your example should be running correctly:
If you see the following console output, your example should be running correctly:
```
...
@ -118,28 +125,17 @@ I (10314) example: Woke up from light sleep, time since boot: 10525143 us
The subsections below walk you through the important parts of the application example.
### Creating Callback Functions
Timers are used to execute a callback function as a delayed action. So the callback functions `periodic_timer_callback()` and `oneshot_timer_callback()` are the most important parts of this application example. They are defined for the periodic and one-shot timers respectively.
### Setting Timer Configuration Parameters
The struct `esp_timer_create_args_t` is used to initialize a timer. Its parameters are described in *ESP Timer API Reference* > [esp_timer_create_args_t](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html#esp_timer_create_args_t).
The defined struct instance is then used in the function `esp_timer_create()`.
### Creating and Starting Timers
To run a timer, it needs to be created first using the function `esp_timer_create()` and then started using either `esp_timer_start_periodic()` or `esp_timer_start_once()` depending on the timer type.
Timers are used to execute a callback function as a delayed action. So the callback functions `periodic_timer_callback()` and `oneshot_timer_callback()` are crucial parts of this application example.
### Printing Timer Dumps
The function `esp_timer_dump()` is used to print the timer dumps which can be useful for debugging purposes. For details, see *ESP Timer API Reference* > [Debugging Timers](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html#debugging-timers).
To make the output of the dump function more detailed, this example's file `sdkconfig.defaults` has the option `CONFIG_ESP_TIMER_PROFILING` set (see [Review Kconfig Options](#review-kconfig-options)).
To make the output of the dump function more detailed, this example's file `sdkconfig.defaults` has the option `CONFIG_ESP_TIMER_PROFILING` set (see [Configure the Project](#configure-the-project)).
### Entering and Waking Up from Light Sleep
@ -149,18 +145,14 @@ To demonstrate that timekeeping continues correctly after light sleep, the examp
During light sleep, the CPU is not running, so callbacks cannot be dispatched. On wakeup, the system attempts to execute all unhandled callbacks if any, then ESP Timer resumes its normal operation.
### Stopping and Deleting Timers
Once the timers are not needed anymore, they are stopped and deleted to free up memory using `esp_timer_stop()` and `esp_timer_delete()`.
## Troubleshooting
For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you as soon as possible.
For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub.
## Reference
- [ESP-IDF ESP Timer](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html)
- [ESP-IDF: ESP Timer feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html)
- [ESP-IDF: Sleep Modes feature](https://docs.espressif.com/projects/esp-idf/en/stable/api-reference/system/sleep_modes.html)
- [ESP-IDF Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html#get-started)
- [Kconfig Options](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html)
- [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html#esp-timer-high-resolution-timer) (Kconfig Options)