DS1337 Real-Time Clock

[Anobium]

The DS1337 Real-Time Clock

The DS1337.h include file provides both high- and low-level support for the DS1337 real-time clock chip, two alarms and two ports (One as an interrupt and one as SQW or interrupt).

The DS1337 serial real-time clock is a low-power clock/calendar with two programmable time-of-day alarms and a programmable square-wave output. Address and data are transferred serially through an I2C bus. The clock/calendar provides seconds, minutes, hours, day, date, month, and year information.
The date at the end of the month is automatically adjusted for months with fewer than 31 days, including corrections for leap year. The clock operates in either the 24-hour or 12-hour format with AM/PM indicator.

Insert the following directive in your code to make these new commands available:
#include <ds1337.h></ds1337.h>

Here follows a list of the commands..

DS1337_EnableOscillator(flag)
enables the clock when flag is TRUE,
disables the clock when flag is FALSE

DS1337_OscillatorStopFlagStatus
A function that returns the status of the Oscillator.

DS1337_ClearOscillatorStopFlag
A method to clear the Oscillator stop flag.  To be  used after a power failure.

DS1337_ResetClock
resets clock completely to manufacturer’s original condition,
time to 00:00:00, day of the week to 01, date to 01/01/00,
also sets 24-hour mode and enables the clock.

DS1337_SetClock(hour, minute, second, DOW, date, month, year)
sets the entire clock: hours, minutes, seconds, day of week, date, month, year.
there is no error detection for out-of-range dates, (e.g., April 31)
also sets 24-hour mode and enables the clock.

DS1337_SetTime(hour, minute, second)
sets the time only: hours, minutes, seconds,.
also sets 24-hour mode and enables the clock.

DS1337_SetDate(dayoftheweek, date, month, year)
sets the date only: date, month, year,
there is no error detection for out-of-range dates, (e.g., April 31)

DS1337_ReadClock(hour, minute, second, flag, DOW, date, month, year)
reads the entire clock: hours, minutes, seconds, flag, day of week, date, month, year
flag = FALSE means a.m.,
flag = TRUE means p.m.

DS1337_ReadTime(hour, minute, second, flag)
reads the time only: hours, minutes, seconds, a.m. or p.m.,
flag = FALSE means a.m.,
flag = TRUE means p.m.

DS1337_ReadDate(date, month, year)
reads the date only: date, month, year

DS1337_SetHourMode(12|24)
sets the hour mode,
12 = 12-hour
24 = 24-hour
any other value defaults to 24-hour mode

DS1337_ReadHourMode(value)
returns the current hour mode,

DS1337_SetSQW(rate)
sets the square wave output pin mode:
    0 = disable square wave output
    1 = 1 Hz output
    4 = 4096 Hz
    8 = 8192 Hz
    32 = 32768 Hz,
    any other value defaults to 1 Hz

DS1337_EnableSQW
sets the square wave output pin mode to on

DS1337_DisableSQW
sets the square wave output pin mode to off

DS1337_SetControl (MFP_Value)
Sets Control address status to the value of the variable MFP_Value.  The control - rtcc control register is at address 0xOE. Direct access to the control register permits reading and writing of the controls. Set  bits usage as specified in the datasheet.

DS1337_ReadControl
This function returns the current value of the Control address.  See DS1337_SetControl(for usage.

DS1337_SetControlStatus (MFP_Value)
Sets Control Status address status to the value of the variable MFP_Value.  The control - rtcc control register is at address 0xOE. Direct access to the control register permits reading and writing of the controls. Set  bits usage as specified in the datasheet.

DS1337_ReadControlStatus
This function returns the current value of the Control Status  address.  See DS1337_SetControl(for usage.

DS1337_SetAlarm1 (Hour, Min, Sec, DOW, Date )
sets the alarm: hours, minutes, seconds, day of week, date. DOW or Date must BE 0. When DOW is non zero then the alarm if weekly, when Date is non zero then the alarm is monthly.
There is no error detection for out-of-range dates, (e.g., April 31)
also sets 24-hour mode.

DS1337_SetAlarmMask1 (alarmAssertionMatch)
sets the alarm where Value can be any of the following.

- DS1337_Alarm1Assertion_EverySecond                            = 0x0F
- DS1337_Alarm1Assertion_Seconds                                   = 0x0E
- DS1337_Alarm1Assertion_MinutesSeconds                       = 0x0C
- DS1337_Alarm1Assertion_HoursMinutesSeconds              = 0x08
- DS1337_Alarm1Assertion_DateHoursMinutesSeconds      = 0x00
- DS1337_Alarm1Assertion_DayHoursMinutesSeconds       = 0x00

  A match of these assertions will raise the alarm.


DS1337_ReadAlarm1 (Hour, Min, Sec, DOW, Date )
Returns the current settings for a specific alarm.

DS1337_ClearAlarm1
Clears a specific alarm after an alarm assertion.

DS1337_EnableAlarm1Interrupt
Enables the SQW output to be used to raise an external interrupt

DS1337_DisableAlarm1Interrupt
Disables the SQW output to be used to raise an external interrupt

DS1337_AlarmStatus1
This is a function. Returns a specific alarm status.
FALSE means the specific alarm has not met the assertion criteria
TRUE means the specific alarm has met the assertion criteria

DS1337_DisableAlarm1
Disables the alarm.

DS1337_SetAlarm2 (Hour, Min,  DOW, Date )
sets the alarm: hours, minutes,  day of week, date. DOW or Date must BE 0. When DOW is non zero then the alarm if weekly, when Date is non zero then the alarm is monthly.
There is no error detection for out-of-range dates, (e.g., April 31)
also sets 24-hour mode.

DS1337_SetAlarmMask1 (alarmAssertionMatch)
sets the alarm where Value can be any of the following.

- DS1337_Alarm2Assertion_EveryMinute                        = 0x07
- DS1337_Alarm2Assertion_Minutes                            = 0x06
- DS1337_Alarm2Assertion_HoursMinutes                       = 0x04
- DS1337_Alarm2Assertion_DateHoursMinutes                   = 0x00
- DS1337_Alarm2Assertion_DayHoursMinutesSeconds     = 0x00

  A match of these assertions will raise the alarm.

DS1337_ReadAlarm2 (Hour, Min, DOW, Date )
Returns the current settings for a specific alarm.

DS1337_ClearAlarm2
Clears a specific alarm after an alarm assertion.

DS1337_EnableAlarm2Interrupt
Enables the SQW output to be used to raise an external interrupt

DS1337_DisableAlarm2Interrupt
Disables the SQW output to be used to raise an external interrupt

DS1337_AlarmStatus2
This is a function. Returns a specific alarm status.
FALSE means the specific alarm has not met the assertion criteria
TRUE means the specific alarm has met the assertion criteria

DS1337_DisableAlarm2
Disables the alarm.

DS1337_ReadRegister ( in DS_Value )
This is a function. Returns the value of the specific register as specified in DS_Value.

DS1337_WriteRegister ( in DS_Value, in DS_Temp )
This method set the specific register as specified in DS_Value to the value specified in DS_Temp

Version 1.01

[Anobium]

The driver code can be found here: download

Documentation can found here: download

Example code for a Serial Terminal can be found here: download

Example code for an LCD can be found here: download