# ESP 定时器

[English]

## API 参考

### Header File

- components/esp_timer/include/esp_timer.h

- This header file can be included with:

  >     #include "esp_timer.h"

- This header file is a part of the API provided by the `esp_timer` component. To declare that your component depends on `esp_timer`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_timer

  > or

  >     PRIV_REQUIRES esp_timer

### Functions

esp_err_t esp_timer_early_init(void)

  Minimal initialization of esp_timer.

  This function can be called very early in startup process, after this call only esp_timer_get_time() function can be used.

  备注

  This function is called from startup code. Applications do not need to call this function before using other esp_timer APIs.

  返回:

    - ESP_OK on success

esp_err_t esp_timer_init(void)

  Initialize esp_timer library.

  This function will be called from startup code on every core. If Kconfig option `CONFIG_ESP_TIMER_ISR_AFFINITY` is set to `NO_AFFINITY`, it allocates the timer ISR on MULTIPLE cores and creates the timer task which can be run on any core.

  备注

  This function is called from startup code. Applications do not need to call this function before using other esp_timer APIs. Before calling this function, esp_timer_early_init() must be called by the startup code.

  返回:

    - ESP_OK on success

    - ESP_ERR_NO_MEM if allocation has failed

    - ESP_ERR_INVALID_STATE if already initialized

    - other errors from interrupt allocator

esp_err_t esp_timer_deinit(void)

  De-initialize esp_timer library.

  备注

  Normally this function should not be called from applications

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_STATE if not yet initialized

esp_err_t esp_timer_create(const esp_timer_create_args_t *create_args, esp_timer_handle_t *out_handle)

  Create an esp_timer instance.

  备注

  When timer no longer needed, delete it using esp_timer_delete().

  参数:

    - create_args -- Pointer to a structure with timer creation arguments. Not saved by the library, can be allocated on the stack.

    - out_handle -- [out] Output, pointer to esp_timer_handle_t variable that holds the created timer handle.

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if some of the create_args are not valid

    - ESP_ERR_INVALID_STATE if esp_timer library is not initialized yet

    - ESP_ERR_NO_MEM if memory allocation fails

esp_err_t esp_timer_start_once(esp_timer_handle_t timer, uint64_t timeout_us)

  Start a one-shot timer.

  Timer represented by `timer` should not be running when this function is called.

  参数:

    - timer -- timer handle created using esp_timer_create()

    - timeout_us -- timer timeout, in microseconds relative to the current moment

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if the handle is invalid

    - ESP_ERR_INVALID_STATE if the timer is already running

esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period)

  Start a periodic timer.

  Timer represented by `timer` should not be running when this function is called. This function starts the timer which will trigger every `period` microseconds.

  参数:

    - timer -- timer handle created using esp_timer_create()

    - period -- timer period, in microseconds

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if the handle is invalid

    - ESP_ERR_INVALID_STATE if the timer is already running

esp_err_t esp_timer_restart(esp_timer_handle_t timer, uint64_t timeout_us)

  Restart a currently running timer.

  Type of `timer` | Action
  --- | ---
  One-shot timer | Restarted immediately and times out once in `timeout_us` microseconds
  Periodic timer | Restarted immediately with a new period of `timeout_us` microseconds

  参数:

    - timer -- timer handle created using esp_timer_create()

    - timeout_us -- Timeout in microseconds relative to the current time. In case of a periodic timer, also represents the new period.

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if the handle is invalid

    - ESP_ERR_INVALID_STATE if the timer is not running

esp_err_t esp_timer_stop(esp_timer_handle_t timer)

  Stop a running timer.

  This function stops the timer previously started using esp_timer_start_once() or esp_timer_start_periodic().

  参数:

    timer -- timer handle created using esp_timer_create()

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_STATE if the timer is not running

esp_err_t esp_timer_delete(esp_timer_handle_t timer)

  Delete an esp_timer instance.

  The timer must be stopped before deleting. A one-shot timer which has expired does not need to be stopped.

  参数:

    timer -- timer handle created using esp_timer_create()

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_STATE if the timer is running

int64_t esp_timer_get_time(void)

  Get time in microseconds since boot.

  返回:

    Number of microseconds since the initialization of ESP Timer

int64_t esp_timer_get_next_alarm(void)

  Get the timestamp of the next expected timeout.

  返回:

    Timestamp of the nearest timer event, in microseconds. The timebase is the same as for the values returned by esp_timer_get_time().

int64_t esp_timer_get_next_alarm_for_wake_up(void)

  Get the timestamp of the next expected timeout excluding those timers that should not interrupt light sleep (such timers have esp_timer_create_args_t::skip_unhandled_events enabled)

  返回:

    Timestamp of the nearest timer event, in microseconds. The timebase is the same as for the values returned by esp_timer_get_time().

esp_err_t esp_timer_get_period(esp_timer_handle_t timer, uint64_t *period)

  Get the period of a timer.

  This function fetches the timeout period of a timer. For a one-shot timer, the timeout period will be 0.

  参数:

    - timer -- timer handle created using esp_timer_create()

    - period -- memory to store the timer period value in microseconds

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if the arguments are invalid

esp_err_t esp_timer_get_expiry_time(esp_timer_handle_t timer, uint64_t *expiry)

  Get the expiry time of a one-shot timer.

  This function fetches the expiry time of a one-shot timer.

  备注

  Passing the timer handle of a periodic timer will result in an error.

  参数:

    - timer -- timer handle created using esp_timer_create()

    - expiry -- memory to store the timeout value in microseconds

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if the arguments are invalid

    - ESP_ERR_NOT_SUPPORTED if the timer type is periodic

esp_err_t esp_timer_dump(FILE *stream)

  Dump the list of timers to a stream.

  By default, this function prints the list of active (running) timers. The output format is:

  | Name | Period | Alarm |

  - Name — timer pointer

  - Period — period of timer in microseconds, or 0 for one-shot timer

  - Alarm - time of the next alarm in microseconds since boot, or 0 if the timer is not started

  To print the list of all created timers, enable Kconfig option `CONFIG_ESP_TIMER_PROFILING`. In this case, the output format is:

  | Name | Period | Alarm | Times_armed | Times_trigg | Times_skip | Cb_exec_time |

  - Name — timer name

  - Period — same as above

  - Alarm — same as above

  - Times_armed — number of times the timer was armed via esp_timer_start_X

  - Times_triggered - number of times the callback was triggered

  - Times_skipped - number of times the callback was skipped

  - Callback_exec_time - total time taken by callback to execute, across all calls

  参数:

    stream -- stream (such as stdout) to which to dump the information

  返回:

    - ESP_OK on success

    - ESP_ERR_NO_MEM if can not allocate temporary buffer for the output

void esp_timer_isr_dispatch_need_yield(void)

  Requests a context switch from a timer callback function.

  This only works for a timer that has an ISR dispatch method. The context switch will be called after all ISR dispatch timers have been processed.

bool esp_timer_is_active(esp_timer_handle_t timer)

  Returns status of a timer, active or not.

  This function is used to identify if the timer is still active (running) or not.

  参数:

    timer -- timer handle created using esp_timer_create()

  返回:

    - 1 if timer is still active (running)

    - 0 if timer is not active

esp_err_t esp_timer_new_etm_alarm_event(esp_etm_event_handle_t *out_event)

  Get the ETM event handle of esp_timer underlying alarm event.

  备注

  The created ETM event object can be deleted later using esp_etm_del_event()

  备注

  The ETM event is generated by the underlying hardware - systimer; therefore, if the esp_timer is not clocked by systimer, then no ETM event will be generated.

  参数:

    out_event -- [out] Returned ETM event handle

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

### Structures

struct esp_timer_create_args_t

  Timer configuration passed to esp_timer_create()

  Public Members

  esp_timer_cb_t callback

    Callback function to execute when timer expires.

  void *arg

    Argument to pass to callback.

  esp_timer_dispatch_t dispatch_method

    Dispatch callback from task or ISR; if not specified, esp_timer task.

  const char *name

    Timer name, used in esp_timer_dump() function.

  bool skip_unhandled_events

    Setting to skip unhandled events in light sleep for periodic timers.

### Type Definitions

typedef struct esp_timer *esp_timer_handle_t

  Opaque type representing a single timer handle.

typedef void (*esp_timer_cb_t)(void *arg)

  Timer callback function type.

  Param arg:

    pointer to opaque user-specific data

### Enumerations

enum esp_timer_dispatch_t

  Method to dispatch timer callback.

  Values:

  enumerator ESP_TIMER_TASK

    Callback is dispatched from esp_timer task.

  enumerator ESP_TIMER_ISR

    Callback is dispatched from interrupt handler.

  enumerator ESP_TIMER_MAX

    Sentinel value for the number of callback dispatch methods.

提供有关此文档的反馈