DS1307, DS3231 and DS3232 RTCs basic library. More...

Public Member Functions
	uRTCLib ()
	Constructor.

	uRTCLib (const int)
	Constructor.

	uRTCLib (const int, const uint8_t)
	Constructor.

bool	refresh ()
	Refresh data from HW RTC.

uint8_t	second ()
	Returns actual second.

uint8_t	minute ()
	Returns actual minute.

uint8_t	hour ()
	Returns actual hour.

uint8_t	hourModeAndAmPm ()
	Returns whether clock is in 12 or 24 hour mode and AM or PM if in 12 hour mode 0 = 24 hour mode (0-23 hours) 1 = 12 hour mode AM hours (1-12 hours) 2 = 12 hour mode PM hours (1-12 hours)

uint8_t	day ()
	Returns actual day.

uint8_t	month ()
	Returns actual month.

uint8_t	year ()
	Returns actual year.

uint8_t	dayOfWeek ()
	Returns actual Day Of Week.

int16_t	temp ()
	Returns actual temperature.

void	set (const uint8_t, const uint8_t, const uint8_t, const uint8_t, const uint8_t, const uint8_t, const uint8_t)
	Sets RTC datetime data.

void	set_12hour_mode (const bool)
	Set clock in 12 or 24 hour mode 12 hour mode has 1-12 hours and AM or PM flag 24 hour mode has 0-23 hours get current clock mode and AM or PM flag using hourModeAndAmPm()

void	set_rtc_address (const int)
	Sets RTC i2 addres.

void	set_model (const uint8_t)
	Sets RTC Model.

uint8_t	model ()
	Gets RTC Model.

bool	getEOSCFlag ()
	Returns Enable Oscillator Flag.

bool	lostPower ()
	Returns lost power VBAT staus.

void	lostPowerClear ()
	Clears lost power VBAT staus.

bool	enableBattery ()
	Enable VBAT operation when VCC power is lost.

bool	disableBattery ()
	Disable VBAT operation when VCC power is lost.

bool	alarmSet (const uint8_t, const uint8_t, const uint8_t, const uint8_t, const uint8_t)
	Sets any alarm.

bool	alarmDisable (const uint8_t)
	Disables an alarm.

bool	alarmClearFlag (const uint8_t)
	Clears an alarm flag.

uint8_t	alarmMode (const uint8_t)
	Returns actual alarm mode.

uint8_t	alarmSecond (const uint8_t)
	Returns actual alarm second.

uint8_t	alarmMinute (const uint8_t)
	Returns actual alarm minute.

uint8_t	alarmHour (const uint8_t)
	Returns actual alarm hour.

uint8_t	alarmDayDow (const uint8_t)
	Returns actual alarm day or DOW.

bool	alarmTriggered (const uint8_t)
	Checks if any alarm has been triggered.

uint8_t	sqwgMode ()
	Changes SQWG mode, including turning it off.

bool	sqwgSetMode (const uint8_t)
	Gets current SQWG mode.

byte	ramRead (const uint8_t)
	Reads a byte from RTC RAM.

bool	ramWrite (const uint8_t, byte)
	Writes a byte to RTC RAM.

int8_t	agingGet ()
	Reads actual aging value on the RTC.

bool	agingSet (int8_t)
	Sets aging value on the RTC.

bool	enable32KOut ()
	Enables 32K pin output.

bool	disable32KOut ()
	Disable 32K pin output.

bool	status32KOut ()
	Checks 32K pin output status.

Detailed Description

DS1307, DS3231 and DS3232 RTCs basic library.

Really tiny library to basic RTC functionality on Arduino.

Supported features:

SQuare Wave Generator
Fixed output pin for DS1307
RAM for DS1307 and DS3232
temperature sensor for DS3231 and DS3232
Alarms (1 and 2) for DS3231 and DS3232
Power failure check and clear

See uEEPROMLib for EEPROM support, https://github.com/Naguissa/uEEPROMLib

Note: For AtTiny you need TinyWireM library from Adafruit installed (available on library manager).

I2C locked in unknown state

If uC crashes and I2C communication is locked in a unknown state you have a procedure to unlock it. It's not implemented in this library but you can find an explanation and a PIC implementation thanks to @rtek1000 in #42 : https://github.com/Naguissa/uRTCLib/issues/42

Constructor & Destructor Documentation

◆ uRTCLib() [1/2]

uRTCLib::uRTCLib ( const int rtc_address )

Constructor.

Parameters

rtc_address I2C address of RTC

◆ uRTCLib() [2/2]

uRTCLib::uRTCLib	(	const int	rtc_address,
		const uint8_t	model
	)

Constructor.

Parameters

rtc_address	I2C address of RTC
model	RTC model: URTCLIB_MODEL_DS1307 URTCLIB_MODEL_DS3231 URTCLIB_MODEL_DS3232

Member Function Documentation

◆ agingGet()

int8_t uRTCLib::agingGet ( )

Reads actual aging value on the RTC.

Returns: Aging register value on RTC, 2-complement recalculated (use as regular int8_t)

◆ agingSet()

bool uRTCLib::agingSet ( int8_t val )

Sets aging value on the RTC.

Parameters

val	new value (use as regular int8_t, 2-complement conversion is done internally)

Returns: True when executed, false if RTC doesn't support it.

◆ alarmClearFlag()

bool uRTCLib::alarmClearFlag ( const uint8_t alarm )

Clears an alarm flag.

Parameters

alarm

Alarm number:

Returns: false in case of not supported (DS1307) or wrong parameters

◆ alarmDayDow()

uint8_t uRTCLib::alarmDayDow ( const uint8_t alarm )

Returns actual alarm day or DOW.

Parameters

alarm

Alarm number:

Returns: Current stored day or dow. 0b11111111 means error.

◆ alarmDisable()

bool uRTCLib::alarmDisable ( const uint8_t alarm )

Disables an alarm.

Parameters

alarm

Alarm number:

Returns: false in case of not supported (DS1307) or wrong parameters

◆ alarmHour()

uint8_t uRTCLib::alarmHour ( const uint8_t alarm )

Returns actual alarm hour.

Parameters

alarm

Alarm number:

Returns: Current stored hour. 0b11111111 means error.

◆ alarmMinute()

uint8_t uRTCLib::alarmMinute ( const uint8_t alarm )

Returns actual alarm minute.

Parameters

alarm

Alarm number:

Returns: Current stored minute. 0b11111111 means error.

◆ alarmMode()

uint8_t uRTCLib::alarmMode ( const uint8_t alarm )

Returns actual alarm mode.

See URTCLIB_ALARM_TYPE_X_YYYYY defines to see modes

Parameters

alarm

Alarm number:

Returns

Current stored mode. 0b11111111 means error.

◆ alarmSecond()

uint8_t uRTCLib::alarmSecond ( const uint8_t alarm )

Returns actual alarm second.

Parameters

alarm

Alarm number:

Returns: Current stored second. 0b11111111 means error.

◆ alarmSet()

bool uRTCLib::alarmSet	(	const uint8_t	type,
		const uint8_t	second,
		const uint8_t	minute,
		const uint8_t	hour,
		const uint8_t	day_dow
	)

Sets any alarm.

This method can also be used to disable an alarm, but it's better to use alarmDisable(const uint8_t alarm) to do so.

Parameters

type	Alarm type: URTCLIB_ALARM_TYPE_1_NONE URTCLIB_ALARM_TYPE_1_ALL_S URTCLIB_ALARM_TYPE_1_FIXED_S URTCLIB_ALARM_TYPE_1_FIXED_MS URTCLIB_ALARM_TYPE_1_FIXED_HMS URTCLIB_ALARM_TYPE_1_FIXED_DHMS URTCLIB_ALARM_TYPE_1_FIXED_DOWHMS URTCLIB_ALARM_TYPE_2_NONE URTCLIB_ALARM_TYPE_2_ALL_M URTCLIB_ALARM_TYPE_2_FIXED_M URTCLIB_ALARM_TYPE_2_FIXED_HM URTCLIB_ALARM_TYPE_2_FIXED_DHM URTCLIB_ALARM_TYPE_2_FIXED_DOWHM
second	second to set Alarm (ignored in Alarm 2)
minute	minute to set Alarm
hour	hour to set Alarm
day_dow	Day of the month or DOW to set Alarm, depending on alarm type

Returns: false in case of not supported (DS1307) or wrong parameters

◆ alarmTriggered()

bool uRTCLib::alarmTriggered ( const uint8_t alarm )

Checks if any alarm has been triggered.

NOTE: Alarm Flags A1F and A2F will be triggered whether or not Alarm Interrupt is Enabled A1IE and A2IE When the RTC register values match alarm register settings, the corresponding Alarm Flag ‘A1F’ or ‘A2F’ bit is set to logic 1. If using alarmTriggered function to check for alarm trigger, be sure to alarmMode function to see if alarm is enabled or not.

Parameters

alarm

Alarm number:

Returns: bool true or false

◆ day()

uint8_t uRTCLib::day ( )

Returns actual day.

Returns: Current stored day

◆ dayOfWeek()

uint8_t uRTCLib::dayOfWeek ( )

Returns actual Day Of Week.

Returns

Current stored Day Of Week

◆ disable32KOut()

bool uRTCLib::disable32KOut ( )

Disable 32K pin output.

Disables 32K pin output.

As DS1307 doen't have this functionality we map it to SqWG with 32K frequency

◆ disableBattery()

bool uRTCLib::disableBattery ( )

Disable VBAT operation when VCC power is lost.

Returns: True on success

◆ enable32KOut()

bool uRTCLib::enable32KOut ( )

Enables 32K pin output.

A Pull-Up resistor is required on the pin. As DS1307 doen't have this functionality we map it to SqWG with 32K frequency

◆ enableBattery()

bool uRTCLib::enableBattery ( )

Enable VBAT operation when VCC power is lost.

DS3231/DS3232 should enable the battery by default on first power-up using VCC, however this sometimes won't happen automatically, and therefore the Control Register needs to be forcefully overwritten to set EOSC to 0. The devices are usually shipped from China with EOSC set to 1 to save battery (even though they come with no battery included).

Cause of frustration for a lot of first time users of the device. i.e. Time is lost even though battery present.

Reference: https://forum.arduino.cc/index.php?topic=586520.msg3990086#msg3990086

Returns: True on success

◆ getEOSCFlag()

bool uRTCLib::getEOSCFlag ( )

Returns Enable Oscillator Flag.

Returns Enable Oscillator Flah.

DS3231 Control Register (0Eh) Bit 7: Enable Oscillator (EOSC) When set to logic 0, the oscillator is started. When set to logic 1, the oscillator is stopped when the DS3231 switches to VBAT. This bit is clear (logic 0) when power is first applied. When the DS3231 is powered by VCC, the oscillator is always on regardless of the status of the EOSC bit. When EOSC is disabled, all register data is static.

Returns: _eosc flag - 0 if set to enable OSC with VBAT if VCC is stopped

◆ hour()

uint8_t uRTCLib::hour ( )

Returns actual hour.

Returns: Current stored hour

◆ hourModeAndAmPm()

uint8_t uRTCLib::hourModeAndAmPm ( )

Returns whether clock is in 12 or 24 hour mode and AM or PM if in 12 hour mode 0 = 24 hour mode (0-23 hours) 1 = 12 hour mode AM hours (1-12 hours) 2 = 12 hour mode PM hours (1-12 hours)

Returns whether clock is in 12 or 24 hour mode with AM or PM if in 12 hour mode 0 = 24 hour mode (0-23 hours) 1 = 12 hour mode AM hours (1-12 hours) 2 = 12 hour mode PM hours (1-12 hours)

Returns: byte with value 0, 1 or 2

◆ lostPower()

bool uRTCLib::lostPower ( )

Returns lost power VBAT staus.

DS1307 has a 'CH' Clock Halt Bit in Register 00h.

On first application of power to the device the time and date registers are typically reset to 01/01/00 01 00:00:00 (MM/DD/YY DOW HH:MM:SS).

The CH bit in the seconds register will be set to a 1.

Others have a 'OSF' Oscillator Stop Flag in Register 0Fh

Returns: True if power was lost (both power sources, VCC and VBAT)

◆ lostPowerClear()

void uRTCLib::lostPowerClear ( )

Clears lost power VBAT staus.

DS1307 has a 'CH' Clock Halt Bit in Register 00h -> When cleared to 0, the oscillator is enabled and time starts incermenting

Others have a 'OSF' Oscillator Stop Flag in Register 0Fh

DS1307 has a 'CH' Clock Halt Bit in Register 00h -> When cleared to 0, the oscillator is enabled and the time starts to increase

Others have a 'OSF' Oscillator Stop Flag in Register 0Fh

◆ minute()

uint8_t uRTCLib::minute ( )

Returns actual minute.

Returns: Current stored minute

◆ model()

uint8_t uRTCLib::model ( )

Gets RTC Model.

Returns

RTC Model

◆ month()

uint8_t uRTCLib::month ( )

Returns actual month.

Returns: Current stored month

◆ ramRead()

byte uRTCLib::ramRead ( const uint8_t address )

Reads a byte from RTC RAM.

Parameters

address RAM Address

Returns: content of that position. If any error it will return always 0xFF;

◆ ramWrite()

bool uRTCLib::ramWrite	(	const uint8_t	address,
		byte	data
	)

Writes a byte to RTC RAM.

Parameters

address	RAM Address
data	Content to write on that position

Returns: true if correct

◆ refresh()

bool uRTCLib::refresh ( )

Refresh data from HW RTC.

Returns: False on error

◆ second()

uint8_t uRTCLib::second ( )

Returns actual second.

Returns: Current stored second

◆ set()

void uRTCLib::set	(	const uint8_t	second,
		const uint8_t	minute,
		const uint8_t	hour,
		const uint8_t	dayOfWeek,
		const uint8_t	dayOfMonth,
		const uint8_t	month,
		const uint8_t	year
	)

Sets RTC datetime data.

Parameters

second	second to set to HW RTC
minute	minute to set to HW RTC
hour	hour to set to HW RTC
dayOfWeek	day of week to set to HW RTC URTCLIB_WEEKDAY_SUNDAY URTCLIB_WEEKDAY_MONDAY URTCLIB_WEEKDAY_TUESDAY URTCLIB_WEEKDAY_WEDNESDAY URTCLIB_WEEKDAY_THURSDAY URTCLIB_WEEKDAY_FRIDAY URTCLIB_WEEKDAY_SATURDAY
dayOfMonth	day of month to set to HW RTC
month	month to set to HW RTC
year	year to set to HW RTC in last 2 digits mode. As RTCs only support 19xx and 20xx years (see datasheets), it's harcoded to 20xx.

◆ set_12hour_mode()

void uRTCLib::set_12hour_mode ( const bool twelveHrMode )

Set clock in 12 or 24 hour mode 12 hour mode has 1-12 hours and AM or PM flag 24 hour mode has 0-23 hours get current clock mode and AM or PM flag using hourModeAndAmPm()

Parameters

twelveHrMode true or false

◆ set_model()

void uRTCLib::set_model ( const uint8_t model )

Sets RTC Model.

Parameters

model

RTC Model

◆ set_rtc_address()

void uRTCLib::set_rtc_address ( const int addr )

Sets RTC i2 addres.

Parameters

addr	RTC i2C address

◆ sqwgMode()

uint8_t uRTCLib::sqwgMode ( )

Changes SQWG mode, including turning it off.

Gets current SQWG mode.

Parameters

mode	SQWG mode: URTCLIB_SQWG_OFF_0 URTCLIB_SQWG_OFF_1 URTCLIB_SQWG_1H URTCLIB_SQWG_1024H URTCLIB_SQWG_4096H URTCLIB_SQWG_8192H URTCLIB_SQWG_32768H

Returns

false in case of not supported (DS1307) or wrong parameters

SQWG mode:

◆ sqwgSetMode()

bool uRTCLib::sqwgSetMode ( const uint8_t mode )

Gets current SQWG mode.

Changes SQWG mode, including turning it off.

Returns

SQWG mode:

Parameters

mode	SQWG mode: URTCLIB_SQWG_OFF_0 URTCLIB_SQWG_OFF_1 URTCLIB_SQWG_1H URTCLIB_SQWG_1024H URTCLIB_SQWG_4096H URTCLIB_SQWG_8192H URTCLIB_SQWG_32768H

Returns: false in case of not supported (DS1307) or wrong parameters

◆ status32KOut()

bool uRTCLib::status32KOut ( )

Checks 32K pin output status.

As DS1307 doen't have this functionality we map it to SqWG with 32K frequency

◆ temp()

int16_t uRTCLib::temp ( )

Returns actual temperature.

Temperature is returned as degrees * 100; i.e.: 3050 is 30.50º

WARNING: DS1307 has no temperature register, so it always returns URTCLIB_TEMP_ERROR

Returns: Current stored temperature

◆ year()

uint8_t uRTCLib::year ( )

Returns actual year.

Returns: Current stored year

The documentation for this class was generated from the following files:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ uRTCLib() [1/2]

◆ uRTCLib() [2/2]

Member Function Documentation

◆ agingGet()

◆ agingSet()

◆ alarmClearFlag()

◆ alarmDayDow()

◆ alarmDisable()

◆ alarmHour()

◆ alarmMinute()

◆ alarmMode()

◆ alarmSecond()

◆ alarmSet()

◆ alarmTriggered()

◆ day()

◆ dayOfWeek()

◆ disable32KOut()

◆ disableBattery()

◆ enable32KOut()

◆ enableBattery()

◆ getEOSCFlag()

◆ hour()

◆ hourModeAndAmPm()

◆ lostPower()

◆ lostPowerClear()

◆ minute()

◆ model()

◆ month()

◆ ramRead()

◆ ramWrite()

◆ refresh()

◆ second()

◆ set()

◆ set_12hour_mode()

◆ set_model()

◆ set_rtc_address()

◆ sqwgMode()

◆ sqwgSetMode()

◆ status32KOut()

◆ temp()

◆ year()