calibrate()

The calibrate method allows fine-tuning of the MCP7940's accuracy. The oscillator/crystal's speed can change due to circuit design, capacitor sizing and temperature; all of which can introduce timing errors over time. The MCP7940 has an internal register which allow the clock to be slowed down or sped up in order to compensate for these errors. Every unit of trim equates to 2 clock cycles per minute. The function can be called in several ways:

1. calibrate(); This resets any programmed trim values back to 0.
2. calibrate(uint8_t); This sets the programmed trim to parameter value. Negative values mean that the MCP7940 oscillator is slower than the expected speed. Values range from +/- 127
3. calibrate(DateTime); This represents the actual DateTime. This is compared with the current RTC value to get a delta and this is combined with the total amount of time that the RTC has been running to come up with a new trim register value. The longer the Calibration period the better the resulting trim correction will be. Since the RTC only stores time down to the second and is generally quite accurate, it will take many hours (if not days) to be off by one second. The example program CalibrateFromGPS.ino demonstrates how a GPS (in this case, the Adafruit Ultimate GPS, can be used to calibrate a newly implemented MCP7940 in a circuit. Note that the trim offset is only valid for a given chip in a given circuit at a given temperature. This call will not only adjust the internal trim value but also reset the RTC's time to the one given.
4. calibrate(float); This is used to calibrate by passing in an actual frequency that has been measured on the Square-Wave pin. The square-wave pin can be set using setSQWSpeed and the current value is compared to the speed parameter and the trim is adjusted accordingly.

---

Example:

...
MCP7940_Class MCP7940;        // Create an instance of the MCP7940
DateTime      NewDateAndTime; // hold a DateTime value
...
void setup() {
  Serial.begin(SERIAL_SPEED);
  while (!MCP7940.begin()) { // Initialize RTC communications
    Serial.println("Unable to find MCP7940. Checking again in 1 second.");
    delay(1000);
  } // of loop until device is located
  MCP7940.adjust(); // Set the RTC to the Date/Time of library compile
  
... (very long period of time, set NewDateAndTime )
  int8_t newTrimValue = MCP7940.Calibrate(NewDateAndTime);
  Serial.print("New Trim value is ");Serial.println(newTrimValue);
...