Add rv 3032 c7 support

[alx2009]

This pull request adds support for Micro Crystal AG RV-3032-C7, a new accurate I²C RTC with integrated crystal and digital temperature compensation.

The RV-3032-C7 can be used in a similar way to the the DS3231 in most applications where the RTClib would be used. This is especially interesting because the DS3231 is very difficult to source right now. As of this writing, Digikey has 10K RV-3032-C7 in stock, and the next shipment is scheduled in "just" 3 months.

As can be expected from a new chip, the RV-3032-C7 bests the DS3231 in a number of ways:

• Wider operating voltage range: 1.3 V to 5.5 V

•  Backup can be as low as 1.2 V with temperature compensation
  

•  Timekeeping down to 1V (but no temperature compensation)
  

•  Ultra low power consumption: 160 nA @ 3 V
  

•  Time accuracy: -40°C to +85°C, ±2.5 ppm
  

•  Charge pumps for trickle charge of backup capacitor/battery
  

•  12 bit temp. resolution (new reading every second)
  

•  Very compact 8-WCDFN package  (3.2 x 1.5 x 0.8 mm)
  

See Data sheet summary for more information: https://www.microcrystal.com/fileadmin/Media/Products/RTC/Datasheet/RV-3032-C7.pdf

Product page for the full application manual and more: https://www.microcrystal.com/en/products/real-time-clock-rtc-modules/rv-3032-c7/

This is an initial release of the RV-3032-C7 support for RTClib. It includes setting time, alarm and enabling/disabling the CLKOUT pin.

I tried to keep the API as close as possible to the DS3231 behaviour except where it would be misleading. Feedback and suggestions are of course welcomed.

Assuming the idea of including this chip in RTClib is approved, I intend to add more features, in particular:

• readme file specific to RV-3032-C7 with more usage details
• controlling the CLKOUT frequency
• support for periodic timers
• support for time stamping external events (works even when the chip is on backup power)
• support for read/write the user RAM and EEPROM

I can add other features if there is interest.

Some features like trickle charge may be unsafe for beginners, so I am not currently planning to provide direct support for activation (they are off by default). I may provide an example if there is an interest (and then the library would work).

Tested with Arduino Uno, Arduino MKR1000, Adafruit Adafruit QT Py - SAMD21. More testing will follow.

For full disclosure, I have developed this library with an eval board provided free of charge by Micro Crystal AG, but I have no other affiliation with the company and I will not receive any form of compensation for this work.

[edgar-bonet]

This looks like a great addition! I have a couple of small issues. These are only my personal suggestions though: I am not a maintainer of this library.

[edgar-bonet]

According to the Arduino Library Specification, within keywords.txt

the fields should be “separated by a single true tab (not spaces)”

Oh, wait, the three keywords just above your addition already have this problem... This will have to be fixed, maybe in another pull request.

[alx2009]

Good catch, it was a copy/paste then modify... but I should have noticed that the keyword was not recognized in the Arduino GUI! I think I will correct that in the next update.

[edgar-bonet]

This should probably be removed.

[alx2009]

Agreed! It will be removed in the next update, coming soon.

[edgar-bonet]

I have a few suggestions regarding the documentation of this new class:

1. List the class in the comment block at the top of RTClib.h. This ensures that it appears in the list of available classes in the library's reference page.

   diff --git a/src/RTClib.cpp b/src/RTClib.cpp
   index 8f1f4ea..4719480 100644
   --- a/src/RTClib.cpp
   +++ b/src/RTClib.cpp
   @@ -29,6 +29,7 @@
        - RTC_DS3231
        - RTC_PCF8523
        - RTC_PCF8563
   +    - RTC_RV3032C7
      - RTC emulated in software; do not expect much accuracy out of these:
        - RTC_Millis is based on `millis()`
        - RTC_Micros is based on `micros()`; its drift rate can be tuned by

2. Use the correct name RV3032C7EventType (with a final ‘e’) in the documentation of both setAlarm() and enableCountdownTimer(). The former could also be turned into a link:

   diff --git a/src/RTC_RV3032C7.cpp b/src/RTC_RV3032C7.cpp
   index 30b0f65..459ae9c 100644
   --- a/src/RTC_RV3032C7.cpp
   +++ b/src/RTC_RV3032C7.cpp
   @@ -194,7 +194,7 @@ float RTC_RV3032C7::getTemperature() {
       disableAlarm().
            @param         dt DateTime object
            @param         alarm_mode Desired mode, see RV3032C7AlarmMode enum
   -        @param   event_type Desired event type, see RV3032C7EventTyp enum
   +        @param   event_type Desired event type, see #RV3032C7EventType enum
        @return False if alarm registers are not set, otherwise true
    */
    /**************************************************************************/
   @@ -361,7 +361,7 @@ bool RTC_RV3032C7::alarmFired(void) {
            @param clkFreq One of the RV3032C7's Periodic Countdown Timer Clock Frequencies.
             See the #RV3032C7TimerClockFreq enum for options and associated time ranges.
            @param numPeriods The number of clkFreq periods (1-4095) to count down.
   -        @param   event_type Desired event type, see #RV3032C7EventTyp enum
   +        @param   event_type Desired event type, see #RV3032C7EventType enum
    */
    /**************************************************************************/
    void RTC_RV3032C7::enableCountdownTimer(RV3032C7TimerClockFreq clkFreq, uint8_t numPeriods, RV3032C7EventType event_type) {

3. Doxygen complains that the macro RV3032C7InvalidDate is not documented, and that the following methods also lack documentation:

   • getCountdownTimerEventType()
   • disableCountdownTimer(void)
   • clearCountdownTimer(void)
   • CountdownTimerFired(void)

   It appears that none of these methods have been defined (getCountdownTimerEventType() has been defined as a plain function, which is likely a mistake).