From 3b2d17f5f85a7f72d2f9f57e789c1e08881c7ad1 Mon Sep 17 00:00:00 2001
From: doctea <doctea@gmail.com>
Date: Tue, 26 Mar 2024 21:58:08 +0000
Subject: [PATCH] update readme, remove debug, add some comments

---
 README.md               | 26 +++++++++++++++++++++++++-
 src/platforms/generic.h | 11 ++++++++---
 2 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 68115fd..4630911 100755
--- a/README.md
+++ b/README.md
@@ -2,7 +2,9 @@
 
 The **uClock BPM Generator library** is designed to implement precise and reliable BPM clock tick calls using the microcontroller's timer hardware interruption. It is designed to be multi-architecture, portable, and easy to use within the Opensource community universe. 
 
-We have chosen PlatformIO and Arduino as our official deployment platforms. The library has been supported and tested on general **AVR boards (ATmega168/328, ATmega16u4/32u4, and ATmega2560)** as well as **ARM boards (Teensy, STM32XX, and Seedstudio XIAO M0)**.
+We have chosen PlatformIO and Arduino as our official deployment platforms. The library has been supported and tested on general **AVR boards (ATmega168/328, ATmega16u4/32u4, and ATmega2560)** as well as **ARM boards (Teensy, STM32XX, and Seedstudio XIAO M0)**.  
+
+(See also the generic fallback mode)
 
 The absence of real-time features necessary for creating professional-level embedded devices for music and video on Opensource community-based platforms like Arduino led to the development of uClock. By leveraging the use of timer hardware interruptions, the library can schedule and manage real-time-like processing with safe shared resource access through its API.
 
@@ -18,6 +20,28 @@ The uClock library API operates through attached callback functions mechanism:
 5. **setOnClockStart(onClockStartCallback) > onClockStartCallback()** on uClock Start event
 6. **setOnClockStop(onClockStopCallback) > onClockStopCallback()** on uClock Stop event
 
+### Generic mode - for unsupported boards (or avoiding usage of interrupts)
+If a supported board isn't detected during compilation then a generic fallback approach will be used that does not utilise any interrupts to ensure accurate timekeeping.  This can be useful to port projets to boards that do not have support in uClock yet, or to test if suspected bugs are related to interactions with interrupts or task handling.
+
+You can force this non-interrupt "generic mode" even on supported boards by defining the build flag `USE_UCLOCK_GENERIC`.
+
+In order for generic mode to work, you need to add a call to your `loop()` function to process ticks. For example,
+
+```c++
+
+// prototype of 
+void uClockCheckTime(uint32_t micros_time);
+
+void loop() {
+  #ifdef USE_UCLOCK_GENERIC
+    uClockCheckTime(micros());
+  #endif
+  
+  // do anything else you need to do inside loop()...
+}
+```
+
+
 ## uClock v2.0 Breakchanges
 
 If you are comming from uClock version < 2.0 versions keep attention to the breakchanges so you can update your code to the new API interface changes:
diff --git a/src/platforms/generic.h b/src/platforms/generic.h
index 9b543a4..4e381a4 100644
--- a/src/platforms/generic.h
+++ b/src/platforms/generic.h
@@ -1,6 +1,12 @@
 #include <Arduino.h>
 
-//#define ATOMIC(X) noInterrupts(); X; interrupts();
+/* 
+    Generic fallback approach that doesn't rely on any particular MCU's interrupts or RTOS threads etc.
+    Simply checks micros() and compares last time tick happened and interval size to determine when a tick is due.
+    requires calling uClockCheckTime(micros()); inside loop() in order to trigger tick processing. 
+    function signature: void uClockCheckTime(uint32_t micros_time);
+*/
+
 #define ATOMIC(X) X;
 
 // forward declaration of ISR
@@ -12,7 +18,7 @@ uint32_t uclock_us_interval;
 // call this as often as possible to tick the uClock
 void uClockCheckTime(uint32_t micros_time) {
     if (micros_time - uclock_last_time_ticked >= uclock_us_interval) {
-        uclock_last_time_ticked = micros();
+        uclock_last_time_ticked = micros_time;
         uClockHandler();
     }
 }
@@ -26,5 +32,4 @@ void initTimer(uint32_t init_clock)
 void setTimer(uint32_t us_interval)
 {
     uclock_us_interval = us_interval;
-    Serial.printf("setTimer(%d)\n", us_interval); Serial.flush();
 }
\ No newline at end of file