From 21db69dfdcedd3dc5f2976610b881cd705a10873 Mon Sep 17 00:00:00 2001 From: mikee47 Date: Mon, 15 Jan 2024 21:20:59 +0000 Subject: [PATCH] Add note in documentation about behaviour of one-shot Hardware timer with Esp8266 --- .../Components/driver/include/driver/hw_timer.h | 7 ++++++- docs/source/framework/timers/hardware-timer.rst | 14 ++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/Sming/Arch/Esp8266/Components/driver/include/driver/hw_timer.h b/Sming/Arch/Esp8266/Components/driver/include/driver/hw_timer.h index 069f8dafc1..1d7a7459f7 100644 --- a/Sming/Arch/Esp8266/Components/driver/include/driver/hw_timer.h +++ b/Sming/Arch/Esp8266/Components/driver/include/driver/hw_timer.h @@ -80,7 +80,12 @@ void IRAM_ATTR hw_timer1_attach_interrupt(hw_timer_source_type_t source_type, hw * @brief Enable the timer * @param div * @param intr_type - * @param auto_load + * @param auto_load true for repeating timer, false for one-shot + * + * Note: With one-shot timer application callback must stop the timer when it is no longer required. + * This is to reduce callback latency. + * If this is not done, timer will trigger again when timer counter wraps around to 0. + * For /16 divisor this is only 1.7s. */ inline void IRAM_ATTR hw_timer1_enable(hw_timer_clkdiv_t div, hw_timer_intr_type_t intr_type, bool auto_load) { diff --git a/docs/source/framework/timers/hardware-timer.rst b/docs/source/framework/timers/hardware-timer.rst index 713edb7be7..ee27c2932c 100644 --- a/docs/source/framework/timers/hardware-timer.rst +++ b/docs/source/framework/timers/hardware-timer.rst @@ -11,5 +11,19 @@ The API for hardware (and :doc:`timer-queue` timers) is identical, implemented u :cpp:class:`CallbackTimer` class template for best performance. +.. note:: + + **Applies to Esp8266 architecture only.** + + As with all Callback timers, the :cpp:type:`HardwareTimer` can be one-shot or repeating. + + With the Esp8266 a one-shot timer will repeat after it has been triggered, but only after the timer + counter wraps around. The Esp8266 only has 23 bits of resolution so with a clock divider of 16 + this will happen after about 1.7s. + + Because the Esp8266 lacks any proper PWM hardware the timer latency is critical. + Adding any additional code to the callback is therefore left to the programmer. + + .. doxygengroup:: hardware_timer :members: