ds3231 - Driver for DS1337 RTC and DS3231 high precision RTC module¶
-
group
ds3231
ESP-IDF driver for DS337 RTC and DS3231 high precision RTC module.
Ported from esp-open-rtos
Copyright (C) 2015 Richard A Burton richardaburton@gmail.com
Copyright (C) 2016 Bhuvanchandra DV
bhuvanchandra.dv@gmail.comCopyright (C) 2018 Ruslan V. Uss
unclerus@gmail.comMIT Licensed as described in the file LICENSE
Defines
-
DS3231_ADDR
¶ I2C address.
Enums
-
enum
ds3231_alarm_t
¶ Alarms.
Values:
-
enumerator
DS3231_ALARM_NONE
¶ No alarms.
-
enumerator
DS3231_ALARM_1
¶ First alarm.
-
enumerator
DS3231_ALARM_2
¶ Second alarm.
-
enumerator
DS3231_ALARM_BOTH
¶ Both alarms.
-
enumerator
-
enum
ds3231_alarm1_rate_t
¶ First alarm rate.
Values:
-
enumerator
DS3231_ALARM1_EVERY_SECOND
¶
-
enumerator
DS3231_ALARM1_MATCH_SEC
¶
-
enumerator
DS3231_ALARM1_MATCH_SECMIN
¶
-
enumerator
DS3231_ALARM1_MATCH_SECMINHOUR
¶
-
enumerator
DS3231_ALARM1_MATCH_SECMINHOURDAY
¶
-
enumerator
DS3231_ALARM1_MATCH_SECMINHOURDATE
¶
-
enumerator
Functions
-
esp_err_t
ds3231_init_desc
(i2c_dev_t *dev, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)¶ Initialize device descriptor.
- Return
ESP_OK to indicate success
- Parameters
dev
: I2C device descriptorport
: I2C portsda_gpio
: SDA GPIOscl_gpio
: SCL GPIO
-
esp_err_t
ds3231_free_desc
(i2c_dev_t *dev)¶ Free device descriptor.
- Return
ESP_OK to indicate success
- Parameters
dev
: I2C device descriptor
-
esp_err_t
ds3231_set_time
(i2c_dev_t *dev, struct tm *time)¶ Set the time on the RTC.
Timezone agnostic, pass whatever you like. I suggest using GMT and applying timezone and DST when read back.
- Return
ESP_OK to indicate success
-
esp_err_t
ds3231_get_time
(i2c_dev_t *dev, struct tm *time)¶ Get the time from the RTC, populates a supplied tm struct.
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor[out] time
: RTC time
-
esp_err_t
ds3231_set_alarm
(i2c_dev_t *dev, ds3231_alarm_t alarms, struct tm *time1, ds3231_alarm1_rate_t option1, struct tm *time2, ds3231_alarm2_rate_t option2)¶ Set alarms.
alarm1
works with seconds, minutes, hours and day of week/month, or fires every second.alarm2
works with minutes, hours and day of week/month, or fires every minute.Not all combinations are supported, see
DS3231_ALARM1_*
andDS3231_ALARM2_*
defines for valid options you only need to populate the fields you are using in thetm
struct, and you can set both alarms at the same time (passDS3231_ALARM_1
/DS3231_ALARM_2
/DS3231_ALARM_BOTH
).If only setting one alarm just pass 0 for
tm
struct andoption
field for the other alarm. If usingDS3231_ALARM1_EVERY_SECOND
/DS3231_ALARM2_EVERY_MIN
you can pass 0 fortm
struct.If you want to enable interrupts for the alarms you need to do that separately.
- Return
ESP_OK to indicate success
-
esp_err_t
ds3231_get_oscillator_stop_flag
(i2c_dev_t *dev, bool *flag)¶ Check if oscillator has previously stopped.
E.g. no power/battery or disabled sets flag to true if there has been a stop
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor[out] flag
: Stop flag
-
esp_err_t
ds3231_clear_oscillator_stop_flag
(i2c_dev_t *dev)¶ Clear the oscillator stopped flag.
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor
-
esp_err_t
ds3231_get_alarm_flags
(i2c_dev_t *dev, ds3231_alarm_t *alarms)¶ Check which alarm(s) have past.
Sets alarms to
DS3231_ALARM_NONE
/DS3231_ALARM_1
/DS3231_ALARM_2
/DS3231_ALARM_BOTH
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor[out] alarms
: Alarms
-
esp_err_t
ds3231_clear_alarm_flags
(i2c_dev_t *dev, ds3231_alarm_t alarms)¶ Clear alarm past flag(s)
Pass
DS3231_ALARM_1
/DS3231_ALARM_2
/DS3231_ALARM_BOTH
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptoralarms
: Alarms
-
esp_err_t
ds3231_enable_alarm_ints
(i2c_dev_t *dev, ds3231_alarm_t alarms)¶ enable alarm interrupts (and disables squarewave)
Pass
DS3231_ALARM_1
/DS3231_ALARM_2
/DS3231_ALARM_BOTH
.If you set only one alarm the status of the other is not changed you must also clear any alarm past flag(s) for alarms with interrupt enabled, else it will trigger immediately.
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptoralarms
: Alarms
-
esp_err_t
ds3231_disable_alarm_ints
(i2c_dev_t *dev, ds3231_alarm_t alarms)¶ Disable alarm interrupts.
Does not (re-)enable squarewave
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptoralarms
: Alarm
-
esp_err_t
ds3231_enable_32khz
(i2c_dev_t *dev)¶ Enable the output of 32khz signal.
Supported only by DS3231
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor
-
esp_err_t
ds3231_disable_32khz
(i2c_dev_t *dev)¶ Disable the output of 32khz signal.
Supported only by DS3231
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor
-
esp_err_t
ds3231_enable_squarewave
(i2c_dev_t *dev)¶ Enable the squarewave output.
Disables alarm interrupt functionality.
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor
-
esp_err_t
ds3231_disable_squarewave
(i2c_dev_t *dev)¶ Disable the squarewave output.
Which re-enables alarm interrupts, but individual alarm interrupts also need to be enabled, if not already, before they will trigger.
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor
-
esp_err_t
ds3231_set_squarewave_freq
(i2c_dev_t *dev, ds3231_sqwave_freq_t freq)¶ Set the frequency of the squarewave output.
Does not enable squarewave output.
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptorfreq
: Squarewave frequency
-
esp_err_t
ds3231_get_raw_temp
(i2c_dev_t *dev, int16_t *temp)¶ Get the raw temperature value.
Supported only by DS3231
- Return
ESP_OK to indicate success
- Parameters
dev
: Device descriptor[out] temp
: Raw temperature value
-