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:
Full Initialization, including I2C bus.
i2c_master_dev_handle_t* rtc_handle = ds3231_init_full(GPIO_NUM_X, GPIO_NUM_Y);
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]
-
uint16_t data
- 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
-
enumerator RTC_REGISTER_TIME_SECONDS
-
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
-
enumerator RTC_MONDAY
-
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
-
enumerator TM_SUNDAY
-
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
-
enumerator RTC_SQUARE_WAVE_FREQ_1000HZ
-
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
-
enumerator RTC_ALARM_MATCH_EVERY_SECOND
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.
-
RTC_I2C_TIMEOUT 1000
- dir /home/docs/checkouts/readthedocs.org/user_builds/esp-idf-ds3231/checkouts/v0.9.10/include