From bf1d8ab1d47ca764d43c67ecf9a38ac855cc4352 Mon Sep 17 00:00:00 2001
From: Klaus K Wilting <Klaus.K.Wilting@deutschebahn.com>
Date: Mon, 28 Jan 2019 21:47:44 +0100
Subject: [PATCH] if482.cpp: comments added

---
 src/if482.cpp | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/if482.cpp b/src/if482.cpp
index 48d98a47..3914c7d2 100644
--- a/src/if482.cpp
+++ b/src/if482.cpp
@@ -1,7 +1,19 @@
 #if defined HAS_IF482 && defined HAS_RTC
 
-/*
+/* NOTE:
+The IF482 Generator needs an high precise 1 Hz clock signal which cannot be
+acquired in suitable precision on the ESP32 SoC itself. Additional clocking
+hardware is required, ususally the clock signal is generated by external RTC or
+GPS chip or a GPS chip which can generate a precise clock signal (+/- 2ppm). In
+this example code we use a Maxim DS3231 RTC chip, and configure it's interrupt
+output as clock output. The clock signal triggers an interrupt on the ESP32,
+which controls the realtime output of IF482 telegram. This is why code in
+IF482.cpp depends on code in RTCTIME.cpp.
+*/
 
+///////////////////////////////////////////////////////////////////////////////
+
+/*
 IF482 Generator to control clocks with IF482 telegram input (e.g. BÜRK BU190)
    
 Example IF482 telegram: "OAL160806F170400"
@@ -63,6 +75,7 @@ L: Local Time
 not evaluated by model BU-190
 
 */
+///////////////////////////////////////////////////////////////////////////////
 
 #include "if482.h"
 
@@ -79,7 +92,7 @@ int if482_init(void) {
   // open serial interface
   IF482.begin(HAS_IF482);
 
-  // use rtc 1Hz clock for triggering IF482 telegram send
+  // use external rtc 1Hz clock for triggering IF482 telegram
   Rtc.SetSquareWavePinClockFrequency(DS3231SquareWaveClock_1Hz);
   Rtc.SetSquareWavePin(DS3231SquareWavePin_ModeClock);
   pinMode(RTC_INT, INPUT_PULLUP);
@@ -124,7 +137,7 @@ void if482_loop(void *pvParameters) {
   time_t t, tt;
   const TickType_t shotTime = pdMS_TO_TICKS(IF482_OFFSET);
 
-  // wait until begin of a new second
+  // wait until begin of a new second to sync clock signal and absolute time
   t = tt = now();
   do {
     tt = now();
@@ -146,7 +159,7 @@ void if482_loop(void *pvParameters) {
     // now we're synced to start of second t and wait
     // until it's time to start transmit telegram for t+1
     vTaskDelayUntil(&wakeTime, shotTime);
-    IF482.print(if482Telegram(t+1));
+    IF482.print(if482Telegram(t + 1));
   }
   vTaskDelete(IF482Task); // shoud never be reached
 } // if482_loop()