Add functionality to address different I2C peripherals.

Author: JChristensen

README.md

@@ -13,8 +13,18 @@ This program is distributed in the hope that it will be useful, but WITHOUT ANY
 
 You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/gpl.html>
 
-## Important note: Library v2.0.0
+## Version 3.0.0 notes
+Version 3.0.0 adds the ability to address different I2C peripherals for microcontrollers that have more than one (e.g. `Wire`, `Wire1`, etc.) There is one situation that is not backwards compatible with earlier versions of the library. Code that calls `setSyncProvider()` in the [Time library](https://github.com/PaulStoffregen/Time), e.g.:
+```c++
+    setSyncProvider(myRTC.get);
+```
+Needs to change as follows:
+```c++
+    setSyncProvider([](){return myRTC.get();});
+```
+This uses a lambda to provide the Time library with a static function, which it requires. The `MCP79412::get()` function was static in previous versions of the library, but no longer is in v3.0.0. This allows the flexibility to operate with different I2C peripherals.
 
+## Version 2.0.0 notes
 The 2.0.0 version of the library has some significant changes and is not completely backwards compatible with earlier versions. These changes provide a more consistent API and reduce the possibility of name collisions. While sketches using this library will likely require changes as a result, these should be mostly straightforward.
 
  - The library no longer defines a `DS3232RTC` object, therefore each sketch needs to define  one. (Previous versions of the library defined a DS3232RTC object named `RTC`, although only for AVR architecture. Consider using a name other than `RTC` as this can cause a name collision on some architectures.)
@@ -41,6 +51,7 @@ The following example sketches are included with the **DS3232RTC** library:
 - **rtcTimeTemp:** Displays time and temperature.
 - **rtc_temperature:** Displays time and temperature but initiates a temperature conversion every 10 seconds in addition to the RTC's default conversion period of 64 seconds.
 - **rtc_interrupt:** Uses a 1Hz interrupt from the RTC to keep time.
+- **rtc_wire1:** Raspberry Pi Pico example using `Wire1`.
 - **mcu_clock_drift:** Demonstrates that MCU time as kept by the **Time** library will drift as compared to RTC time, and that MCU time may not increase by one second every second.
 - **tiny3232_KnockBang:** Demonstrates interfacing an ATtiny45/85 to a DS3231 or DS3232 RTC.
 - Several examples for using the RTC alarms. See the [alarm primer](https://github.com/JChristensen/DS3232RTC/blob/master/alarm-primer.md) for more information.
@@ -87,18 +98,20 @@ Symbolic names used with the squareWave() function (described below).
 - SQWAVE_8192_HZ
 
 ## Constructor
-### DS3232RTC()
+### DS3232RTC(TwoWire& wire)
 ##### Description
-Instantiates a DS3232RTC object.
+Instantiates a `DS3232RTC` object.
 ##### Syntax
-`DS3232RTC myRTC;`
+`DS3232RTC myRTC(wire);`
 ##### Parameters
-None.
+**wire:** An optional parameter to specify which I2C bus to use. If omitted, defaults to `Wire`. *(TwoWire&)*.
 ##### Returns
 None.
 ##### Example
 ```c++
-DS3232RTC myRTC;
+DS3232RTC myRTC;          // to use Wire
+// or
+DS3232RTC myRTC(Wire1);   // to use Wire1
 ```
 
 ## Initialization function
@@ -408,6 +421,21 @@ myRTC.squareWave(DS3232RTC::SQWAVE_1_HZ);   // 1 Hz square wave
 myRTC.squareWave(DS3232RTC::SQWAVE_NONE);   // no square wave
 ```
 
+### enable32kHz(bool enable)
+##### Description
+Enables or disables the 32kHz square wave output.
+##### Syntax
+`myRTC.enable32kHz(enable);`
+##### Parameters
+**enable:** true, false, or boolean expression. *(bool)*  
+##### Returns
+None.
+##### Example
+```c++
+myRTC.enable32kHz(true);   // 32kHz output enabled
+myRTC.enable32kHz(false);  // 32kHz output disabled
+```
+
 ### oscStopped(bool clearOSF)
 ##### Description
 Returns the value of the oscillator stop flag (OSF) bit in the control/status register which indicates that the oscillator is or was stopped, and that the timekeeping data may be invalid. Optionally clears the OSF bit depending on the argument passed. If the `clearOSF` argument is omitted, the OSF bit is cleared by default. Calls to `set()` and `write()` also clear the OSF bit.

examples/SetSerial/SetSerial.ino

@@ -40,7 +40,7 @@ void setup()
 
     // setSyncProvider() causes the Time library to synchronize with the
     // external RTC by calling RTC.get() every five minutes by default.
-    setSyncProvider(myRTC.get);
+    setSyncProvider([](){return myRTC.get();});
     Serial << F("RTC Sync");
     if (timeStatus() != timeSet) Serial << F(" FAIL!");
     Serial << endl;

examples/TimeRTC/TimeRTC.ino

@@ -14,7 +14,7 @@ void setup()
 {
     Serial.begin(115200);
     myRTC.begin();
-    setSyncProvider(myRTC.get);   // the function to get the time from the RTC
+    setSyncProvider([](){return myRTC.get();}); // the function to get the time from the RTC
     if(timeStatus() != timeSet)
         Serial.println("Unable to sync with the RTC");
     else

examples/alarm_ex6/alarm_ex6.ino

@@ -56,7 +56,7 @@ void setup()
 
     // setSyncProvider() causes the Time library to synchronize with the
     // external RTC by calling myRTC.get() every five minutes by default.
-    setSyncProvider(myRTC.get);
+    setSyncProvider([](){return myRTC.get();});
     Serial << "RTC Sync";
     if (timeStatus() != timeSet) {
         Serial << " FAIL!";

examples/mcu_clock_drift/mcu_clock_drift.ino

@@ -36,7 +36,7 @@ void setup()
     Serial.begin(115200);
     Serial.println(F("\n" __FILE__ " " __DATE__ " " __TIME__));
     myRTC.begin();
-    setSyncProvider(myRTC.get);     // the function to get the time from the RTC
+    setSyncProvider([](){return myRTC.get();}); // the function to get the time from the RTC
     Serial.print(F("RTC sync "));
     if (timeStatus() == timeSet)
         Serial.println(F("OK"));

examples/rtc_wire1/rtc_wire1.ino

@@ -0,0 +1,32 @@
+// Arduino DS3232RTC Library
+// https://github.com/JChristensen/DS3232RTC
+// rtc_wire1.ino
+// Example sketch with the RTC on the Wire1 bus.
+// Tested with Raspberry Pi Pico using the Arduino-Pico core,
+// https://github.com/earlephilhower/arduino-pico
+
+#include <DS3232RTC.h>  // http://github.com/JChristensen/DS3232RTC
+
+constexpr int sdaPin {26}, sclPin {27}; // I2C pins for Wire1 (your pins may vary)
+DS3232RTC myRTC(Wire1);
+
+void setup()
+{
+    Serial.begin(115200);
+    while (!Serial && millis() < 2000) delay(50);
+
+    Wire1.setSDA(sdaPin); Wire1.setSCL(sclPin);
+    myRTC.begin();
+    setSyncProvider([](){return myRTC.get();}); // the function to get the time from the RTC
+    if (timeStatus() != timeSet)
+        Serial.println("Unable to sync with the RTC");
+    else
+        Serial.println("RTC has set the system time");
+}
+
+void loop()
+{
+    Serial.printf("%.4d-%.2d-%.2d %.2d:%.2d:%.2d\n", year(), month(), day(),
+        hour(), minute(), second());
+    delay(1000);
+}

examples/tiny3232_KnockBang/tiny3232_KnockBang.ino

@@ -29,7 +29,7 @@ void setup()
 
     // setSyncProvider() causes the Time library to synchronize with the
     // external RTC by calling myRTC.get() every five minutes by default.
-    setSyncProvider(myRTC.get);
+    setSyncProvider([](){return myRTC.get();});
     Debug.print(F("RTC Sync"));
     if (timeStatus() != timeSet) Debug.print(F(" FAIL!"));
     Debug.println();

library.properties

@@ -1,5 +1,5 @@
 name=DS3232RTC
-version=2.0.1
+version=3.0.0
 author=Jack Christensen <jack.christensen@outlook.com>
 maintainer=Jack Christensen <jack.christensen@outlook.com>
 sentence=Arduino Library for Maxim Integrated DS3232 and DS3231 Real-Time Clocks.

src/DS3232RTC.cpp

@@ -8,8 +8,6 @@
 
 #include <DS3232RTC.h>
 
-uint8_t DS3232RTC::errCode;
-
 // Initialize the I2C bus.
 void DS3232RTC::begin()
 {

src/DS3232RTC.h

@@ -23,20 +23,20 @@
 #define i2cWrite TinyWireM.send
 #elif ARDUINO >= 100
 #include <Wire.h>
-#define i2cBegin Wire.begin
-#define i2cBeginTransmission Wire.beginTransmission
-#define i2cEndTransmission Wire.endTransmission
-#define i2cRequestFrom Wire.requestFrom
-#define i2cRead Wire.read
-#define i2cWrite Wire.write
+#define i2cBegin wire.begin
+#define i2cBeginTransmission wire.beginTransmission
+#define i2cEndTransmission wire.endTransmission
+#define i2cRequestFrom wire.requestFrom
+#define i2cRead wire.read
+#define i2cWrite wire.write
 #else
 #include <Wire.h>
-#define i2cBegin Wire.begin
-#define i2cBeginTransmission Wire.beginTransmission
-#define i2cEndTransmission Wire.endTransmission
-#define i2cRequestFrom Wire.requestFrom
-#define i2cRead Wire.receive
-#define i2cWrite Wire.send
+#define i2cBegin wire.begin
+#define i2cBeginTransmission wire.beginTransmission
+#define i2cEndTransmission wire.endTransmission
+#define i2cRequestFrom wire.requestFrom
+#define i2cRead wire.receive
+#define i2cWrite wire.send
 #endif
 
 #ifndef _BV
@@ -131,12 +131,11 @@ class DS3232RTC
             DS32_CENTURY     {7},        // Century bit in Month register
             DS32_DYDT        {6};        // Day/Date flag bit in alarm Day/Date registers
 
-        DS3232RTC() {};
-        DS3232RTC(bool initI2C) { (void)initI2C; }  // undocumented for backward compatibility
+        DS3232RTC(TwoWire& tw=Wire) : wire(tw) {};
         void begin();
-        static time_t get();    // static needed to work with setSyncProvider() in the Time library
+        time_t get();
         uint8_t set(time_t t);
-        static uint8_t read(tmElements_t &tm);
+        uint8_t read(tmElements_t &tm);
         uint8_t write(tmElements_t &tm);
         uint8_t writeRTC(uint8_t addr, uint8_t* values, uint8_t nBytes);
         uint8_t writeRTC(uint8_t addr, uint8_t value);
@@ -152,11 +151,12 @@ class DS3232RTC
         void enable32kHz(bool enable);
         bool oscStopped(bool clearOSF = false);
         int16_t temperature();
-        static uint8_t errCode;
+        uint8_t errCode;
 
     private:
+        TwoWire& wire;      // reference to Wire, Wire1, etc.
         uint8_t dec2bcd(uint8_t n);
-        static uint8_t bcd2dec(uint8_t n);
+        uint8_t bcd2dec(uint8_t n);
 };
 
 #endif