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

enum 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

enum 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.