From 9802d4dc13a81502f5f952c7e75707495cdaa022 Mon Sep 17 00:00:00 2001
From: Mike <mike@sillyhouse.net>
Date: Tue, 16 Jan 2024 08:32:23 +0000
Subject: [PATCH] Add note in documentation about behaviour of one-shot
 Hardware timer with Esp8266 (#2713)

---
 .../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 a8214a1373..e5bb203c7c 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: