Updated to latest release level. This posting matches the released code and the attached documentation. See here for example code. The driver now supports Software I2C and Hardware I2C.
The DS3231.h include file provides both high- and low-level support for the DS3231 real-time clock chip. The DS3231 is a low-cost, extremely accurate I²C real-time clock (RTC) with an integrated temperature-compensated crystal oscillator (TCXO) and crystal. The device incorporates a battery input, and maintains accurate timekeeping when main power to the device is interrupted.
The RTC maintains 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 an active-low AM/PM indicator. Two programmable time-of-day alarms and a programmable square-wave output are provided. Address and data are transferred serially through an I²C bidirectional bus.
Insert the following directive in your code to make these new commands available:
~~~~
include <DS3231.h>
~~~~~
Recognition goes to the following:
Initial work created myself in Oct 2013 for the DS1307, adapted works by Thomas Henry, May 26, 2014 for DS1307, adapted by myself to add new functionality to comply with DS3231 datasheet - Jan 4 2015,
The latest file is here. The latest version support Hardware i2c and software (bit banging) i2c.
Here follows a list of the commands. See the attachment also and the include file.
Here follows a list of the commands.
DS3231_EnableOscillator(flag)
enables the clock when flag is TRUE,
disables the clock when flag is FALSE
DS3231_OscillatorStopFlagStatus
A function that returns the status of the Oscillator.
DS3231_ClearOscillatorStopFlag
A method to clear the Oscillator stop flag. To be used after a power failure.
DS3231_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.
DS3231_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.
DS3231_SetTime(hour, minute, second)
sets the time only: hours, minutes, seconds,.
also sets 24-hour mode and enables the clock.
DS3231_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)
DS3231_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.
DS3231_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.
DS3231_ReadDate(date, month, year)
reads the date only: date, month, year
DS3231_SetHourMode(12|24)
sets the hour mode,
12 = 12-hour
24 = 24-hour
any other value defaults to 24-hour mode
DS3231_ReadHourMode(value)
returns the current hour mode,
DS3231_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
DS3231_EnableSQW
sets the square wave output pin mode to on
DS3231_DisableSQW
sets the square wave output pin mode to off
DS3231_SetSQWInterruptControl(flag)
enables the SQW output when flag is TRUE,
disables the SQW output when flag is FALSE
DS3231_EnableSQWInterruptControl
Enables the SQW
DS3231_DisableSQWInterruptControl
Disables the SQW
DS3231_Set32kHz(flag)
enables the Set32kHz output when flag is TRUE,
disables the Set32kHz output when flag is FALSE
DS3231_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.
DS3231_ReadControl
This function returns the current value of the Control address. See DS3231_SetControl(for usage.
DS3231_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.
DS3231_ReadControlStatus
This function returns the current value of the Control Status address. See DS3231_SetControl(for usage.
DS3231_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.
DS3231_SetAlarmMask1 (alarmAssertionMatch)
sets the alarm where Value can be any of the following.
DS3231_ReadAlarm1 (Hour, Min, Sec, DOW, Date )
Returns the current settings for a specific alarm.
DS3231_ClearAlarm1
Clears a specific alarm after an alarm assertion.
DS3231_EnableAlarm1Interrupt
Enables the SQW output to be used to raise an external interrupt
DS3231_DisableAlarm1Interrupt
Disables the SQW output to be used to raise an external interrupt
DS3231_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
DS3231_DisableAlarm1
Disables the alarm.
DS3231_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.
DS3231_SetAlarmMask1 (alarmAssertionMatch)
sets the alarm where Value can be any of the following.
DS3231_ReadAlarm2 (Hour, Min, DOW, Date )
Returns the current settings for a specific alarm.
DS3231_ClearAlarm2
Clears a specific alarm after an alarm assertion.
DS3231_EnableAlarm2Interrupt
Enables the SQW output to be used to raise an external interrupt
DS3231_DisableAlarm2Interrupt
Disables the SQW output to be used to raise an external interrupt
DS3231_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
DS3231_DisableAlarm2
Disables the alarm.
DS3231_ReadRegister ( in DS_Value )
This is a function. Returns the value of the specific register as specified in DS_Value.
DS3231_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
Attached is a demo of a fully featured calendar/clock for a LCD. This code has been adapted from the previous clock demonstration code but adapted for the DS3231.
The code is extensively commented and includes operating instructions as well. It only needs two pushbuttons to get all the options which will make it great for chips with fewer pins.
The example includes two alarms and is extensively documented for the use of the output ports and the alarms.
Attached is a demo of a fully featured calendar/clock for ANSI compliant Serial Terminal. This code has been adapted from the previous clock demonstration code but adapted for the DS3231.
The code is extensively commented and includes operating instructions as well. It only needs two pushbuttons to get all the options which will make it great for chips with fewer pins.
The example includes two alarms and is extensively documented for the use of the output ports and the alarms.
This example uses the Serial port for output. I used Putty.exe to test the solution as Putty is ANSI compliant.
I now have the correct batteries. When I checked the battery I initially used (a non-rechargeable) it is a tad swollen! That battery is is the trash already!!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
DS3231 Real-Time Clock
Updated to latest release level. This posting matches the released code and the attached documentation. See here for example code. The driver now supports Software I2C and Hardware I2C.
The DS3231.h include file provides both high- and low-level support for the DS3231 real-time clock chip. The DS3231 is a low-cost, extremely accurate I²C real-time clock (RTC) with an integrated temperature-compensated crystal oscillator (TCXO) and crystal. The device incorporates a battery input, and maintains accurate timekeeping when main power to the device is interrupted.
The RTC maintains 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 an active-low AM/PM indicator. Two programmable time-of-day alarms and a programmable square-wave output are provided. Address and data are transferred serially through an I²C bidirectional bus.
Insert the following directive in your code to make these new commands available:
~~~~
include <DS3231.h>
~~~~~
Recognition goes to the following:
Initial work created myself in Oct 2013 for the DS1307, adapted works by Thomas Henry, May 26, 2014 for DS1307, adapted by myself to add new functionality to comply with DS3231 datasheet - Jan 4 2015,
The latest file is here. The latest version support Hardware i2c and software (bit banging) i2c.
Here follows a list of the commands. See the attachment also and the include file.
Here follows a list of the commands.
DS3231_EnableOscillator(flag)
enables the clock when flag is TRUE,
disables the clock when flag is FALSE
DS3231_OscillatorStopFlagStatus
A function that returns the status of the Oscillator.
DS3231_ClearOscillatorStopFlag
A method to clear the Oscillator stop flag. To be used after a power failure.
DS3231_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.
DS3231_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.
DS3231_SetTime(hour, minute, second)
sets the time only: hours, minutes, seconds,.
also sets 24-hour mode and enables the clock.
DS3231_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)
DS3231_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.
DS3231_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.
DS3231_ReadDate(date, month, year)
reads the date only: date, month, year
DS3231_SetHourMode(12|24)
sets the hour mode,
12 = 12-hour
24 = 24-hour
any other value defaults to 24-hour mode
DS3231_ReadHourMode(value)
returns the current hour mode,
DS3231_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
DS3231_EnableSQW
sets the square wave output pin mode to on
DS3231_DisableSQW
sets the square wave output pin mode to off
DS3231_SetSQWInterruptControl(flag)
enables the SQW output when flag is TRUE,
disables the SQW output when flag is FALSE
DS3231_EnableSQWInterruptControl
Enables the SQW
DS3231_DisableSQWInterruptControl
Disables the SQW
DS3231_Set32kHz(flag)
enables the Set32kHz output when flag is TRUE,
disables the Set32kHz output when flag is FALSE
DS3231_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.
DS3231_ReadControl
This function returns the current value of the Control address. See DS3231_SetControl(for usage.
DS3231_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.
DS3231_ReadControlStatus
This function returns the current value of the Control Status address. See DS3231_SetControl(for usage.
DS3231_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.
DS3231_SetAlarmMask1 (alarmAssertionMatch)
sets the alarm where Value can be any of the following.
-DS3231_Alarm1Assertion_EverySecond = 0x0F
-DS3231_Alarm1Assertion_Seconds = 0x0E
-DS3231_Alarm1Assertion_MinutesSeconds = 0x0C
-DS3231_Alarm1Assertion_HoursMinutesSeconds = 0x08
-DS3231_Alarm1Assertion_DateHoursMinutesSeconds = 0x00
-DS3231_Alarm1Assertion_DayHoursMinutesSeconds = 0x00
A match of these assertions will raise the alarm.
DS3231_ReadAlarm1 (Hour, Min, Sec, DOW, Date )
Returns the current settings for a specific alarm.
DS3231_ClearAlarm1
Clears a specific alarm after an alarm assertion.
DS3231_EnableAlarm1Interrupt
Enables the SQW output to be used to raise an external interrupt
DS3231_DisableAlarm1Interrupt
Disables the SQW output to be used to raise an external interrupt
DS3231_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
DS3231_DisableAlarm1
Disables the alarm.
DS3231_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.
DS3231_SetAlarmMask1 (alarmAssertionMatch)
sets the alarm where Value can be any of the following.
-DS3231_Alarm2Assertion_EveryMinute = 0x07
-DS3231_Alarm2Assertion_Minutes = 0x06
-DS3231_Alarm2Assertion_HoursMinutes = 0x04
-DS3231_Alarm2Assertion_DateHoursMinutes = 0x00
-DS3231_Alarm2Assertion_DayHoursMinutesSeconds = 0x00
A match of these assertions will raise the alarm.
DS3231_ReadAlarm2 (Hour, Min, DOW, Date )
Returns the current settings for a specific alarm.
DS3231_ClearAlarm2
Clears a specific alarm after an alarm assertion.
DS3231_EnableAlarm2Interrupt
Enables the SQW output to be used to raise an external interrupt
DS3231_DisableAlarm2Interrupt
Disables the SQW output to be used to raise an external interrupt
DS3231_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
DS3231_DisableAlarm2
Disables the alarm.
DS3231_ReadRegister ( in DS_Value )
This is a function. Returns the value of the specific register as specified in DS_Value.
DS3231_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.02
Last edit: Anobium 2015-01-12
Attached is a demo of a fully featured calendar/clock for a LCD. This code has been adapted from the previous clock demonstration code but adapted for the DS3231.
The code is extensively commented and includes operating instructions as well. It only needs two pushbuttons to get all the options which will make it great for chips with fewer pins.
The example includes two alarms and is extensively documented for the use of the output ports and the alarms.
This example uses the LCD for output.
Last edit: Anobium 2015-01-10
Attached is a demo of a fully featured calendar/clock for ANSI compliant Serial Terminal. This code has been adapted from the previous clock demonstration code but adapted for the DS3231.
The code is extensively commented and includes operating instructions as well. It only needs two pushbuttons to get all the options which will make it great for chips with fewer pins.
The example includes two alarms and is extensively documented for the use of the output ports and the alarms.
This example uses the Serial port for output. I used Putty.exe to test the solution as Putty is ANSI compliant.
Last edit: Anobium 2015-01-10
This is a must read if you are getting a DS3231 device off Ebay.
See http://woodsgood.ca/projects/2014/10/21/the-right-rtc-battery/
I now have the correct batteries. When I checked the battery I initially used (a non-rechargeable) it is a tad swollen! That battery is is the trash already!!
The driver now supports Software I2C and Hardware I2C.
See here for example code.