MD_DS3231 Real Time Clock Library  1.3
Library to control DS3231 high precision clock with alarms
MD_DS3231.h File Reference

Main header file for the MD_DS3231 library. More...

#include <Arduino.h>
+ Include dependency graph for MD_DS3231.h:

Classes

class  MD_DS3231
 

Macros

#define ENABLE_12H   1
 Enable 12H (AMP/PM) support. More...
 
#define ENABLE_DOW   1
 Enable Day of Week vs Date support. More...
 
#define ENABLE_DYNAMIC_CENTURY   1
 Enable support for dynamic century. More...
 
#define ENABLE_RTC_INSTANCE   1
 Enable default RTC instance creation. More...
 
#define DS3231_RAM_MAX   19
 Total number of RAM registers that can be read from the device.
 

Enumerations

enum  codeRequest_t {
  DS3231_CLOCK_HALT, DS3231_SQW_ENABLE, DS3231_SQW_TYPE, DS3231_12H,
  DS3231_TCONV, DS3231_INT_ENABLE, DS3231_A1_INT_ENABLE, DS3231_A2_INT_ENABLE,
  DS3231_HALTED_FLAG, DS3231_32KHZ_ENABLE, DS3231_BUSY_FLAG, DS3231_A1_FLAG,
  DS3231_A2_FLAG, DS3231_AGING_OFFSET
}
 
enum  codeStatus_t {
  DS3231_ERROR, DS3231_ON, DS3231_OFF, DS3231_SQW_1HZ,
  DS3231_SQW_1KHZ, DS3231_SQW_4KHZ, DS3231_SQW_8KHZ
}
 
enum  almType_t {
  DS3231_ALM_ERROR = -1, DS3231_ALM_SEC = 0b00001111, DS3231_ALM_S = 0b00001110, DS3231_ALM_MIN = 0b01000111,
  DS3231_ALM_M = 0b01000110, DS3231_ALM_MS = 0b00001100, DS3231_ALM_HM = 0b01000100, DS3231_ALM_HMS = 0b00001000,
  DS3231_ALM_DTHM = 0b01000000, DS3231_ALM_DTHMS = 0b00000000, DS3231_ALM_DDHM = 0b01001000, DS3231_ALM_DDHMS = 0b00010000
}
 

Variables

MD_DS3231 RTC
 Library created instance of the RTC class.
 

Detailed Description

Main header file for the MD_DS3231 library.

Macro Definition Documentation

◆ ENABLE_12H

#define ENABLE_12H   1

Enable 12H (AMP/PM) support.

Set to 1 (default) to enable the AM/PM support. The related code cannot be omitted by GCC optimization so if you're not using AMP/PM, disabling 12H support migh give back up to 340 bytes on the final HEX size. Note that if diabled, you should call control(DS3231_12H, DS3231_OFF) right after device initialization.

You can change the default by editing this file directly or using a command line tool like sed : sed "s/^#define ENABLE_12H 1/#define ENABLE_12H 0/" -i MD_DS3231.h

◆ ENABLE_DOW

#define ENABLE_DOW   1

Enable Day of Week vs Date support.

Set to 1 (default) to enable Day of Week support. The related code cannot be omitted by GCC optimization so disabling day of week support if you're not using it might give back up to 212 bytes on the final HEX size.

You can change the default by editing this file directly or using a command line tool like sed : sed "s/^#define ENABLE_DOW 1/#define ENABLE_DOW 0/" -i MD_DS3231.h

◆ ENABLE_DYNAMIC_CENTURY

#define ENABLE_DYNAMIC_CENTURY   1

Enable support for dynamic century.

Set to 1 (default) to enable support for dynamic centuries using the setCentury() and getCentury() methods. If disabled, century is hardcoded (via DEFAULT_CENTURY) to 20 which allow working with dates from 2000 to 2199.

You can disable this to gain 10 bytes of HEX and 2 bytes of RAM. It is only needed for backward compatility, or if you need to work with dynamic centuries.

You can change the default by editing this file directly or using a command line tool like sed : sed "s/^#define ENABLE_CENTURY 1/#define ENABLE_CENTURY 0/" -i MD_DS3231.h

See also
setCentury() method
getCentury() method
DEFAULT_CENTURY

◆ ENABLE_RTC_INSTANCE

#define ENABLE_RTC_INSTANCE   1

Enable default RTC instance creation.

Set to 1 (default) to create a default instance when the library is included. It can be useful if you want to extend the MD_DS3231 class without wasting space (around 60 bytes) because of a variable declaration you do not use.

You can change the default by editing this file directly or using a command line tool like sed : sed "s/^#define ENABLE_RTC_INSTANCE 1/#define ENABLE_RTC_INSTANCE 0/" -i MD_DS3231.h

See also
setCentury() method.

Enumeration Type Documentation

◆ almType_t

enum almType_t

Alarm Type specifier enumerated type.

This enumerated type is used to set and inspect the alarm types for Alarms 1 and 2 using the setAlarmType() and getAlarmType() methods.

Enumerator
DS3231_ALM_ERROR 

An error occurred executing the requested action.

DS3231_ALM_SEC 

Alarm once per second (alm 1 only)

DS3231_ALM_S 

Alarm when seconds match (alm 1 only)

DS3231_ALM_MIN 

Alarm once per minute (alm 2 only)

DS3231_ALM_M 

Alarm when minutes match (alm 2 only)

DS3231_ALM_MS 

Alarm when minutes and seconds match (alm 1 only)

DS3231_ALM_HM 

Alarm when hours and minutes match (alm 2 only)

DS3231_ALM_HMS 

Alarm when hours, minutes and seconds match (alm 1 only)

DS3231_ALM_DTHM 

Alarm when date, hours and minutes match (alm 2 only)

DS3231_ALM_DTHMS 

Alarm when date, hours, minutes and seconds match (alm 1 only)

DS3231_ALM_DDHM 

Alarm when day, hours and minutes match (alm 2 only)

DS3231_ALM_DDHMS 

Alarm when day, hours, minutes and seconds match (alm 1 only)

◆ codeRequest_t

Control and Status Request enumerated type.

This enumerated type is used with the control() and status() methods to identify the control action request.

Enumerator
DS3231_CLOCK_HALT 

Controls the EOSC bit. When set to ON, the oscillator is stopped when the DS3231 switches to battery, effectively stopping any RTC functions. This bit is OFF when power is first applied. When the DS3231 is powered by Vcc, the oscillator is always on regardless of this status.

DS3231_SQW_ENABLE 

Controls the BBSQW bit. This bit is OFF when power is first applied. When set to ON with INT_ENABLE OFF, the square wave output is enabled.

DS3231_SQW_TYPE 

Controls the RS1 and RS2 bits to control the frequency of the square wave output. When power is first applied SQW_8KHZ is selected.

DS3231_12H 

Controls whether the library is using 24 hour time or AM/PM designation. Setting ON enables 12 hour time and AM/PM.

DS3231_TCONV 

Controls the CONV bit. Setting this ON forces the temperature sensor to convert the temperature into digital code and execute the TCXO algorithm. The user should check the status of BUSY_FLAG before forcing the controller to start a new TCXO execution. The TCONV status remains ON from the time it is written until the conversion is finished, at which time both TCONV and BUSY_FLAG go OFF. The TCONV status should be used when monitoring the status of a user-initiated conversion.

DS3231_INT_ENABLE 

Controls the INTCN bit. When set OFF, a square wave is output on the INT/SQW pin. When set ON, then the Alarm interrupt functions are enabled if the corresponding alarm interrupt is also enabled. The corresponding An_FLAG is always set regardless of this status. The function is ON when power is first applied.

DS3231_A1_INT_ENABLE 

Controls the A1E bit. When ON, the this bit enables the A1_FLAG bit to generate an interrupt when INT_ENABLE is also ON. When this is OFF, or INT_ENABLE is OFF, no interrupt signal is generated for Alarm 1. A1_INT_ENABLE is OFF when power is first applied.

DS3231_A2_INT_ENABLE 

Controls the A2E bit and operates like A1_INT_ENABLE but for alarm 2.

DS3231_HALTED_FLAG 

Controls the OSF bit. When ON, this indicates that the oscillator either is stopped or was stopped for some period and may be used to judge the validity of the timekeeping data. It remains ON turned OFF by user code.

DS3231_32KHZ_ENABLE 

Controls the EN32KHZ bit. When set to ON, the 32kHz pin is enabled and outputs a 32.768kHz square wave signal. When set OFF, the 32kHz pin goes to a high-impedance state. The initial power-up state is ON.

DS3231_BUSY_FLAG 

Reports the BSY bit. This status indicates the device is busy executing TCXO functions. It goes ON when the conversion is being carried out and then set to OFF when the TCXO is in the idle state.

DS3231_A1_FLAG 

Controls the A1F bit. When ON, it indicates that the time matched the alarm 1 registers. If A1_FLAG is ON and the INT_ENABLE status IS ON, an interrupt is also generated for the alarm. A1_FLAG is only cleared when written OFF by the user code.

DS3231_A2_FLAG 

Controls the A2F bit and operates like the A1_FLAG except for alarm 2.

DS3231_AGING_OFFSET 

Controls the Aging Offset register value. The register takes a user-provided value to add to or subtract from the codes in the capacitance array registers. The code is encoded in two's complement, with bit 7 representing the sign bit.

◆ codeStatus_t

Control and Status Request return values enumerated type.

This enumerated type is used as the return status from the control() and status() methods.

Enumerator
DS3231_ERROR 

An error occurred executing the requested action.

DS3231_ON 

Represents an ON status to set or returned from a get.

DS3231_OFF 

Represents an OFF status to set or returned from a get.

DS3231_SQW_1HZ 

Set or get 1Hz square wave specifier for SQW_TYPE parameter.

DS3231_SQW_1KHZ 

Set or get 1kHz square wave specifier for SQW_TYPE parameter.

DS3231_SQW_4KHZ 

Set or get 4kHz square wave specifier for SQW_TYPE parameter.

DS3231_SQW_8KHZ 

Set or get 8kHz square wave specifier for SQW_TYPE parameter.