Arduino DS3232RTC Library

https://github.com/JChristensen/DS3232RTC
README file
Jack Christensen
Mar 2013

License

Arduino DS3232RTC Library Copyright (C) 2018 Jack Christensen GNU GPL v3.0

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

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

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, e.g.:

    setSyncProvider(myRTC.get);

Needs to change as follows:

    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.)
• The constructor no longer has the capability to initialize the I2C bus and no longer accepts an optional parameter. Therefore, the sketch needs to call DS3232RTC::begin() in the setup() function or elsewhere as appropriate.
• To reduce the possibility of name collisions, the enumerations as well as register addresses, etc. are now defined in the header file within the DS3232RTC class. Therefore, when using any of these names, it will be necessary to include the DS3232RTC scope, e.g. myRTC.alarm(DS3232RTC::ALARM_1);
• Also to reduce collisions, register address names and bit names have been prefixed with DS32_ (see the header file.)
• The example sketches and documentation have been updated to reflect these changes.

Introduction

DS3232RTC is an Arduino library that supports the Maxim Integrated DS3231 and DS3232 Real-Time Clocks. This library is intended to be used with PJRC's Arduino Time library.

The DS3232RTC library also implements functions to support the additional features of the DS3232 and DS3231. The DS3232 has the same features as the DS3231, but the DS3232 also has these extra features:

• Battery-backed SRAM
• Battery-backed 32kHz output (BB32kHz bit in Control/Status register 0x0F)
• Adjustable temperature sensor sample rate (CRATE1:0 bits in the Control/Status register).

Examples

The following example sketches are included with the DS3232RTC library:

• TimeRTC: A simple example to display the time and date.
• SetSerial: Set the RTC's date and time from the Arduino serial monitor. Displays date, time and temperature.
• 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 for more information.

Usage notes

When using the DS3232RTC library, the user is responsible for ensuring that reads and writes do not exceed the device's address space (0x00-0x12 for DS3231, 0x00-0xFF for DS3232); no bounds checking is done by the library.

Enumerations

ALARM_TYPES_t

Description

Symbolic names used with the setAlarm() function (described below).

Values for Alarm 1

• ALM1_EVERY_SECOND -- causes an alarm once per second.
• ALM1_MATCH_SECONDS -- causes an alarm when the seconds match (i.e. once per minute).
• ALM1_MATCH_MINUTES -- causes an alarm when the minutes and seconds match.
• ALM1_MATCH_HOURS -- causes an alarm when the hours and minutes and seconds match.
• ALM1_MATCH_DATE -- causes an alarm when the date of the month and hours and minutes and seconds match.
• ALM1_MATCH_DAY -- causes an alarm when the day of the week and hours and minutes and seconds match.

Values for Alarm 2

• ALM2_EVERY_MINUTE -- causes an alarm once per minute.
• ALM2_MATCH_MINUTES -- causes an alarm when the minutes match (i.e. once per hour).
• ALM2_MATCH_HOURS -- causes an alarm when the hours and minutes match.
• ALM2_MATCH_DATE -- causes an alarm when the date of the month and hours and minutes match.
• ALM2_MATCH_DAY -- causes an alarm when the day of the week and hours and minutes match.

ALARM_NBR_t

Description

Symbolic names used with alarm functions.

Values

• ALARM_1
• ALARM_2

SQWAVE_FREQS_t

Description

Symbolic names used with the squareWave() function (described below).

Values

• SQWAVE_NONE
• SQWAVE_1_HZ
• SQWAVE_1024_HZ
• SQWAVE_4096_HZ
• SQWAVE_8192_HZ

Constructor

DS3232RTC(TwoWire& wire)

Description

Instantiates a DS3232RTC object.

Syntax

DS3232RTC myRTC(wire);

Parameters

wire: An optional parameter to specify which I2C bus to use. If omitted, defaults to Wire. (TwoWire&).

Returns

None.

Example

DS3232RTC myRTC;          // to use Wire
// or
DS3232RTC myRTC(Wire1);   // to use Wire1

Initialization function

begin()

Description

Initializes the I2C bus. Calls Wire.begin().

Syntax

begin();

Parameters

None.

Returns

None.

Example

DS3232RTC myRTC;
void setup() {
    myRTC.begin();
}

Functions for setting and reading the time

get()

Description

Reads the current date and time from the RTC and returns it as a time_t value. Returns zero if an I2C error occurs (RTC not present, etc.).

Syntax

myRTC.get();

Parameters

None.

Returns

Current date and time (time_t)

Example

time_t myTime = myRTC.get();

set(time_t t)

Description

Sets the RTC date and time to the given time_t value. Clears the oscillator stop flag (OSF) bit in the control/status register. See the oscStopped() function and also the DS323x datasheet for more information on the OSF bit.

Syntax

myRTC.set(t);

Parameters

t: The date and time to set the RTC to (time_t)

Returns

I2C status (uint8_t). Returns zero if successful.

Example

// this example first sets the system time (maintained by the Time library) to
// a hard-coded date and time, and then sets the RTC from the system time.
// the setTime() function is part of the Time library.
setTime(23, 31, 30, 13, 2, 2009);   // set the system time to 23h31m30s on 13Feb2009
myRTC.set(now());                   // set the RTC from the system time

read(tmElements_t &tm)

Description

Reads the current date and time from the RTC and returns it as a tmElements_t structure. See the Arduino Time Library for details on the tmElements_t structure.

Syntax

myRTC.read(tm);

Parameters

tm: Address of a tmElements_t structure to which the date and time are returned.

Returns

I2C status (uint8_t). Returns zero if successful. The date and time read from the RTC are returned to the tm parameter.

Example

tmElements_t tm;
myRTC.read(tm);
Serial.print(tm.Hour, DEC);
Serial.print(':');
Serial.print(tm.Minute,DEC);
Serial.print(':');
Serial.println(tm.Second,DEC);

write(tmElements_t &tm)

Description

Sets the RTC to the date and time given by a tmElements_t structure. Clears the oscillator stop flag (OSF) bit in the control/status register. See the oscStopped() function and also the DS323x datasheet for more information on the OSF bit.

Syntax

myRTC.write(tm);

Parameters

tm: Address of a tmElements_t structure used to set the date and time.

Returns

I2C status (uint8_t). Returns zero if successful.

Example

tmElements_t tm;
tm.Hour = 23;             // set the tm structure to 23h31m30s on 13Feb2009
tm.Minute = 31;
tm.Second = 30;
tm.Day = 13;
tm.Month = 2;
tm.Year = 2009 - 1970;    // tmElements_t.Year is the offset from 1970
myRTC.write(tm);          // set the RTC from the tm structure

Alarm functions

The DS3231 and DS3232 have two alarms. Alarm1 can be set to seconds precision; Alarm2 can only be set to minutes precision.

setAlarm(ALARM_TYPES_t alarmType, uint8_t seconds, uint8_t minutes, uint8_t hours, uint8_t daydate)

Description

Set an alarm time. Sets the alarm registers only. To c