DS1374 RTC Arduino Library

The DS1374RTC is a standalone Arduino library that allows setup and use of the DS1374 Real-time Clock (RTC) IC from Maxim. It is based on both the Arduino Time library and also the DS1307RTC library. The latest version is on our GitHub Repository here.

The DS1374 is similar to the DS1307 in that they share the same i2c address of 0x68 and also a similar register structure. In fact you can run the DS1307 code and it will appear to work though the time will do some strange jumps (which can be quite amusing). However, the ds1374 is what is known as a binary counter and the ds1307 is a BCD counter. A BCD counter encodes a 0 – 9 number in 4-bits, so an 8-bit register holds 2 encoded numbers. With a binary counter there is no encoding, a register simply increments the binary value once a second.

Alarm #

Aside from being a being a binary counter instead of the more common BCD counter, the ds1374 has an Alarm function and an Alarm output. The Alarm output is an active low I/O line that can be set to pulse low when the the Alarm goes off.

Time Structures #

The ds1374RTC makes use of the Arduino Time library. This implements some convenient structures to represent time and conversions between time formats. Two key structures that the ds1374RTC library uses are:

tmElements_t is a structure that allows convenient access to the familiar elements of time directly like hours, minutes and seconds.

time_t is a standard C time format defined as “time since the epoch type” which in English means that it is no more than a really big, single number that was started at zero on 00:00 Jan 1st 1970 and gives the count the seconds since then.

Overloaded functions #

The ds1374RTC makes use of these two time formats and implements them using what is known as function overloading. This has nothing to do with lifting boxes that are too heavy or manual handling training, but refers instead to one of my favourite C++ features, which in essence allows you to use the same function name for multiple functions.

For example, we could create two functions like this:

setTimeElements(tmElements_t tm);
setTimeType(time_t time);

but in C++ we have an alternative that we can use:

setTime(tmElements_t tm);
setTime(time_t time);

In the second example, both functions have the same name, but take slightly different parameters. When you compile and run the code the compiler works out which function it should actually call and generates the correct code. Much easier and cuts down on the number of functions you have to remember.

Functions #

setConfig – sets up the behaviour of the RTC. The routine takes the RTCConfig_t parameter which is defined as follows:

typedef struct {
   bool disableOsc;        // Enable/Disable the RTC Oscillator
   bool enableCTR;         // Enable/Disable the Watchdog or Alarm Counters
   eCTRType_t CTRType;     // Select either the Watchdog or the Alarm as the Counter
   bool enableSQW;         // Enable/Disable the square wave output
   eWDTOutput_t WDToutput; // Select where the reset pulse goes when the WDT expires
   eSQWRate_t SQWRate;     // Selects the frequency of the square wave output
   bool enableAlarmInt;    // Enable/Disable the Alarm for setting the INT pin when it expires
}RTCConfig_t;

It is worth referring to the data sheet for the exact meaning of all the options which can be quite involved. For example to setup the Alarm to output a pulse on the /INT pin of the RTC use the following given in pseudo-code:

disableOsc = false     // Enable/Disable the RTC OScillator
enableCTR = true       // Enable/Disable the Watchdog or Alarm Counters
CTRType = eALARM       // Select either the Watchdog or the Alarm as the Counter
enableSQW = false      // Enable/Disable the square wave output
WDToutput = eINT_PIN   // Select where the reset pulse goes when the WDT expires
SQWRate = e1Hz         // Selects the frequency of the square wave output
enableAlarmInt = true  // Enable/Disable the Alarm for setting the INT pin when it expires

setAlarm – sets the Alarm time which is in essence a countdown timer. What happens when the Alarm expires is determined by the setup of setConfig.
readAlarm – read the Alarm time.
setTime – sets the clock to the desired time.
readTime – not surprisingly reads the current time.
chipPresent  – verifies that the chip is present on the i2c and is responding.