uRTCLib https://github.com/Naguissa/uRTCLib

Loading...
Searching...
No Matches
Public Member Functions | List of all members
uRTCLib Class Reference

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: URTCLIB_ALARM_1 URTCLIB_ALARM_2

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: URTCLIB_ALARM_1 URTCLIB_ALARM_2

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

## ◆ alarmDisable()

bool uRTCLib::alarmDisable | ( | const uint8_t | alarm | ) |

Disables an alarm.

Parameters

  alarm | Alarm number: URTCLIB_ALARM_1 URTCLIB_ALARM_2

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: URTCLIB_ALARM_1 URTCLIB_ALARM_2

Returns
  Current stored hour. 0b11111111 means error.

## ◆ alarmMinute()

uint8_t uRTCLib::alarmMinute | ( | const uint8_t | alarm | ) |

Returns actual alarm minute.

Parameters

  alarm | Alarm number: URTCLIB_ALARM_1 URTCLIB_ALARM_2

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: URTCLIB_ALARM_1 URTCLIB_ALARM_2

Returns
  Current stored mode. 0b11111111 means error.
  - 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
  - ...or...
  - 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

## ◆ alarmSecond()

uint8_t uRTCLib::alarmSecond | ( | const uint8_t | alarm | ) |

Returns actual alarm second.

Parameters

  alarm | Alarm number: URTCLIB_ALARM_1 URTCLIB_ALARM_2

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: URTCLIB_ALARM_1 URTCLIB_ALARM_2 URTCLIB_ALARM_ANY

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
  - URTCLIB_WEEKDAY_SUNDAY
  - URTCLIB_WEEKDAY_MONDAY
  - URTCLIB_WEEKDAY_TUESDAY
  - URTCLIB_WEEKDAY_WEDNESDAY
  - URTCLIB_WEEKDAY_THURSDAY
  - URTCLIB_WEEKDAY_FRIDAY
  - URTCLIB_WEEKDAY_SATURDAY

## ◆ 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
  - URTCLIB_MODEL_DS1307
  - URTCLIB_MODEL_DS3231
  - URTCLIB_MODEL_DS3232

## ◆ 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 URTCLIB_MODEL_DS1307 URTCLIB_MODEL_DS3231 URTCLIB_MODEL_DS3232

## ◆ 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:
  - URTCLIB_SQWG_OFF_0
  - URTCLIB_SQWG_OFF_1
  - URTCLIB_SQWG_1H
  - URTCLIB_SQWG_1024H
  - URTCLIB_SQWG_4096H
  - URTCLIB_SQWG_8192H
  - URTCLIB_SQWG_32768H

## ◆ sqwgSetMode()

bool uRTCLib::sqwgSetMode | ( | const uint8_t | mode | ) |

Gets current SQWG mode.

Changes SQWG mode, including turning it off.

Returns
  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

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:

- uRTCLib.h
- uRTCLib.cpp