Struct TimerDriver

Source

pub struct TimerDriver<'d> { /* private fields */ }

Expand description

General Purpose Timer driver.

You can use this driver to get notified when a certain amount of time has passed (TimerDriver::subscribe), or to measure time intervals (TimerDriver::get_raw_count).

The driver has the following states:

“init” state: After creation of the driver, or after calling TimerDriver::disable.
“enable” state: After calling TimerDriver::enable. In this state, the timer is ready to be started, but the internal counter is not running yet.
“run” state: After calling TimerDriver::start. In this state, the internal counter is running. To stop the counter, call TimerDriver::stop, which would transition back to “enable” state.

Implementations§

Source §

impl<'d> TimerDriver<'d>

Source

pub fn new(config: &TimerConfig) -> Result<Self, EspError>

Create a new General Purpose Timer, and return the handle.

The state of the returned timer will be “init” state.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument
ESP_ERR_NO_MEM: Failed because out of memory
ESP_ERR_NOT_FOUND: Failed because all hardware timers are used up and no more free one
ESP_FAIL: Failed because of other error

Source

pub fn handle(&self) -> gptimer_handle_t

Returns the underlying GPTimer handle.

Source

pub fn duration_to_count(&self, duration: Duration) -> Result<u64, EspError>

Converts the given duration to the corresponding timer count value.

§Errors

If Self::get_resolution fails, this function will return the same error.

This function might overflow if the duration is too long to be represented as ticks with the current timer resolution. In that case an error with the code ERR_EOVERFLOW will be returned.

Source

pub async fn delay(&self, duration: Duration) -> Result<(), EspError>

Asynchronously delay for the specified duration.

This function will reset the timer count to 0, and set a one-shot alarm. Any existing count or alarm configuration will be overwritten. This function does not Self::start or Self::enable the timer, this must be done beforehand.

§Errors

If there is no interrupt service registered, it will return an ESP_ERR_INVALID_STATE. To enable interrupts, either register your own callback through Self::subscribe/Self::subscribe_nonstatic, or call Self::subscribe_default.

Source

pub async fn wait(&self) -> Result<(), EspError>

Wait for the timer alarm event interrupt.

§Errors

If this function is called without a registered ISR, it will return an ESP_ERR_INVALID_STATE. To enable interrupts, either register your own callback through Self::subscribe/Self::subscribe_nonstatic, or call Self::subscribe_default.

Source

pub fn reset_wait(&self)

Resets the internal wait notification.

If no callback is registered, this function does nothing.

Source

pub fn set_raw_count(&self, value: u64) -> Result<(), EspError>

Set GPTimer raw count value.

When updating the raw count of an active timer, the timer will immediately start counting from the new value.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument
ESP_FAIL: Failed because of other error

Source

pub fn get_raw_count(&self) -> Result<u64, EspError>

Get GPTimer raw count value.

This function will trigger a software capture event and then return the captured count value.

With the raw count value and the resolution returned from Self::get_resolution, you can convert the count value into seconds.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument (should not happen)
ESP_FAIL: Failed because of other error

Source

pub fn get_resolution(&self) -> Result<Hertz, EspError>

Return the real resolution of the timer.

Usually the timer resolution is same as what you configured in the TimerConfig::resolution, but some unstable clock source (e.g. RC_FAST) will do a calibration, the real resolution can be different from the configured one.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument (should not happen)
ESP_FAIL: Failed because of other error

Source

pub fn get_captured_count(&self) -> Result<u64, EspError>

Get GPTimer captured count value.

Different from Self::get_raw_count, this function won’t trigger a software capture event. It just returns the last captured count value. It’s especially useful when the capture has already been triggered by an external event and you want to read the captured value.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument (should not happen)
ESP_FAIL: Failed because of other error

Define the ISR handler for when the alarm event occurs.

The callbacks are expected to run in ISR context. The first call to this function should happen before the timer is enabled through Self::enable.

There is only one callback possible, you can not subscribe multiple callbacks.

§ISR Safety

Care should be taken not to call std, libc or FreeRTOS APIs (except for a few allowed ones) in the callback passed to this function, as it is executed in an ISR context.

You are not allowed to block, but you are allowed to call FreeRTOS APIs with the FromISR suffix.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument
ESP_ERR_INVALID_STATE: Failed because the timer is not in init state
ESP_FAIL: Failed because of other error

Source

pub unsafe fn subscribe_nonstatic( &mut self, on_alarm: impl FnMut(AlarmEventData) + Send + 'd, ) -> Result<(), EspError>

Subscribe a non-’static callback for when a transmission is done.

§Safety

You must not forget the driver (for example through [core::mem::forget]), while the callback is still subscribed, otherwise this would lead to undefined behavior.

To unsubscribe the callback, call Self::unsubscribe.

Source

pub fn subscribe_default(&mut self) -> Result<(), EspError>

Register the default callback.

This function will overwrite any previously registered callbacks. This is useful if you want to asynchronously wait for an alarm event through Self::wait or Self::delay.

Source

pub fn unsubscribe(&mut self) -> Result<(), EspError>

Unregister the previously registered callback.

Source

pub fn set_alarm_action( &self, config: Option<&AlarmConfig>, ) -> Result<(), EspError>

Set alarm event actions for GPTimer.

If the config is None, the alarm will be disabled.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument (should not happen)
ESP_FAIL: Failed because of other error

Source

pub fn enable(&self) -> Result<(), EspError>

Enable the timer.

This function will transition the timer from the “init” state to “enable” state.

§Note

This function will enable the interrupt service, if a callback has been registered through Self::subscribe.

It will acquire a power management lock, if a specific source clock (e.g. APB) is selected in the timer configuration, while CONFIG_PM_ENABLE is set in the project configuration.

To make the timer start counting, call Self::start.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument (should not happen)
ESP_ERR_INVALID_STATE: Failed because the timer is not in “init” state (e.g. already enabled)
ESP_FAIL: Failed because of other error

Source

pub fn disable(&self) -> Result<(), EspError>

Disable the timer.

This function will transition the timer from the “enable” state to “init” state.

§Note

This function will disable the interrupt service, if a callback has been registered through Self::subscribe.

It will release the power management lock, if it acquired one in Self::enable.

Disabling the timer will not make it stop counting. To make the timer stop counting, call Self::stop.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument (should not happen)
ESP_ERR_INVALID_STATE: Failed because the timer is not in “enable” state (e.g. already disabled)
ESP_FAIL: Failed because of other error

Source

pub fn start(&self) -> Result<(), EspError>

Start GPTimer (internal counter starts counting)

This function will transition the timer from the “enable” state to “run” state.

§Errors

ESP_ERR_INVALID_ARG: Failed because of invalid argument (should not happen)
ESP_ERR_INVALID_STATE: Failed because the timer is not enabled or already in running
ESP_FAIL: Failed because of other error

Source