esp-idf-ds3221 Documentation

esp-idf-ds3231 is a component for the esp-idf. The component abstracts all the features in to get/set functions. The component is 100% feature complete. All time keeping, alarm and control function are part of the comoment, including alarm interrupt functionality.

This my first fully documented and shared open source project. I welcome comments, suggestions and corrections.

The areas I could use help in are the documentation generation and configurion on readthedics.io.

Usage

Adding to Project

To use esp-idf-ds3231, simply use idf.py to import the component in to you project:

idf.py add-dependency "jschwefel/esp-idf-ds3231"

All publically accessable structs, enums, defines and functions are available through esp-idf-ds3231.h.

#include "esp-idf-ds3231.h"

Initialization

The esp-idf-ds3231 component provides two methof of Initialization:

  1. Full Initialization, including I2C bus.

i2c_master_dev_handle_t* rtc_handle = ds3231_init_full(GPIO_NUM_X, GPIO_NUM_Y);
  1. Partial Initialization, where the IC2 bus is initialized serparately.

// Allocte memory for the pointer of i2c_master_bus_handle_t
i2c_master_bus_handle_t* bus_handle = (i2c_master_bus_handle_t*)malloc(sizeof(i2c_master_bus_handle_t));
// Create the i2c_master_bus_config_t struct and assign values.
i2c_master_bus_config_t i2c_mst_config = {
   .clk_source = I2C_CLK_SRC_DEFAULT,
   .i2c_port = -1,
   .scl_io_num = GPIO_NUM_X,
   .sda_io_num = GPIO_NUM_Y,
   .glitch_ignore_cnt = 7,
   // The DS3231 **requires** pullup resistors on all of its I/O pins. Note: Some DS3231 boards have pullup resistors as part
   // of their design.
   .flags.enable_internal_pullup = true,
};
i2c_new_master_bus(&i2c_mst_config, bus_handle);
rtc_handle_t* rtc_handle = ds3231_init(bus_handle);

Use method 1 if the DS3231 is the only I2C device conneced to that I2C bus, otherwise use method 2.

union rtc_control_status_t

Union of the 2 control and status registers (0Eh and 0Fh) of the * DS3231. All (flags are active if 1.)

Public Members

uint16_t data

Native type representation of the data.

unsigned alarm1_enable

Alarm 1 Enable.

unsigned alarm2_enable

Alarm 2 Enable.

unsigned interrup_control

Interrupt/Square Wave Control. Square Wave is active when set to 1. See the DS3231 data sheet for more details.

unsigned square_freq

Square wave frequncy control register (2 bits)

BIT 1

BIT 0

OUTPUT FREQ

0

0

1.000khZ

0

1

1.024KhZ

1

0

4.096KhZ

1

1

8.192KhZ

unsigned convert_temp

Force a tempature conversion. See the DS3231 data sheet for more details

unsigned battery_square

Run the square wave when on battery. See the DS3231 data sheet for more details

unsigned enable_oscillator

Active 0 - Whien inactive, all register are read only

unsigned alarm1_flag

Flag indicating Alarm 1 triggered. If interrupts are enabled, one will be triggered/

unsigned alarm2_flag

Flag indicating Alarm 2 triggered. If interrupts are enabled, one will be triggered/

unsigned busy_flag

Temperature conversion is processing

unsigned enable_32kHz_out

Enables output of 32.765kHZ square wave. Power on default is active

unsigned oscillaror_stop_flag

Indicates the oscillator is stopped. Seethe DS3231 data sheet for more details.

struct rtc_control_status_t.[anonymous] [anonymous]
file esp-idf-ds3231.h

Defines

RTC_I2C_TIMEOUT     1000

Timeout of I2C commands in ms. Defaul is 1000. Redefine as needed. For no timeout use -1 .

Typedefs

typedef i2c_master_dev_handle_t rtc_handle_t

Simple alias of i2c_master_dev_handle.

Enums

enum rtc_register_e

Enumeration of all the register values of the DS3231 RTC chip.

Values:

enumerator RTC_REGISTER_TIME_SECONDS

Time - Seconds register

enumerator RTC_REGISTER_TIME_MINUTES

Time - Minutes register

enumerator RTC_REGISTER_TIME_HOURS

Time - Hours register

enumerator RTC_REGISTER_TIME_DAY

Time - Days (Day of Week) register

enumerator RTC_REGISTER_TIME_DATE

Time - Date (Day of Month register

enumerator RTC_REGISTER_TIME_MONTH

Time - Month register

enumerator RTC_REGISTER_TIME_YEAR

Time - Year register

enumerator RTC_REGISTER_ALARM1_SECONDS

Alarm 1 - Seconds register

enumerator RTC_REGISTER_ALARM1_MINUTES

Alarm 1 - Minutes register

enumerator RTC_REGISTER_ALARM1_HOURS

Alarm 1 - Hours register

enumerator RTC_REGISTER_ALARM1_DAY_DATE

Alarm 1 - Day or Date register

enumerator RTC_REGISTER_ALARM2_MINUTES

Alarm 1 - Minutes register

enumerator RTC_REGISTER_ALARM2_HOURS

Alarm 1 - Hours register

enumerator RTC_REGISTER_ALARM2_DAY_DATE

Alarm 1 - Day or Date register

enumerator RTC_REGISTER_CONTROL

Control & Status registers

enumerator RTC_REGISTER_CONTROL_UPPER

Upper Control & Status registers

enumerator RTC_REGISTER_CONTROL_LOWER

Lower Control & Status registers

enumerator RTC_REGISTER_AGING_OFFSET

Aging Offset register

enumerator RTC_REGISTER_TEMPERATURE

Temperature registers

enum rtc_day_of_week_e

Enumeration of all the Days of the Week vaules as used by the DS3231 chip.

Note

The Day of Week values used by DS3231 and struct tm are different. In the DS3231, the values are 1 - 7 and correspons to Monday to Sunday. In the struct tm, the values are 0 - 6 and corresponds to Sunday - Saturday. The ds3231_time_get function accounts for this. The ds3231_time_day_of_week_get does not.

Values:

enumerator RTC_MONDAY
enumerator RTC_TUESDAY
enumerator RTC_WEDNESDAY
enumerator RTC_THURSDAY
enumerator RTC_FRIDAY
enumerator RTC_SATURDAY
enumerator RTC_SUNDAY
enum tm_day_of_week_e

Enumeration of all the Days of the Week vaules as used by the POSIX time struct.

Note

The Day of Week values used by DS3231 and struct tm are different. In the DS3231, the values are 1 - 7 and correspons to Monday to Sunday. In the struct tm, the values are 0 - 6 and corresponds to Sunday - Saturday. The ds3231_time_get function accounts for this. The ds3231_time_day_of_week_get does not.

Values:

enumerator TM_SUNDAY
enumerator TM_MONDAY
enumerator TM_TUESDAY
enumerator TM_WEDNESDAY
enumerator TM_THURSDAY
enumerator TM_FRIDAY
enumerator TM_SATURDAY
enum rtc_square_wave_freq_e

Enumation of the four frequency values availed for output as a square wave on the DS3231.

Values:

enumerator RTC_SQUARE_WAVE_FREQ_1000HZ
enumerator RTC_SQUARE_WAVE_FREQ_1024HZ
enumerator RTC_SQUARE_WAVE_FREQ_4096HZ
enumerator RTC_SQUARE_WAVE_FREQ_8192HZ
enum rtc_alarm_rate_e

The alarm functionality of the DS3231 is veritile in it’s functionaliity.

Values:

enumerator RTC_ALARM_MATCH_EVERY_SECOND

Alarm 1 Only - The alarm will fire every second.

enumerator RTC_ALARM_MATCH_SECONDS_A1_OR_EVERY_MINUTES_A2

Alarm 1 Only - The alarm will fire when the seconds value in the alarm matches the seconds value of the DS3231. Alarm 2 Only - The alarm will fire every minute when the seconds value on the DS3231 hits 00.

enumerator RTC_ALARM_MATCH_MINUTES

The alarm will fire every hour when the minutes (and seconds for Alarm 1) value matches the the DS3231 minutes (and seconds for Alarm 1) value

enumerator RTC_ALARM_MATCH_HOURS

The alarm will fire every day when the hour, minutes (and seconds for Alarm 1) value matches the the DS3231 hour, minutes (and seconds for Alarm 1) value

enumerator RTC_ALARM_MATCH_DAY_DATE

The alarm will fire every day when the hour, minutes (and seconds for Alarm 1) value matches the the DS3231 hour, minutes (and seconds for Alarm 1) value

enumerator RTC_ALARM_MATCH_INVALID
enum rtc_intr_sqr_e

Values:

enumerator square
enumerator interrupts

Functions

rtc_handle_t *ds3231_init_full(gpio_num_t SCL, gpio_num_t SDA)

Initialize the I2C and the DS3231 RTC Module.

Parameters:
  • SCL – [in] GPIO_NUM_X to use as I2C Clock.

  • SDA – [in] GPIO_NUM_X to use as I2C Data.

Return values:
  • rtc_handle_t – Handle required for subesequent operations.

  • NULL – The handle creation failed. Check serial monitor for ERROR condition.

rtc_handle_t *ds3231_init(i2c_master_bus_handle_t *bus_handle)

Initialize the DS3231 RTC Module with I2C info.

Parameters:
  • *bus_handle – [in] The i2c_master_bus_handle_t from i2c_new_master_bus call.

Return values:
  • rtc_handle_t – Handle required for subesequent operations.

  • NULL – The handle creation failed. Check serial monitor for ERROR condition.

void ds3231_debug_print_data(rtc_handle_t *rtc_handle)

This is a testing function. It will real all registers and display their data.

Gets all of the time, alarm and control/status registers. Data is output as ESP_LOGI.

Note

This is a good function to call as a check on that data being set on the DS3231.

Note

If the debug level is set to VERBOSE, there will a list of each register and its value in both hex and binary for each get AND set operation.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

uint8_t *ds3231_get_registers_raw(rtc_handle_t *rtc_handle)

Queries the DS3231 for the contents of all registers (00h - 12h) as raw data.

Note

The returned value must be freed by the caller to prevent memory leakage

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

uint8_t* - An array containing all of the register data.

esp_err_t ds3231_send_byte_raw(rtc_handle_t *rtc_handle, enum rtc_register_e rtc_register, uint8_t rtc_data)

Sends sinlge unsinged 8-bit byte to a specific DS3231 register.

Warning

This is a potentially dangerous command. ANY data can be sent to ANY register. There is no checking performed.

Warning

The inclustion of this function is to allow low-level access that the standard set_x and get_x function do not provide.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • rtc_register – [in] The register to be written to.

  • rtc_data – [in] The data to be written to rtc_tregister.

Returns:

esp_err_t - cascaded from i2c_master_transmit

  • ESP_OK: I2C master transmit-receive success

  • ESP_ERR_INVALID_ARG: I2C master transmit parameter invalid.

  • ESP_ERR_TIMEOUT: Operation timeout(larger than xfer_timeout_ms) because the bus is busy or hardware crash.

int8_t ds3231_time_minutes_or_seconds_get(rtc_handle_t *rtc_handle, enum rtc_register_e rtc_register)

Queries the DS3231 for the contents the minutes or seconds rgisters. Works on both Time and Alarm registers.

Note

Alarm2 has no seconds register.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • rtc_register – [in] rtc_register_e The minutes/seconds register for Time, Alarm 1, Alarm 2

Returns:

uint8_t - Single byte representing Base-10 minutes or seconds value.

  • Values: 0-59

  • Leap seconds are NOT accounted format

int8_t ds3231_time_hours_get(rtc_handle_t *rtc_handle, enum rtc_register_e rtc_register)

Queries the DS3231 for the contents the hours rgister. Works on both Time and Alarm registers.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • rtc_register – [in] rtc_register_e The hours register for Time, Alarm 1, Alarm 2

Returns:

uint8_t - Single byte representing Base-10 hours.

  • Values: 0-23.

  • Always in 24 hour format.

int8_t ds3231_time_day_of_week_get(rtc_handle_t *rtc_handle, enum rtc_register_e rtc_register)

Queries the DS3231 for the contents the day of week rgister. Works on both Time and Alarm registers.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • rtc_register – [in] rtc_register_e The day of week register for Time, Alarm 1, Alarm 2

Returns:

uint8_t - Single byte representing the Day of Week.

  • Values 1 - 7

  • Day counting starts on Monday (1 == Monday)

int8_t ds3231_time_date_get(rtc_handle_t *rtc_handle, enum rtc_register_e rtc_register)

Queries the DS3231 for the contents the day of month rgister. Works on both Time and Alarm registers.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • rtc_register – [in] rtc_register_e The day of month register for Time, Alarm 1, Alarm 2

Returns:

uint8_t - Single byte representing the Day of Month.

  • Values 1 - 31

int8_t ds3231_time_month_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the contents the Month rgister. Works only on Time.

Note

Neither Alarm 1 nor Alarm 2 have a Month register.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

uint8_t - Single byte representing the Month.

  • Values 1 - 12

int16_t ds3231_time_year_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the contents the Year rgister. Works only on Time.

Note

Neither Alarm 1 nor Alarm 2 have a Year register.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

uint16_t - Two byte representing the Year.

  • Values 1900 - 2099

int8_t ds3231_aging_offset_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the contents the Aging Offset register.

Note

Please see the DS3231 Data Sheet for specifics of the Aging Offset

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

int8_t - Signed single byte representing the aging offset.

float ds3231_temperature_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the contents the Temperature registers.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

float - Float representing the the temperature in 0.25° C increments.

rtc_control_status_t *ds3231_control_status_flags_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the contents the Contol and Status registers.

Note

Please see the DS3231 Data Sheet for full descriptions of all of the control and status values.

Note

The returned value must be freed by the caller to prevent memory leakage

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

rtc_control_status_t* - Pointer to stuct containing all of the control and status register values.

struct tm *ds3231_time_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the current time value and is returned as struct tm.

Note

The returned value must be freed by the caller to prevent memory leakage

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

struct tm* - Pointer to struct tm populated with the current time.

esp_err_t ds3231_time_time_t_set(rtc_handle_t *rtc_handle, time_t time)

Sets the time on the DS3231 usinf a time_t value.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • time – [in] time_t that is set to the time to be set on on the DS3231

Returns:

esp_err_t - cascaded from i2c_master_transmit

time_t ds3231_time_unix_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the current time value and is returned as struct tm.

Note

Even though the ESP32 family is 32-bits, time_t is 64-bit and is Y2038 compliant,

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

time_t - Unsigned integer value representing number of seconds since Jan 1, 1970 00:00:00

esp_err_t ds3231_time_unix_set(rtc_handle_t *rtc_handle, long unix_time)

Sets the time on the DS3231 using a time_t value.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • unix_time – [in] long that is set to the time, in seconds since Jan 1, 1970 @ 00:00:00 to be set on on the DS3231

Returns:

esp_err_t - cascaded from i2c_master_transmit

esp_err_t ds3231_time_tm_set(rtc_handle_t *rtc_handle, struct tm time)

Sets the time of the DS3231 using a struct tm value.

Note

the time value MUST have BOTH the day of the week (tm.tm_wday) and day of month (tm.tm_mday) populated to correctlt set the time on the DS3231

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • time – [in] struct tm that has its fields set the desired time values.

Returns:

esp_err_t - cascaded from i2c_master_transmit

esp_err_t ds3231_alarm_isr_create(rtc_handle_t *rtc_handle, gpio_num_t INT, gpio_isr_t isr, void *params)

Creates the GPIO Pin interrupt and queue and assigns the user-defined function and parameters for handling interrupts generated by the DS3231 on it’s INT pin.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • INT – [in] gpio_num_t The GPIO Pin that the DS3231 INT pin is connected to.

  • isr – [in] gpio_isr_t User-defined function to be invoded at every interrupt event.

  • params – [in] void* Pointer to parameters that are passed to isr,

Returns:

esp_err_t - cascaded from gpio_isr_handler_add

esp_err_t ds3231_alarm_isr_delete(rtc_handle_t *rtc_handle, gpio_num_t INT)

Deletes alarm isr previously created by ds3231_alarm_isr_create.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • INT – [in] gpio_num_t The GPIO Pin that the DS3231 INT pin is connected to.

Returns:

esp_err_t - cascaded from gpio_isr_handler_delete

struct tm *ds3231_alarm1_time_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the set value of Alarm 1.

Attention

Due to the difference on how the DS3231 and struct tm store day of week/month values, a -1 will appear in the tm.tm_wday or tm.tm_mday (or both) to indicate that those values are invalid

Attention

If tm.tm_wday or tm.tm_mday has a -1 and the other have is >= 0, this a normal condition as only the Day of the Week or Day of the Month may be used at any given time per alarm.

Note

The returned value must be freed by the caller to prevent memory leakage

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

struct tm* - Pointer to struct tm populated with the Alarm 1 time.

esp_err_t ds3231_alarm1_day_of_week_set(rtc_handle_t *rtc_handle, enum rtc_day_of_week_e dow, int8_t hour, int8_t minutes, int8_t seconds)

Sets the value of Alarm 1 to fire on the same day each week. Alarm 1 supports a seconds value, where as Alarm 2 does not. Otherwise they are functioanally the same.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • dow – [in] enum rtc_day_of_week_e. (This emum coresponds with how the DS3231 represents the doy of week.)

  • hour – [in] int8_t represening hours from 00 - 23.

  • minutes – [in] int8_t representing minutes from 00 - 59.

  • seconds – [in] int8_t representing seconds from 00 - 59.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

esp_err_t ds3231_alarm1_day_of_month_set(rtc_handle_t *rtc_handle, int8_t day, int8_t hour, int8_t minutes, int8_t seconds)

Sets the value of Alarm 1 to fire on the same day each month. Alarm 1 supports a seconds value, where as Alarm 2 does not. Otherwise they are functioanally the same.

Note

If the day of the month does not exist in the current month, i.e. February 30th, the alarm will not fire that month. It is recomended the logic be included in the alarm ISR to adjust the alarm entry after it fires.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • day – [in] int8_t representing the day of the month.

  • hour – [in] int8_t represening hours from 00 - 23.

  • minutes – [in] int8_t representing minutes from 00 - 59.

  • seconds – [in] int8_t representing seconds from 00 - 59.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_alarm1_enable_flag_get(rtc_handle_t *rtc_handle)

Returs a boolean value representing the isEnabled status of the Alarm 1.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – - Alarm 1 is enabled.

  • false – - Alarm 1 is disabled.

esp_err_t ds3231_alarm1_enable_flag_set(rtc_handle_t *rtc_handle, bool isEnabled)

Sets the enable/disabled state of Alarm 1.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • isEnabled – [in] bool that enables/disables Alarm 1

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_alarm1_fired_flag_get(rtc_handle_t *rtc_handle)

Gets the status of the Alarm 1 Fired flag. If alarm interrupts are configured, one will be triggered. This flag remains set until is manually unset.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – - Alarm 1 has fired.

  • false – - Alarm 1 had NOT fired.

enum rtc_alarm_rate_e ds3231_alarm1_rate_get(rtc_handle_t *rtc_handle)

Gets the Alarm 1 trigger condition as described in rtc_alarm_rate_e.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

enum rtc_alarm_rate_e - Enum identifying the trigger condition,

esp_err_t ds3231_alarm1_rate_set(rtc_handle_t *rtc_handle, enum rtc_alarm_rate_e alarm_rate)

Sets the Alarm 1 trigger condition as described in rtc_alarm_rate_e.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • alarm_rate – [in] Enum identifying the trigger condition.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

esp_err_t ds3231_alarm1_fired_flag_reset(rtc_handle_t *rtc_handle)

Resets the Alarm 1 Fired flag to zero.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

struct tm *ds3231_alarm2_time_get(rtc_handle_t *rtc_handle)

Queries the DS3231 for the set value of Alarm 2.

Attention

Due to the difference on how the DS3231 and struct tm store day of week/month values, a -1 will appear in the tm.tm_wday or tm.tm_mday (or both) to indicate that those values are invalid

Attention

If tm.tm_wday or tm.tm_mday has a -1 and the other have is >= 0, this a normal condition as only the Day of the Week or Day of the Month may be used at any given time per alarm.

Note

The returned value must be freed by the caller to prevent memory leakage

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

struct tm* - Pointer to struct tm populated with the Alarm 2 time.

esp_err_t ds3231_alarm2_day_of_week_set(rtc_handle_t *rtc_handle, enum rtc_day_of_week_e dow, int8_t hour, int8_t minutes)

Sets the value of Alarm 2 to fire on the same day each week. Alarm 2 supports a seconds value, where as Alarm 2 does not. Otherwise they are functioanally the same.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • dow – [in] enum rtc_day_of_week_e. (This emum coresponds with how the DS3231 represents the doy of week.)

  • hour – [in] int8_t represening hours from 00 - 23.

  • minutes – [in] int8_t representing minutes from 00 - 59.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

esp_err_t ds3231_alarm2_day_of_month_set(rtc_handle_t *rtc_handle, int8_t day, int8_t hour, int8_t minutes)

Sets the value of Alarm 2 to fire on the same day each month. Alarm 2 supports a seconds value, where as Alarm 2 does not. Otherwise they are functioanally the same.

Note

If the day of the month does not exist in the current month, i.e. February 30th, the alarm will not fire that month. It is recomended the logic be included in the alarm ISR to adjust the alarm entry after it fires.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • day – [in] int8_t representing the day of the month.

  • hour – [in] int8_t represening hours from 00 - 23.

  • minutes – [in] int8_t representing minutes from 00 - 59.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_alarm2_enable_flag_get(rtc_handle_t *rtc_handle)

Returs a boolean value representing the isEnabled status of the Alarm 2.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – - Alarm 2 is enabled.

  • false – - Alarm 2 is disabled.

esp_err_t ds3231_alarm2_enable_flag_set(rtc_handle_t *rtc_handle, bool isEnabled)

Sets the enable/disabled state of Alarm 2.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • isEnabled – [in] bool that enables/disables Alarm 2

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_alarm2_fired_flag_get(rtc_handle_t *rtc_handle)

Gets the status of the Alarm 2 Fired flag. If alarm interrupts are configured, one will be triggered. This flag remains set until is manually unset.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – - Alarm 2 has fired.

  • false – - Alarm 2 had NOT fired.

enum rtc_alarm_rate_e ds3231_alarm2_rate_get(rtc_handle_t *rtc_handle)

Gets the Alarm 2 trigger condition as described in rtc_alarm_rate_e.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

enum rtc_alarm_rate_e - Enum identifying the trigger condition,

esp_err_t ds3231_alarm2_rate_set(rtc_handle_t *rtc_handle, enum rtc_alarm_rate_e alarm_rate)

Sets the Alarm 2 trigger condition as described in rtc_alarm_rate_e.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • alarm_rate – [in] Enum identifying the trigger condition.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

esp_err_t ds3231_alarm2_fired_flag_reset(rtc_handle_t *rtc_handle)

Resets the Alarm 2 Fired flag to zero.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

int ds3231_set_esp_with_rtc(rtc_handle_t *rtc_handle)

Synchronizes the time on the ESP32 with the time from thr DS3231.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • 0 – Success

  • -1 – Failure

bool ds3231_enable_oscillator_flag_get(rtc_handle_t *rtc_handle)

Gets the status of the Oscillartor Flag.

Note

The driver is aware that on the harware that Enable is Logic 0 and will return true for Logic 0

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – Enabled

  • false – Disabled

esp_err_t ds3231_enable_oscillator_flag_set(rtc_handle_t *rtc_handle, bool isEnabled)

Setss the status of the Oscillartor Flag.

Note

The driver is aware that on the harware that Enable is Logic 0 and will set Logic 0 for isEnmabled = true

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • isEnabled – [in] bool that enables/disables the Oscillaror Flag

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_battery_backed_square_wave_flag_get(rtc_handle_t *rtc_handle)

Gets the status of the Battery Backed Scquare Wave Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – Enabled

  • false – Disabled

esp_err_t ds3231_battery_backed_square_wave_flag_set(rtc_handle_t *rtc_handle, bool isEnabled)

Sets the status of the Batter Backed Square Wave Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • isEnabled – [in] bool that enables/disables the Battery Backed Square Wave Flag

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_convert_temp_flag_get(rtc_handle_t *rtc_handle)

Gets the status of the Convert Temp TemperatureFlag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – Enabled

  • false – Disabled

esp_err_t ds3231_convert_temp_flag_set(rtc_handle_t *rtc_handle, bool isEnabled)

Sets the status of the Convert Temperature Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • isEnabled – [in] bool that enables/disables the Convert Temperature Flag

Returns:

esp_err_t - cascaded from i2c_master_transmit.

enum rtc_square_wave_freq_e ds3231_square_wave_freq_get(rtc_handle_t *rtc_handle)

Gets the current (1 of 4) value of the square wave output.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

enum rtc_square_wave_freq_e Square Wave frequency

esp_err_t ds3231_square_wave_freq_set(rtc_handle_t *rtc_handle, enum rtc_square_wave_freq_e frequency)

Sets the (1 of 4) square wave output.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • frequency – [in] rtc_square_wave_freq_e The desired frequency.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

enum rtc_intr_sqr_e ds3231_interrupt_square_wave_control_flag_get(rtc_handle_t *rtc_handle)

Gets the status of the Interupt/Square Wave Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – Alarm Interrupts are enabled

  • false – Square Wave is output constantly

esp_err_t ds3231_interrupt_square_wave_control_flag_set(rtc_handle_t *rtc_handle, enum rtc_intr_sqr_e isEnabled)

Sets the status of the Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • isEnabled – [in] bool that enables/disables the Flag

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_get_oscillator_stop_flag(rtc_handle_t *rtc_handle)

Gets the status of the Ocsillator Stop Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – Enabled

  • false – Disabled

esp_err_t ds3231_oscillator_stop_flag_reset(rtc_handle_t *rtc_handle)

Resets the status of the Ocsillator Stop Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_32kHz_out_enable_flag_get(rtc_handle_t *rtc_handle)

Gets the status of the 32kHz Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – Enabled

  • false – Disabled

esp_err_t ds3231_32kHz_out_enable_flag_set(rtc_handle_t *rtc_handle, bool isEnabled)

Sets the status of the 32kHz Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • isEnabled – [in] bool that enables/disables the 32kHz Flag

Returns:

esp_err_t - cascaded from i2c_master_transmit.

bool ds3231_busy_flag_get(rtc_handle_t *rtc_handle)

Gets the status of the Busy Flag.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

Return values:
  • true – Enabled

  • false – Disabled

esp_err_t ds3231_register_set(rtc_handle_t *rtc_handle, enum rtc_register_e rtc_register, uint8_t bit_pattern)

Similar in concept to ds3231_set_registers_raw. Allows for the setting of a single register with a single byte of data.

Warning

This is a potentially dangerous command as no sanity checks are performed on the data. This function is provided in the event that the other function do not provide desired functionality.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • rtc_register – [in] enum rtc_register_e Register to write to

  • bit_pattern – [in] uint8_t Value to write

Returns:

esp_err_t - cascaded from i2c_master_transmit.

esp_err_t ds3231_set_registers_raw(rtc_handle_t *rtc_handle, uint8_t *rtc_data, size_t count)

Similar in concept to ds3231_register_set. Allows for the setting of a multiple successive registers with an array of data.

Warning

This is a potentially dangerous command as no sanity checks are performed on the data. This function is provided in the event that the other function do not provide desired functionality.

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

  • rtc_data – [in] uint8_t array with the date to write to the register(s).

  • count – [in] size_t the number of elements in rtc_data

Returns:

esp_err_t - cascaded from i2c_master_transmit.

void ds3231_debug_test_set(rtc_handle_t *rtc_handle)

Sets, gets, resets and gets all flags from the control/status regiters. Data is output as ESP_LOGI.

Warning

This should only be used for debugging/testing a DS3231. Existing setting will be overwritten

Parameters:
  • rtc_handle – [in] rtc_handle_t* returned from ds3231_init.

dir /home/docs/checkouts/readthedocs.org/user_builds/esp-idf-ds3231/checkouts/v0.9.10/include