Merge https://github.com/adafruit/RTClib

RTClib.cpp

@@ -1335,15 +1335,34 @@ void RTC_PCF8523::deconfigureAllTimers() {
 
 /**************************************************************************/
 /*!
-    @brief  Use an offset to calibrate the PCF8523.
-    @details This can be used for:
-            - Aging adjustment
-            - Temperature compensation
-            - Accuracy tuning
-    @param mode The offset mode to use, once every two hours or once every
-   minute. See the #Pcf8523OffsetMode enum.
-    @param offset Offset value from -64 to +63. See the datasheet for exact ppm
-   values.
+    @brief Compensate the drift of the RTC.
+    @details This method sets the "offset" register of the PCF8523,
+      which can be used to correct a previously measured drift rate.
+      Two correction modes are available:
+
+      - **PCF8523\_TwoHours**: Clock adjustments are performed on
+        `offset` consecutive minutes every two hours. This is the most
+        energy-efficient mode.
+
+      - **PCF8523\_OneMinute**: Clock adjustments are performed on
+        `offset` consecutive seconds every minute. Extra adjustments are
+        performed on the last second of the minute is `abs(offset)>60`.
+
+      The `offset` parameter sets the correction amount in units of
+      roughly 4 ppm. The exact unit depends on the selected mode:
+
+      |  mode               | offset unit                            |
+      |---------------------|----------------------------------------|
+      | `PCF8523_TwoHours`  | 4.340 ppm = 0.375 s/day = 2.625 s/week |
+      | `PCF8523_OneMinute` | 4.069 ppm = 0.352 s/day = 2.461 s/week |
+
+      See the accompanying sketch pcf8523.ino for an example on how to
+      use this method.
+
+    @param mode Correction mode, either `PCF8523_TwoHours` or
+      `PCF8523_OneMinute`.
+    @param offset Correction amount, from -64 to +63. A positive offset
+      makes the clock slower.
 */
 /**************************************************************************/
 void RTC_PCF8523::calibrate(Pcf8523OffsetMode mode, int8_t offset) {

examples/pcf8523/pcf8523.ino

@@ -44,6 +44,29 @@ void setup () {
   // to be restarted by clearing the STOP bit. Let's do this to ensure
   // the RTC is running.
   rtc.start();
+  
+   // The PCF8523 can be calibrated for:
+  //        - Aging adjustment
+  //        - Temperature compensation
+  //        - Accuracy tuning
+  // The offset mode to use, once every two hours or once every minute.
+  // The offset Offset value from -64 to +63. See the Application Note for calculation of offset values.
+  // https://www.nxp.com/docs/en/application-note/AN11247.pdf
+  // The deviation in parts per million can be calculated over a period of observation. Both the drift (which can be negative)
+  // and the observation period must be in seconds. For accuracy the variation should be observed over about 1 week.
+  // Note: any previous calibration should cancelled prior to any new observation period.
+  // Example - RTC gaining 43 seconds in 1 week
+  float drift = 43; // seconds plus or minus over oservation period - set to 0 to cancel previous calibration.
+  float period_sec = (7 * 86400);  // total obsevation period in seconds (86400 = seconds in 1 day:  7 days = (7 * 86400) seconds )
+  float deviation_ppm = (drift / period_sec * 1000000); //  deviation in parts per million (μs)
+  float drift_unit = 4.34; // use with offset mode PCF8523_TwoHours
+  // float drift_unit = 4.069; //For corrections every min the drift_unit is 4.069 ppm (use with offset mode PCF8523_OneMinute)
+  int offset = round(deviation_ppm / drift_unit);
+  // rtc.calibrate(PCF8523_TwoHours, offset); // Un-comment to perform calibration once drift (seconds) and observation period (seconds) are correct
+  // rtc.calibrate(PCF8523_TwoHours, 0); // Un-comment to cancel previous calibration
+
+  Serial.print("Offset is "); Serial.println(offset); // Print to control offset
+
 }
 
 void loop () {

library.properties

@@ -1,5 +1,5 @@
 name=RTClib
-version=1.11.3
+version=1.11.4
 author=Adafruit
 maintainer=Adafruit <info@adafruit.com>
 sentence=A fork of Jeelab's fantastic RTC library