mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/h2_timer_docs_v5.1' into 'release/v5.1'
docs: updated misc docs with H2 specific information. (v5.1) See merge request espressif/esp-idf!24136
This commit is contained in:
Marius Vikhammer
commit
7f69e29bff
@ -1,12 +1,3 @@
|
||||
languages
|
||||
contribute/esp-idf-tests-with-pytest
|
||||
contribute/contributor-agreement
|
||||
contribute/documenting-code
|
||||
contribute/creating-examples
|
||||
contribute/style-guide
|
||||
contribute/copyright-guide
|
||||
contribute/install-pre-commit-hook
|
||||
contribute/index
|
||||
api-guides/RF_calibration
|
||||
api-guides/coexist
|
||||
api-guides/wifi
|
||||
@ -16,18 +7,9 @@ api-guides/dfu
|
||||
api-guides/wifi-security
|
||||
api-guides/index
|
||||
api-guides/openthread
|
||||
third-party-tools/platformio
|
||||
COPYRIGHT
|
||||
libraries-and-frameworks/libs-frameworks
|
||||
libraries-and-frameworks/index
|
||||
libraries-and-frameworks/cloud-frameworks
|
||||
versions
|
||||
api-reference/peripherals/usb_host
|
||||
api-reference/peripherals/usb_device
|
||||
api-reference/peripherals/i2s
|
||||
api-reference/peripherals/spi_features
|
||||
api-reference/peripherals/sdio_slave
|
||||
api-reference/peripherals/spi_flash/xip_from_psram.inc
|
||||
api-reference/peripherals/adc_calibration
|
||||
api-reference/peripherals/dedic_gpio
|
||||
api-reference/peripherals/sd_pullup_requirements
|
||||
@ -41,9 +23,6 @@ api-reference/network/esp_smartconfig
|
||||
api-reference/network/esp_wifi
|
||||
api-reference/network/index
|
||||
api-reference/system/sleep_modes
|
||||
api-reference/system/chip_revision
|
||||
api-reference/system/esp_timer
|
||||
api-reference/system/system_time
|
||||
api-reference/system/power_management
|
||||
api-reference/system/inc/power_management_esp32
|
||||
api-reference/system/inc/power_management_esp32s2_and_later
|
||||
@ -51,31 +30,3 @@ api-reference/protocols/esp_serial_slave_link
|
||||
api-reference/protocols/esp_sdio_slave_protocol
|
||||
api-reference/protocols/modbus
|
||||
api-reference/protocols/index
|
||||
about
|
||||
resources
|
||||
migration-guides/release-5.x/5.1/index
|
||||
migration-guides/release-5.x/5.1/peripherals
|
||||
migration-guides/release-5.x/5.0/gcc
|
||||
migration-guides/release-5.x/5.0/removed-components
|
||||
migration-guides/release-5.x/5.0/protocols
|
||||
migration-guides/release-5.x/5.0/networking
|
||||
migration-guides/release-5.x/5.0/provisioning
|
||||
migration-guides/release-5.x/5.0/build-system
|
||||
migration-guides/release-5.x/5.0/storage
|
||||
migration-guides/release-5.x/5.0/index
|
||||
migration-guides/release-5.x/5.0/system
|
||||
migration-guides/release-5.x/5.0/tools
|
||||
migration-guides/release-5.x/5.0/peripherals
|
||||
migration-guides/index
|
||||
get-started/establish-serial-connection
|
||||
get-started/linux-macos-setup
|
||||
get-started/linux-macos-start-project
|
||||
get-started/windows-setup
|
||||
get-started/start-project
|
||||
get-started/flashing-troubleshooting
|
||||
get-started/windows-start-project
|
||||
get-started/index
|
||||
get-started/windows-setup-update
|
||||
404
|
||||
index
|
||||
hw-reference/index
|
||||
|
||||
@ -35,6 +35,12 @@ About
|
||||
|
||||
The {IDF_TARGET_NAME} is a 2.4 GHz Wi-Fi, Bluetooth Low Energy, and 802.15.4 Thread/Zigbee combo SoC, which integrates a 32-bit RISC-V RV32IMAC single-core processor.
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for {IDF_TARGET_NAME}.
|
||||
|
||||
The {IDF_TARGET_NAME} is a Bluetooth Low Energy and 802.15.4 Thread/Zigbee combo SoC, which integrates a 32-bit RISC-V RV32IMAC single-core processor.
|
||||
|
||||
.. figure:: ../_static/about-doc.png
|
||||
:align: center
|
||||
:alt: Espressif IoT Integrated Development Framework
|
||||
|
||||
@ -1,46 +1,51 @@
|
||||
High Resolution Timer (ESP Timer)
|
||||
=================================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{IDF_TARGET_HR_TIMER:default = "SYSTIMER", esp32 = "LAC timer"}
|
||||
|
||||
{IDF_TARGET_HR_TIMER_Resolution:default = "Not updated", esp32 = "64", esp32s2 = "64", esp32c3 = "52", esp32s3 = "52", esp32c2 = "52", esp32c6 = "52"}
|
||||
{IDF_TARGET_HR_TIMER_Resolution:default = "Not updated", esp32 = "64", esp32s2 = "64", esp32c3 = "52", esp32s3 = "52", esp32c2 = "52", esp32c6 = "52", esp32h2 = "52"}
|
||||
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Although FreeRTOS provides software timers, these timers have a few limitations:
|
||||
Although FreeRTOS provides software timers, FreeRTOS software timers have a few limitations:
|
||||
|
||||
- Maximum resolution is equal to RTOS tick period
|
||||
- Timer callbacks are dispatched from a low-priority task
|
||||
- Maximum resolution is equal to the RTOS tick period
|
||||
- Timer callbacks are dispatched from a low-priority timer service (i.e., daemon) task. This task can be preempted by other tasks, leading to decreased precision and accuracy.
|
||||
|
||||
Hardware timers are free from both of the limitations, but often they are less convenient to use. For example, application components may need timer events to fire at certain times in the future, but the hardware timer only contains one "compare" value used for interrupt generation. This means that some facility needs to be built on top of the hardware timer to manage the list of pending events can dispatch the callbacks for these events as corresponding hardware interrupts happen.
|
||||
Although hardware timers are not subject to the limitations mentioned, they may not be as user-friendly. For instance, application components may require timer events to be triggered at specific future times, but hardware timers typically have only one "compare" value for interrupt generation. This necessitates the creation of an additional system on top of the hardware timer to keep track of pending events and ensure that callbacks are executed when the corresponding hardware interrupts occur.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The hardware timer interrupt's priority is configured via the :ref:`CONFIG_ESP_TIMER_INTERRUPT_LEVEL` option (possible priorities being 1, 2, or 3). Raising the timer interrupt's priority can reduce the timer processing delay caused by interrupt latency.
|
||||
|
||||
An interrupt level of the handler depends on the :ref:`CONFIG_ESP_TIMER_INTERRUPT_LEVEL` option. It allows to set this: 1, 2 or 3 level (by default 1). Raising the level, the interrupt handler can reduce the timer processing delay.
|
||||
|
||||
``esp_timer`` set of APIs provides one-shot and periodic timers, microsecond time resolution, and {IDF_TARGET_HR_TIMER_Resolution}-bit range.
|
||||
|
||||
Internally, ``esp_timer`` uses a {IDF_TARGET_HR_TIMER_Resolution}-bit hardware timer, where the implementation depends on the target. {IDF_TARGET_HR_TIMER} is used for {IDF_TARGET_NAME}.
|
||||
Internally, ``esp_timer`` uses a {IDF_TARGET_HR_TIMER_Resolution}-bit hardware timer. The exact hardware timer implementation used will depend on the target, where {IDF_TARGET_HR_TIMER} is used for {IDF_TARGET_NAME}.
|
||||
|
||||
Timer callbacks can be dispatched by two methods:
|
||||
|
||||
- ``ESP_TIMER_TASK``
|
||||
- ``ESP_TIMER_TASK``.
|
||||
- ``ESP_TIMER_ISR``. Available only if :ref:`CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD` is enabled (by default disabled).
|
||||
|
||||
``ESP_TIMER_TASK``. Timer callbacks are dispatched from a high-priority ``esp_timer`` task. Because all the callbacks are dispatched from the same task, it is recommended to only do the minimal possible amount of work from the callback itself, posting an event to a lower priority task using a queue instead.
|
||||
``ESP_TIMER_TASK``. Timer callbacks are dispatched from a high-priority ``esp_timer`` task. Because all the callbacks are dispatched from the same task, it is recommended to only do the minimal possible amount of work from the callback itself, posting an event to a lower-priority task using a queue instead.
|
||||
|
||||
If other tasks with priority higher than ``esp_timer`` are running, callback dispatching will be delayed until ``esp_timer`` task has a chance to run. For example, this will happen if an SPI Flash operation is in progress.
|
||||
If other tasks with a priority higher than ``esp_timer`` are running, callback dispatching will be delayed until the ``esp_timer`` task has a chance to run. For example, this will happen if an SPI Flash operation is in progress.
|
||||
|
||||
``ESP_TIMER_ISR``. Timer callbacks are dispatched directly from the timer interrupt handler. This method is useful for some simple callbacks which aim for lower latency.
|
||||
|
||||
Creating and starting a timer, and dispatching the callback takes some time. Therefore, there is a lower limit to the timeout value of one-shot ``esp_timer``. If :cpp:func:`esp_timer_start_once` is called with a timeout value less than 20us, the callback will be dispatched only after approximately 20us.
|
||||
Creating and starting a timer, and dispatching the callback takes some time. Therefore, there is a lower limit to the timeout value of one-shot ``esp_timer``. If :cpp:func:`esp_timer_start_once` is called with a timeout value of less than 20 us, the callback will be dispatched only after approximately 20 us.
|
||||
|
||||
Periodic ``esp_timer`` also imposes a 50us restriction on the minimal timer period. Periodic software timers with period of less than 50us are not practical since they would consume most of the CPU time. Consider using dedicated hardware peripherals or DMA features if you find that a timer with small period is required.
|
||||
Periodic ``esp_timer`` also imposes a 50 us restriction on the minimal timer period. Periodic software timers with a period of less than 50 us are not practical since they would consume most of the CPU time. Consider using dedicated hardware peripherals or DMA features if you find that a timer with a small period is required.
|
||||
|
||||
Using ``esp_timer`` APIs
|
||||
------------------------
|
||||
|
||||
Single timer is represented by :cpp:type:`esp_timer_handle_t` type. Timer has a callback function associated with it. This callback function is called from the ``esp_timer`` task each time the timer elapses.
|
||||
A single timer is represented by :cpp:type:`esp_timer_handle_t` type. Each timer has a callback function associated with it. This callback function is called from the ``esp_timer`` task each time the timer elapses.
|
||||
|
||||
- To create a timer, call :cpp:func:`esp_timer_create`.
|
||||
- To delete the timer when it is no longer needed, call :cpp:func:`esp_timer_delete`.
|
||||
@ -53,66 +58,50 @@ The timer can be started in one-shot mode or in periodic mode.
|
||||
|
||||
Note that the timer must not be running when :cpp:func:`esp_timer_start_once` or :cpp:func:`esp_timer_start_periodic` is called. To restart a running timer, call :cpp:func:`esp_timer_stop` first, then call one of the start functions.
|
||||
|
||||
Callback functions
|
||||
Callback Functions
|
||||
------------------
|
||||
|
||||
.. note:: Keep the callback functions as short as possible otherwise it will affect all timers.
|
||||
.. note:: Keep the callback functions as short as possible. Otherwise, it will affect all timers.
|
||||
|
||||
Timer callbacks which are processed by ``ESP_TIMER_ISR`` method should not call the context switch call - ``portYIELD_FROM_ISR()``, instead of this you should use the :cpp:func:`esp_timer_isr_dispatch_need_yield` function.
|
||||
The context switch will be done after all ISR dispatch timers have been processed, if required by the system.
|
||||
Timer callbacks that are processed by the ``ESP_TIMER_ISR`` method should not call the context switch call - ``portYIELD_FROM_ISR()``. Instead, use the :cpp:func:`esp_timer_isr_dispatch_need_yield` function. The context switch will be done after all ISR dispatch timers have been processed if required by the system.
|
||||
|
||||
.. only:: SOC_ETM_SUPPORTED and SOC_SYSTIMER_SUPPORT_ETM
|
||||
|
||||
ETM Event
|
||||
---------
|
||||
|
||||
The esp_timer is constructed based on a hardware timer called *systimer*, which is able to generate the alarm event and interact with the :doc:`ETM </api-reference/peripherals/etm>` module. You can call :cpp:func:`esp_timer_new_etm_alarm_event` to get the corresponding ETM event handle.
|
||||
The ``esp_timer`` is constructed based on a hardware timer called *systimer*, which is able to generate the alarm event and interact with the :doc:`ETM </api-reference/peripherals/etm>` module. You can call :cpp:func:`esp_timer_new_etm_alarm_event` to get the corresponding ETM event handle.
|
||||
|
||||
To know more about how to connect the event to an ETM channel, please refer to the :doc:`ETM </api-reference/peripherals/etm>` documentation.
|
||||
|
||||
esp_timer during light sleep
|
||||
``esp_timer`` During Light-sleep
|
||||
--------------------------------
|
||||
|
||||
During light sleep, the esp_timer counter stops and no callback functions are called.
|
||||
Instead, the time is counted by the RTC counter. Upon waking up, the system gets the difference
|
||||
between the counters and calls a function that advances the esp_timer counter.
|
||||
Since the counter has been advanced, the system starts calling callbacks that were not called during sleep.
|
||||
The number of callbacks depends on the duration of the sleep and the period of the timers. It can lead to overflow of some queues.
|
||||
This only applies to periodic timers, one-shot timers will be called once.
|
||||
During Light-sleep, the ``esp_timer`` counter stops and no callback functions are called. Instead, the time is counted by the RTC counter. Upon waking up, the system gets the difference between the counters and calls a function that advances the ``esp_timer`` counter. Since the counter has been advanced, the system starts calling callbacks that were not called during sleep. The number of callbacks depends on the duration of the sleep and the period of the timers. It can lead to the overflow of some queues. This only applies to periodic timers, since one-shot timers will be called once.
|
||||
|
||||
This behavior can be changed by calling :cpp:func:`esp_timer_stop` before sleeping.
|
||||
In some cases, this can be inconvenient, and instead of the stop function,
|
||||
you can use the `skip_unhandled_events` option during :cpp:func:`esp_timer_create`.
|
||||
When the `skip_unhandled_events` is true, if a periodic timer expires one or more times during light sleep
|
||||
then only one callback is called on wake.
|
||||
This behavior can be changed by calling :cpp:func:`esp_timer_stop` before sleeping. In some cases, this can be inconvenient, and instead of the stop function, you can use the ``skip_unhandled_events`` option during :cpp:func:`esp_timer_create`. When the ``skip_unhandled_events`` is true, if a periodic timer expires one or more times during Light-sleep, then only one callback is called on wake.
|
||||
|
||||
Using the `skip_unhandled_events` option with `automatic light sleep` (see :doc:`Power Management APIs <power_management>`) helps to reduce the power consumption of the system when it is in light sleep. The duration of light sleep is also determined by esp_timers. Timers with `skip_unhandled_events` option will not wake up the system.
|
||||
Using the ``skip_unhandled_events`` option with automatic Light-sleep (see :doc:`Power Management APIs <power_management>`) helps to reduce the power consumption of the system when it is in Light-sleep. The duration of Light-sleep is also in part determined by the next event occurs. Timers with ``skip_unhandled_events`` option will not wake up the system.
|
||||
|
||||
Handling callbacks
|
||||
Handling Callbacks
|
||||
------------------
|
||||
|
||||
esp_timer is designed to achieve a high-resolution low latency timer and the ability to handle delayed events.
|
||||
If the timer is late then the callback will be called as soon as possible, it will not be lost.
|
||||
In the worst case, when the timer has not been processed for more than one period (for periodic timers),
|
||||
the callbacks will be called one after the other without waiting for the set period.
|
||||
This can be bad for some applications, and the `skip_unhandled_events` option was introduced to eliminate this behavior.
|
||||
If `skip_unhandled_events` is set then a periodic timer that has expired multiple times without being able to call
|
||||
the callback will still result in only one callback event once processing is possible.
|
||||
``esp_timer`` is designed to achieve a high-resolution and low-latency timer with the ability to handle delayed events. If the timer is late, then the callback will be called as soon as possible, and it will not be lost. In the worst case, when the timer has not been processed for more than one period (for periodic timers), the callbacks will be called one after the other without waiting for the set period. This can be bad for some applications, and the ``skip_unhandled_events`` option is introduced to eliminate this behavior. If ``skip_unhandled_events`` is set, then a periodic timer that has expired multiple times without being able to call the callback will still result in only one callback event once processing is possible.
|
||||
|
||||
Obtaining Current Time
|
||||
----------------------
|
||||
|
||||
``esp_timer`` also provides a convenience function to obtain the time passed since start-up, with microsecond precision: :cpp:func:`esp_timer_get_time`. This function returns the number of microseconds since ``esp_timer`` was initialized, which usually happens shortly before ``app_main`` function is called.
|
||||
|
||||
Unlike `gettimeofday` function, values returned by :cpp:func:`esp_timer_get_time`:
|
||||
Unlike ``gettimeofday`` function, values returned by :cpp:func:`esp_timer_get_time`:
|
||||
|
||||
- Start from zero after the chip wakes up from deep sleep
|
||||
- Start from zero after the chip wakes up from Deep-sleep
|
||||
- Do not have timezone or DST adjustments applied
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
The following example illustrates usage of ``esp_timer`` APIs: :example:`system/esp_timer`.
|
||||
The following example illustrates the usage of ``esp_timer`` APIs: :example:`system/esp_timer`.
|
||||
|
||||
|
||||
API Reference
|
||||
|
||||
@ -3,12 +3,12 @@ System Time
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{IDF_TARGET_RTC_CLK_FRE:default="Not updated", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz"}
|
||||
{IDF_TARGET_RTC_CLK_FRE:default="Not updated", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz", esp32h2="150 kHz"}
|
||||
{IDF_TARGET_INT_OSC_FRE:default="Not updated", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz", esp32c6="20 MHz"}
|
||||
{IDF_TARGET_INT_OSC_FRE_DIVIDED:default="Not updated", esp32="~33 kHz", esp32s2="~33 kHz", esp32s3="~68 kHz", esp32c3="~68 kHz", esp32c2="~68 kHz"}
|
||||
{IDF_TARGET_EXT_CRYSTAL_PIN:default="Not updated", esp32="32K_XP and 32K_XN", esp32s2="XTAL_32K_P and XTAL_32K_N", esp32s3="XTAL_32K_P and XTAL_32K_N", esp32c3="XTAL_32K_P and XTAL_32K_N", esp32c6="XTAL_32K_P and XTAL_32K_N"}
|
||||
{IDF_TARGET_EXT_CRYSTAL_PIN:default="Not updated", esp32="32K_XP and 32K_XN", esp32s2="XTAL_32K_P and XTAL_32K_N", esp32s3="XTAL_32K_P and XTAL_32K_N", esp32c3="XTAL_32K_P and XTAL_32K_N", esp32c6="XTAL_32K_P and XTAL_32K_N", esp32h2="XTAL_32K_P and XTAL_32K_N"}
|
||||
{IDF_TARGET_EXT_OSC_PIN:default="Not updated", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P"}
|
||||
{IDF_TARGET_HARDWARE_DESIGN_URL:default="Not updated",esp32="`ESP32 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf#page=11>`_", esp32s2="`ESP32-S2 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_en.pdf#page=10>`_", esp32s3="`ESP32-S3 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_en.pdf#page=11>`_", esp32c3="`ESP32-C3 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_en.pdf#page=9>`_"}
|
||||
{IDF_TARGET_HARDWARE_DESIGN_URL:default="Not updated",esp32="`ESP32 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf#page=11>`_", esp32s2="`ESP32-S2 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_en.pdf#page=10>`_", esp32s3="`ESP32-S3 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_en.pdf#page=11>`_", esp32c3="`ESP32-C3 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_en.pdf#page=9>`_", esp32c6="`ESP32-C6 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-c6_hardware_design_guidelines_en.pdf#page=12>`_", esp32c2="`ESP8684 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp8684_hardware_design_guidelines_en.pdf#page=10>`_", esp32h2="`ESP32-H2 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-h2_hardware_design_guidelines_en.pdf#page=11>`_"}
|
||||
|
||||
|
||||
Overview
|
||||
@ -45,18 +45,13 @@ The RTC timer has the following clock sources:
|
||||
|
||||
- ``External 32 kHz oscillator at {IDF_TARGET_EXT_OSC_PIN} pin``: Allows using 32 kHz clock generated by an external circuit. The external clock signal must be connected to the {IDF_TARGET_EXT_OSC_PIN} pin. The amplitude should be less than 1.2 V for sine wave signal and less than 1 V for square wave signal. Common mode voltage should be in the range of 0.1 < Vcm < 0.5xVamp, where Vamp stands for signal amplitude. In this case, the {IDF_TARGET_EXT_OSC_PIN} pin cannot be used as a GPIO pin.
|
||||
|
||||
:not esp32c6: - ``Internal {IDF_TARGET_INT_OSC_FRE} oscillator, divided by 256 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``: Provides better frequency stability than the ``Internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator`` at the expense of a higher (by 5 μA) Deep-sleep current consumption. It also does not require external components.
|
||||
:not esp32c6 and not esp32h2: - ``Internal {IDF_TARGET_INT_OSC_FRE} oscillator, divided by 256 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``: Provides better frequency stability than the ``Internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator`` at the expense of a higher (by 5 μA) Deep-sleep current consumption. It also does not require external components.
|
||||
|
||||
:esp32c6: - ``Internal 32 kHz RC oscillator``
|
||||
:esp32c6 or esp32h2: - ``Internal 32 kHz RC oscillator``
|
||||
|
||||
The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_RTC_CLK_SRC` in project configuration.
|
||||
|
||||
.. Need to add esp32c2 and esp32c6 hardware design guideline link after it is publsihed.
|
||||
|
||||
.. only:: not esp32c2 and not esp32c6
|
||||
|
||||
More details about the wiring requirements for the external crystal or external oscillator, please refer to {IDF_TARGET_HARDWARE_DESIGN_URL}.
|
||||
|
||||
More details about the wiring requirements for the external crystal or external oscillator, please refer to {IDF_TARGET_HARDWARE_DESIGN_URL}.
|
||||
|
||||
Get Current Time
|
||||
----------------
|
||||
|
||||
@ -141,8 +141,8 @@ Sometimes the USB-to-UART bridge is external. This is often used in small develo
|
||||
|
||||
For the {IDF_TARGET_NAME}, the USB peripheral is available, allowing you to flash the binaries without the need for an external USB-to-UART bridge.
|
||||
|
||||
{IDF_TARGET_USB_PIN_DM:default="Not Updated!", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19", esp32c6="GPIO12"}
|
||||
{IDF_TARGET_USB_PIN_DP:default="Not Updated!", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20", esp32c6="GPIO13"}
|
||||
{IDF_TARGET_USB_PIN_DM:default="Not Updated!", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19", esp32c6="GPIO12", esp32h2="GPIO26"}
|
||||
{IDF_TARGET_USB_PIN_DP:default="Not Updated!", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20", esp32c6="GPIO13", esp32h2="GPIO27"}
|
||||
|
||||
The USB on the {IDF_TARGET_NAME} uses the **{IDF_TARGET_USB_PIN_DP}** for **D+** and **{IDF_TARGET_USB_PIN_DM}** for **D-**.
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ Flashing Troubleshooting
|
||||
Failed to Connect
|
||||
-----------------
|
||||
|
||||
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9", esp32c6="GPIO9"}
|
||||
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9", esp32c6="GPIO9", esp32h2="GPIO9"}
|
||||
|
||||
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is to manually reset as described below. If it does not help, you can find more details about possible issues in the `esptool troubleshooting <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ page.
|
||||
|
||||
|
||||
@ -68,6 +68,14 @@ Introduction
|
||||
* Multiple peripherals
|
||||
* Built-in security hardware
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
* Bluetooth Low Energy
|
||||
* 802.15.4 Thread/Zigbee
|
||||
* High performance 32-bit RISC-V single-core processor
|
||||
* Multiple peripherals
|
||||
* Built-in security hardware
|
||||
|
||||
Powered by 40 nm technology, {IDF_TARGET_NAME} provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
|
||||
|
||||
Espressif provides basic hardware and software resources to help application developers realize their ideas using the {IDF_TARGET_NAME} series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{IDF_TARGET_FEATURES:default="[NEEDS TO BE UPDATED]", esp32="WiFi/BT/BLE, silicon revision 1, 2 MB external flash", esp32s2="WiFi, silicon revision 0, 2 MB external flash", esp32s3="This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c2="WiFi/BLE, silicon revision 0, 2 MB embedded flash", esp32c3="WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c6="WiFi/BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.0, 2 MB external flash"}
|
||||
{IDF_TARGET_FEATURES:default="[NEEDS TO BE UPDATED]", esp32="WiFi/BT/BLE, silicon revision 1, 2 MB external flash", esp32s2="WiFi, silicon revision 0, 2 MB external flash", esp32s3="This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c2="WiFi/BLE, silicon revision 0, 2 MB embedded flash", esp32c3="WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c6="WiFi/BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.0, 2 MB external flash", esp32h2="BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.1, 2 MB external flash"}
|
||||
|
||||
{IDF_TARGET_HEAP_SIZE:default="[NEEDS TO BE UPDATED]", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c2="203888", esp32c3="337332", esp32c6="337332"}
|
||||
{IDF_TARGET_HEAP_SIZE:default="[NEEDS TO BE UPDATED]", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c2="203888", esp32c3="337332", esp32c6="473816", esp32h2="268256"}
|
||||
|
||||
Build the Project
|
||||
=================
|
||||
@ -318,6 +318,48 @@ When flashing, you will see the output log similar to the following:
|
||||
Leaving...
|
||||
Hard resetting via RTS pin...
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
...
|
||||
esptool esp32h2 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 48m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
|
||||
esptool.py v4.6
|
||||
Serial port /dev/ttyUSB0
|
||||
Connecting....
|
||||
Chip is ESP32-H2 (revision v0.1)
|
||||
Features: BLE
|
||||
Crystal is 32MHz
|
||||
MAC: 60:55:f9:f7:3e:93:ff:fe
|
||||
Uploading stub...
|
||||
Running stub...
|
||||
Stub running...
|
||||
Changing baud rate to 460800
|
||||
Changed.
|
||||
Configuring flash size...
|
||||
Flash will be erased from 0x00000000 to 0x00005fff...
|
||||
Flash will be erased from 0x00010000 to 0x00034fff...
|
||||
Flash will be erased from 0x00008000 to 0x00008fff...
|
||||
Compressed 20880 bytes to 12788...
|
||||
Writing at 0x00000000... (100 %)
|
||||
Wrote 20880 bytes (12788 compressed) at 0x00000000 in 0.6 seconds (effective 297.5 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 149424 bytes to 79574...
|
||||
Writing at 0x00010000... (20 %)
|
||||
Writing at 0x00019959... (40 %)
|
||||
Writing at 0x00020bb5... (60 %)
|
||||
Writing at 0x00026d8f... (80 %)
|
||||
Writing at 0x0002e60a... (100 %)
|
||||
Wrote 149424 bytes (79574 compressed) at 0x00010000 in 2.1 seconds (effective 571.7 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 3072 bytes to 103...
|
||||
Writing at 0x00008000... (100 %)
|
||||
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 539.7 kbit/s)...
|
||||
Hash of data verified.
|
||||
|
||||
Leaving...
|
||||
Hard resetting via RTS pin...
|
||||
|
||||
If there are no issues by the end of the flash process, the board will reboot and start up the “hello_world” application.
|
||||
|
||||
|
||||
@ -6,22 +6,26 @@ Hardware Reference
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
:not esp32h2: Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>
|
||||
Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>
|
||||
:esp32: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>
|
||||
:esp32s2: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf>
|
||||
:esp32s3: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf>
|
||||
:esp32c2: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp8684_datasheet_en.pdf>
|
||||
:esp32c3: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf>
|
||||
:esp32c6: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32-c6_datasheet_en.pdf>
|
||||
:esp32h2: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32-h2_datasheet_en.pdf>
|
||||
:esp32: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>
|
||||
:esp32s2: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_en.pdf>
|
||||
:esp32s3: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_en.pdf>
|
||||
:esp32c2: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp8684_hardware_design_guidelines_en.pdf>
|
||||
:esp32c3: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_en.pdf>
|
||||
:esp32c6: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32-c6_hardware_design_guidelines_en.pdf>
|
||||
:esp32h2: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32-h2_hardware_design_guidelines_en.pdf>
|
||||
:esp32: Silicon Errata (PDF) <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
|
||||
:esp32s2: Silicon Errata (PDF) <https://www.espressif.com/sites/default/files/documentation/esp32-s2_errata_en.pdf>
|
||||
:esp32s3: Silicon Errata (PDF) <https://www.espressif.com/sites/default/files/documentation/esp32-s3_errata_en.pdf>
|
||||
:esp32c3: Silicon Errata (PDF) <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_en.pdf>
|
||||
:esp32c2: Silicon Errata (PDF) <https://www.espressif.com/sites/default/files/documentation/esp8684_errata_en.pdf>
|
||||
Chip Variants <https://espressif.com/en/products/socs?id={IDF_TARGET_NAME}>
|
||||
Modules <https://espressif.com/en/products/modules?id={IDF_TARGET_NAME}>
|
||||
Development Boards <https://www.espressif.com/en/products/devkits?id={IDF_TARGET_NAME}>
|
||||
|
||||
@ -35,6 +35,12 @@
|
||||
|
||||
{IDF_TARGET_NAME} 是一款支持 2.4 GHz Wi-Fi, 802.15.4 Thread/Zigbee 和低功耗蓝牙的芯片，搭载 RISC-V RV32IMAC 32 位单核处理器。
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
本指南为 {IDF_TARGET_NAME} 官方应用开发框架 `ESP-IDF <https://github.com/espressif/esp-idf>`_ 的配套文档。
|
||||
|
||||
{IDF_TARGET_NAME} 是一款支持 802.15.4 Thread/Zigbee 和低功耗蓝牙的芯片，搭载 RISC-V RV32IMAC 32 位单核处理器。
|
||||
|
||||
.. figure:: ../_static/about-doc.png
|
||||
:align: center
|
||||
:alt: 乐鑫物联网综合开发框架
|
||||
|
||||
@ -1 +1,112 @@
|
||||
.. include:: ../../../en/api-reference/system/esp_timer.rst
|
||||
高分辨率定时器（ESP 定时器）
|
||||
=================================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
{IDF_TARGET_HR_TIMER:default = "SYSTIMER", esp32 = "LAC 定时器"}
|
||||
|
||||
{IDF_TARGET_HR_TIMER_Resolution:default = "Not updated", esp32 = "64", esp32s2 = "64", esp32c3 = "52", esp32s3 = "52", esp32c2 = "52", esp32c6 = "52", esp32h2 = "52"}
|
||||
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
尽管 FreeRTOS 提供软件定时器，但 FreeRTOS 软件定时器存在一定局限性：
|
||||
|
||||
- 最大分辨率等于 RTOS 滴答周期
|
||||
- 定时器回调函数从低优先级的定时器服务（即守护进程）任务中分发。该任务可能会被其他任务抢占，导致精度和准确性下降。
|
||||
|
||||
硬件定时器虽不受上述限制，但使用不便。例如，应用组件可能需要在特定的未来时间触发计时器事件，但硬件定时器通常只有一个“compare（比较）”值用于中断生成。为提升使用的便利性，应在硬件定时器的基础上构建某种机制来管理待处理事件列表，确保在相应的硬件中断发生时调度回调。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
配置 :ref:`CONFIG_ESP_TIMER_INTERRUPT_LEVEL` 选项，设置硬件定时器中断的优先级（可设置为 1、2 或 3 级），提高定时器中断的优先级可以减少由中断延迟引起的定时器处理延迟。
|
||||
|
||||
|
||||
``esp_timer`` API 集支持单次定时器和周期定时器、微秒级的时间分辨率、以及 {IDF_TARGET_HR_TIMER_Resolution} 位范围。
|
||||
|
||||
``esp_timer`` 内部使用 {IDF_TARGET_HR_TIMER_Resolution} 位硬件定时器，具体硬件实现取决于芯片型号，如 {IDF_TARGET_NAME} 使用的是 {IDF_TARGET_HR_TIMER}。
|
||||
|
||||
定时器回调可通过以下两种方式调度：
|
||||
|
||||
- ``ESP_TIMER_TASK``。
|
||||
- ``ESP_TIMER_ISR``。仅当 :ref:`CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD` 被启用时可用（默认为禁用）。
|
||||
|
||||
使用 ``ESP_TIMER_TASK`` 这一途径时，定时器回调函数是从高优先级的 ``esp_timer`` 任务中调度的。由于所有回调函数都是从同一个任务中调度，因此建议在回调函数本身中仅执行最小化的工作，如使用队列向低优先级任务发布事件。
|
||||
|
||||
如果有优先级高于 ``esp_timer`` 的其他任务正在运行，则回调调度将延迟，直至 ``esp_timer`` 能够运行。例如，执行 SPI flash 操作时便会发生此类情况。
|
||||
|
||||
使用 ``ESP_TIMER_ISR`` 这一途径时，定时器回调由定时器中断处理程序直接调度。对旨在降低延迟的简单回调，建议使用此途径。
|
||||
|
||||
创建、启动定时器并调度回调需要一些时间。因此，单次 ``esp_timer`` 的超时值存在最小限制。若调用 :cpp:func:`esp_timer_start_once` 时设置的超时值小于 20 us，回调函数仍会在大约 20 微秒后被调度。
|
||||
|
||||
周期 ``esp_timer`` 将最小周期限制为 50 us。周期小于 50 us 的软件定时器会占用大部分 CPU 时间，因此它们并不实用。如需使用小周期定时器，请考虑使用专用硬件外设或 DMA 功能。
|
||||
|
||||
使用 ``esp_timer`` API
|
||||
------------------------
|
||||
|
||||
单个定时器由 :cpp:type:`esp_timer_handle_t` 类型表示。每个定时器都有与之关联的回调函数，定时器超时时便会从 ``esp_timer`` 任务中调用此函数。
|
||||
|
||||
- 要创建定时器，请调用函数 :cpp:func:`esp_timer_create`。
|
||||
- 要删除定时器，请调用函数 :cpp:func:`esp_timer_delete`。
|
||||
|
||||
定时器可以以单次模式和周期模式启动。
|
||||
|
||||
- 要以单次模式启动定时器，请调用函数 :cpp:func:`esp_timer_start_once`，传递应在多久后调用回调的时间间隔。调用回调时，定时器被视为停止工作。
|
||||
|
||||
- 要以周期模式启动定时器，请调用函数 :cpp:func:`esp_timer_start_periodic`，传递应调用回调的周期。计时器持续运行，直到调用函数 :cpp:func:`esp_timer_stop`。
|
||||
|
||||
注意，当调用函数 :cpp:func:`esp_timer_start_once` 或 :cpp:func:`esp_timer_start_periodic` 时，应确保定时器处于非运行状态。因此，要重启运行中的定时器，需首先调用函数 :cpp:func:`esp_timer_stop` 停止定时器，然后调用 :cpp:func:`esp_timer_start_once` 或 :cpp:func:`esp_timer_start_periodic` 来启动定时器。
|
||||
|
||||
回调函数
|
||||
------------------
|
||||
|
||||
.. note:: 回调函数应尽可能简略，避免影响所有定时器。
|
||||
|
||||
若定时器回调由 ``ESP_TIMER_ISR`` 方式处理，则该回调不应调用切换上下文的 ``portYIELD_FROM_ISR()``，而应调用函数 :cpp:func:`esp_timer_isr_dispatch_need_yield`。如果系统有此需求，上下文切换将在所有 ISR 调度定时器处理完毕后进行。
|
||||
|
||||
.. only:: SOC_ETM_SUPPORTED and SOC_SYSTIMER_SUPPORT_ETM
|
||||
|
||||
ETM 事件
|
||||
---------
|
||||
|
||||
``esp_timer`` 的构建基于 *systimer* 硬件定时器，能够产生报警事件并与 :doc:`ETM </api-reference/peripherals/etm>` 模块交互。调用函数 :cpp:func:`esp_timer_new_etm_alarm_event` 以获取相应的 ETM 事件句柄。
|
||||
|
||||
如需了解如何将 ETM 事件连接到相应 ETM 通道，请参阅 :doc:`ETM </api-reference/peripherals/etm>`。
|
||||
|
||||
Light-sleep 模式下的 ``esp_timer``
|
||||
-----------------------------------
|
||||
|
||||
在 Light-sleep 期间， ``esp_timer`` 计数器停止工作，并且不调用回调函数，而是由 RTC 计数器负责计算时间。唤醒后，系统得到两个计数器间的差值，并调用函数推进 ``esp_timer`` 计数器计数。计数器计数被推进后，系统开始调用 Light-sleep 期间未被调用的回调。回调数量取决于 Light-sleep 模式持续时长和定时器周期，这可能会导致某些队列溢出。以上情况仅适用于周期性定时器，单次定时器只会被调用一次。
|
||||
|
||||
通过在 Light-sleep 模式前调用函数 :cpp:func:`esp_timer_stop` 可以改变上述行为。但在某些情况下这可能并不方便。比起使用停止函数，在 :cpp:func:`esp_timer_create` 中使用 ``skip_unhandled_events`` 选项将更加便利。 当 ``skip_unhandled_events`` 为真时，如果一个周期性定时器在 Light-sleep 期间超时一次或多次，那么在唤醒时只有一个回调会被调用。
|
||||
|
||||
使用带有自动 Light-sleep 的 ``skip_unhandled_events`` 选项（请参阅 :doc:`电源管理 <power_management>`），有助于在系统处于 Light-sleep 状态时降低功耗。 Light-sleep 的持续时间也在一定程度上由下一个事件发生的时间确定。具有 ``skip_unhandled_events``` 选项的定时器不会唤醒系统。
|
||||
|
||||
处理回调
|
||||
------------------
|
||||
|
||||
设计 ``esp_timer`` 是为了使定时器实现高分辨率和低延迟，并具备处理延迟事件的能力。如果定时器延迟，回调将被尽快调用，不会丢失。在最糟的情况下，周期性定时器可能超过一个周期还没有被处理，此时回调将被陆续调用，而不会等待设定的周期。这会给某些应用带来负面影响，为避免此类情况发生，特引入 ``skip_unhandled_events`` 选项。设置该选项后，即使一个周期性定时器多次超时且无法调用回调，该定时器在恢复处理能力后，仍将只产生一个回调事件。
|
||||
|
||||
获取当前时间
|
||||
----------------------
|
||||
|
||||
``esp_timer`` 还提供了一个便捷函数 :cpp:func:`esp_timer_get_time` 以获取自启动以来经过的时间，可精确到微秒。这个函数通常会在 ``app_main`` 函数即将被调用前，返回自 ``esp_timer`` 启动以来的微秒数。
|
||||
|
||||
不同于 ``gettimeofday`` 函数，:cpp:func:`esp_timer_get_time` 返回的值：
|
||||
|
||||
- 芯片从 Deep-sleep 中唤醒后，从零开始
|
||||
- 没有应用时区或 DST 调整
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
``esp_timer`` API 的详细用法可参阅 :example:`system/esp_timer`。
|
||||
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_timer.inc
|
||||
|
||||
|
||||
|
||||
@ -3,12 +3,12 @@
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
{IDF_TARGET_RTC_CLK_FRE:default="未更新", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz"}
|
||||
{IDF_TARGET_RTC_CLK_FRE:default="未更新", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz", esp32h2="150 kHz"}
|
||||
{IDF_TARGET_INT_OSC_FRE:default="未更新", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz", esp32c6="20 MHz"}
|
||||
{IDF_TARGET_INT_OSC_FRE_DIVIDED:default="未更新", esp32="~33 kHz", esp32s2="~33 kHz", esp32s3="~68 kHz", esp32c3="~68 kHz", esp32c2="~68 kHz"}
|
||||
{IDF_TARGET_EXT_CRYSTAL_PIN:default="未更新", esp32="32K_XP 和 32K_XN", esp32s2="XTAL_32K_P 和 XTAL_32K_N", esp32s3="XTAL_32K_P 和 XTAL_32K_N", esp32c3="XTAL_32K_P 和 XTAL_32K_N", esp32c6="XTAL_32K_P 和 XTAL_32K_N"}
|
||||
{IDF_TARGET_EXT_CRYSTAL_PIN:default="未更新", esp32="32K_XP 和 32K_XN", esp32s2="XTAL_32K_P 和 XTAL_32K_N", esp32s3="XTAL_32K_P 和 XTAL_32K_N", esp32c3="XTAL_32K_P 和 XTAL_32K_N", esp32c6="XTAL_32K_P 和 XTAL_32K_N", esp32h2="XTAL_32K_P 和 XTAL_32K_N"}
|
||||
{IDF_TARGET_EXT_OSC_PIN:default="未更新", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P"}
|
||||
{IDF_TARGET_HARDWARE_DESIGN_URL:default="未更新", esp32="`ESP32 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_cn.pdf#page=10>`_", esp32s2="`ESP32-S2 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_cn.pdf#page=10>`_", esp32s3="`ESP32-S3 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_cn.pdf#page=12>`_", esp32c3="`ESP32-C3 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_cn.pdf#page=9>`_"}
|
||||
{IDF_TARGET_HARDWARE_DESIGN_URL:default="未更新", esp32="`ESP32 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_cn.pdf#page=10>`_", esp32s2="`ESP32-S2 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_cn.pdf#page=10>`_", esp32s3="`ESP32-S3 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_cn.pdf#page=12>`_", esp32c3="`ESP32-C3 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_cn.pdf#page=9>`_", esp32c2="`ESP8684 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp8684_hardware_design_guidelines_cn.pdf#page=10>`_", esp32c6="`ESP32-C6 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-c6_hardware_design_guidelines_cn.pdf#page=12>`_", esp32h2="`ESP32-H2 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-h2_hardware_design_guidelines_cn.pdf#page=11>`_"}
|
||||
|
||||
|
||||
概述
|
||||
@ -45,18 +45,13 @@ RTC 定时器有以下时钟源：
|
||||
|
||||
- ``管脚 {IDF_TARGET_EXT_OSC_PIN} 外置 32 kHz 振荡器``：允许使用由外部电路产生的 32 kHz 时钟。外部时钟信号必须连接到管脚 {IDF_TARGET_EXT_OSC_PIN}。正弦波信号的振幅应小于 1.2 V，方波信号的振幅应小于 1 V。正常模式下，电压范围应为 0.1 < Vcm < 0.5 xVamp，其中 Vamp 代表信号振幅。使用此时钟源时，管脚 {IDF_TARGET_EXT_OSC_PIN} 无法用作 GPIO 管脚。
|
||||
|
||||
:not esp32c6: - ``内置 {IDF_TARGET_INT_OSC_FRE} 振荡器的 256 分频时钟 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``：频率稳定性优于 ``内置 {IDF_TARGET_RTC_CLK_FRE} RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。
|
||||
:not esp32c6 and not esp32h2: - ``内置 {IDF_TARGET_INT_OSC_FRE} 振荡器的 256 分频时钟 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``：频率稳定性优于 ``内置 {IDF_TARGET_RTC_CLK_FRE} RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。
|
||||
|
||||
:esp32c6: - ``内置 32 kHz RC 振荡器``
|
||||
:esp32c6 or esp32h2: - ``内置 32 kHz RC 振荡器``
|
||||
|
||||
时钟源的选择取决于系统时间精度要求和睡眠模式下的功耗要求。要修改 RTC 时钟源，请在项目配置中设置 :ref:`CONFIG_RTC_CLK_SRC`。
|
||||
|
||||
.. Need to add esp32c2 and esp32c6 hardware design guideline link after it is publsihed.
|
||||
|
||||
.. only:: not esp32c2 and not esp32c6
|
||||
|
||||
想要了解外置晶振或外置振荡器的更多布线要求，请参考 {IDF_TARGET_HARDWARE_DESIGN_URL}。
|
||||
|
||||
想要了解外置晶振或外置振荡器的更多布线要求，请参考 {IDF_TARGET_HARDWARE_DESIGN_URL}。
|
||||
|
||||
获取当前时间
|
||||
--------------
|
||||
|
||||
@ -141,8 +141,8 @@
|
||||
|
||||
{IDF_TARGET_NAME} 支持 USB 外设，无需外部 USB 至 UART 桥，即可烧录二进制文件。
|
||||
|
||||
{IDF_TARGET_USB_PIN_DM:default="尚未更新！", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19", esp32c6="GPIO12"}
|
||||
{IDF_TARGET_USB_PIN_DP:default="尚未更新！", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20", esp32c6="GPIO13"}
|
||||
{IDF_TARGET_USB_PIN_DM:default="尚未更新！", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19", esp32c6="GPIO12", esp32h2="GPIO26"}
|
||||
{IDF_TARGET_USB_PIN_DP:default="尚未更新！", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20", esp32c6="GPIO13", esp32h2="GPIO27"}
|
||||
|
||||
{IDF_TARGET_NAME} 上的 USB 使用 **{IDF_TARGET_USB_PIN_DP}** 作为 **D+**， **{IDF_TARGET_USB_PIN_DM}** 作为 **D-**。
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
连接失败
|
||||
-----------------
|
||||
|
||||
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9", esp32c6="GPIO9"}
|
||||
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9", esp32c6="GPIO9", esp32h2="GPIO9"}
|
||||
|
||||
如果在运行给定命令时出现如“连接失败”这样的错误，造成该错误的原因之一可能是运行 ``esptool.py`` 时出现错误。 ``esptool.py`` 是构建系统调用的程序，用于重置芯片、与 ROM 引导加载器交互以及烧录固件的工具。可以按照以下步骤进行手动复位，轻松解决该问题。如果问题仍未解决，请参考 `esptool 故障排除 <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ 获取更多信息。
|
||||
|
||||
|
||||
@ -68,6 +68,14 @@
|
||||
* 多种外设
|
||||
* 内置安全硬件
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
* 低功耗蓝牙
|
||||
* 802.15.4，支持 Thread 和 Zigbee 协议
|
||||
* 高性能 32 位 RISC-V 单核处理器
|
||||
* 多种外设
|
||||
* 内置安全硬件
|
||||
|
||||
{IDF_TARGET_NAME} 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用场景和不同功耗需求。
|
||||
|
||||
乐鑫为用户提供完整的软、硬件资源，进行 {IDF_TARGET_NAME} 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{IDF_TARGET_FEATURES:default="[NEEDS TO BE UPDATED]", esp32="WiFi/BT/BLE, silicon revision 1, 2 MB external flash", esp32s2="WiFi, silicon revision 0, 2 MB external flash", esp32s3="This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c2="WiFi/BLE, silicon revision 0, 2 MB embedded flash", esp32c3="WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c6="WiFi/BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.0, 2 MB external flash"}
|
||||
{IDF_TARGET_FEATURES:default="[NEEDS TO BE UPDATED]", esp32="WiFi/BT/BLE, silicon revision 1, 2 MB external flash", esp32s2="WiFi, silicon revision 0, 2 MB external flash", esp32s3="This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c2="WiFi/BLE, silicon revision 0, 2 MB embedded flash", esp32c3="WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c6="WiFi/BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.0, 2 MB external flash", esp32h2="BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.1, 2 MB external flash"}
|
||||
|
||||
{IDF_TARGET_HEAP_SIZE:default="[NEEDS TO BE UPDATED]", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c2="203888", esp32c3="337332", esp32c6="337332"}
|
||||
{IDF_TARGET_HEAP_SIZE:default="[NEEDS TO BE UPDATED]", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c2="203888", esp32c3="337332", esp32c6="473816", esp32h2="268256"}
|
||||
|
||||
编译工程
|
||||
=========================
|
||||
@ -318,6 +318,47 @@
|
||||
Leaving...
|
||||
Hard resetting via RTS pin...
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
...
|
||||
esptool esp32h2 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 48m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
|
||||
esptool.py v4.6
|
||||
Serial port /dev/ttyUSB0
|
||||
Connecting....
|
||||
Chip is ESP32-H2 (revision v0.1)
|
||||
Features: BLE
|
||||
Crystal is 32MHz
|
||||
MAC: 60:55:f9:f7:3e:93:ff:fe
|
||||
Uploading stub...
|
||||
Running stub...
|
||||
Stub running...
|
||||
Changing baud rate to 460800
|
||||
Changed.
|
||||
Configuring flash size...
|
||||
Flash will be erased from 0x00000000 to 0x00005fff...
|
||||
Flash will be erased from 0x00010000 to 0x00034fff...
|
||||
Flash will be erased from 0x00008000 to 0x00008fff...
|
||||
Compressed 20880 bytes to 12788...
|
||||
Writing at 0x00000000... (100 %)
|
||||
Wrote 20880 bytes (12788 compressed) at 0x00000000 in 0.6 seconds (effective 297.5 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 149424 bytes to 79574...
|
||||
Writing at 0x00010000... (20 %)
|
||||
Writing at 0x00019959... (40 %)
|
||||
Writing at 0x00020bb5... (60 %)
|
||||
Writing at 0x00026d8f... (80 %)
|
||||
Writing at 0x0002e60a... (100 %)
|
||||
Wrote 149424 bytes (79574 compressed) at 0x00010000 in 2.1 seconds (effective 571.7 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 3072 bytes to 103...
|
||||
Writing at 0x00008000... (100 %)
|
||||
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 539.7 kbit/s)...
|
||||
Hash of data verified.
|
||||
|
||||
Leaving...
|
||||
Hard resetting via RTS pin...
|
||||
|
||||
如果一切顺利，烧录完成后，开发板将会复位，应用程序 "hello_world" 开始运行。
|
||||
|
||||
|
||||
@ -6,22 +6,26 @@ H/W 硬件参考
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
:not esp32h2: 技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}>
|
||||
技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}>
|
||||
:esp32: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>
|
||||
:esp32s2: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s2_datasheet_cn.pdf>
|
||||
:esp32s3: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s3_datasheet_cn.pdf>
|
||||
:esp32c2: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp8684_datasheet_cn.pdf>
|
||||
:esp32c3: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-c3_datasheet_cn.pdf>
|
||||
:esp32c6: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-c6_datasheet_cn.pdf>
|
||||
:esp32h2: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-h2_datasheet_cn.pdf>
|
||||
:esp32: 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_cn.pdf>
|
||||
:esp32s2: 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_cn.pdf>
|
||||
:esp32s3: 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_cn.pdf>
|
||||
:esp32c2: 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp8684_hardware_design_guidelines_cn.pdf>
|
||||
:esp32c3: 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_cn.pdf>
|
||||
:esp32c6: 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-c6_hardware_design_guidelines_cn.pdf>
|
||||
:esp32h2: 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-h2_hardware_design_guidelines_cn.pdf>
|
||||
:esp32: 勘误表及解决方法 (PDF) <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_cn.pdf>
|
||||
:esp32s2: 勘误表及解决方法 (PDF) <https://www.espressif.com/sites/default/files/documentation/esp32-s2_errata_cn.pdf>
|
||||
:esp32s3: 勘误表及解决方法 (PDF) <https://www.espressif.com/sites/default/files/documentation/esp32-s3_errata_cn.pdf>
|
||||
:esp32c3: 勘误表及解决方法 (PDF) <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_cn.pdf>
|
||||
:esp32c2: 勘误表及解决方法 (PDF) <https://www.espressif.com/sites/default/files/documentation/esp8684_errata_cn.pdf>
|
||||
芯片变型 <https://espressif.com/zh-hans/products/socs?id={IDF_TARGET_NAME}>
|
||||
模组 <https://www.espressif.com/zh-hans/products/modules?id={IDF_TARGET_NAME}>
|
||||
开发板 <https://www.espressif.com/zh-hans/products/devkits?id={IDF_TARGET_NAME}>
|
||||
|
||||
@ -20,11 +20,12 @@ void app_main(void)
|
||||
esp_chip_info_t chip_info;
|
||||
uint32_t flash_size;
|
||||
esp_chip_info(&chip_info);
|
||||
printf("This is %s chip with %d CPU core(s), WiFi%s%s%s, ",
|
||||
printf("This is %s chip with %d CPU core(s), %s%s%s%s, ",
|
||||
CONFIG_IDF_TARGET,
|
||||
chip_info.cores,
|
||||
(chip_info.features & CHIP_FEATURE_BT) ? "/BT" : "",
|
||||
(chip_info.features & CHIP_FEATURE_BLE) ? "/BLE" : "",
|
||||
(chip_info.features & CHIP_FEATURE_WIFI_BGN) ? "WiFi/" : "",
|
||||
(chip_info.features & CHIP_FEATURE_BT) ? "BT" : "",
|
||||
(chip_info.features & CHIP_FEATURE_BLE) ? "BLE" : "",
|
||||
(chip_info.features & CHIP_FEATURE_IEEE802154) ? ", 802.15.4 (Zigbee/Thread)" : "");
|
||||
|
||||
unsigned major_rev = chip_info.revision / 100;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user