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

Copyright (C) 2018 Ruslan V. Uss

unclerus@gmail.com

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

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

Second alarm rate.

Values:

enumerator DS3231_ALARM2_EVERY_MIN
enumerator DS3231_ALARM2_MATCH_MIN
enumerator DS3231_ALARM2_MATCH_MINHOUR
enumerator DS3231_ALARM2_MATCH_MINHOURDAY
enumerator DS3231_ALARM2_MATCH_MINHOURDATE
enum ds3231_sqwave_freq_t

Squarewave frequency.

Values:

enumerator DS3231_SQWAVE_1HZ
enumerator DS3231_SQWAVE_1024HZ
enumerator DS3231_SQWAVE_4096HZ
enumerator DS3231_SQWAVE_8192HZ

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.

Parameters

  • dev – I2C device descriptor

  • port – I2C port

  • sda_gpio – SDA GPIO

  • scl_gpio – SCL GPIO

Returns

ESP_OK to indicate success

esp_err_t ds3231_free_desc(i2c_dev_t *dev)

Free device descriptor.

Parameters

dev – I2C device descriptor

Returns

ESP_OK to indicate success

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.

Returns

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.

Parameters

  • dev – Device descriptor

  • [out] time – RTC time

Returns

ESP_OK to indicate success

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_* and DS3231_ALARM2_* defines for valid options you only need to populate the fields you are using in the tm struct, and you can set both alarms at the same time (pass DS3231_ALARM_1/DS3231_ALARM_2/DS3231_ALARM_BOTH).

If only setting one alarm just pass 0 for tm struct and option field for the other alarm. If using DS3231_ALARM1_EVERY_SECOND/DS3231_ALARM2_EVERY_MIN you can pass 0 for tm struct.

If you want to enable interrupts for the alarms you need to do that separately.

Returns

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

Parameters

  • dev – Device descriptor

  • [out] flag – Stop flag

Returns

ESP_OK to indicate success

esp_err_t ds3231_clear_oscillator_stop_flag(i2c_dev_t *dev)

Clear the oscillator stopped flag.

Parameters

dev – Device descriptor

Returns

ESP_OK to indicate success

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

Parameters

  • dev – Device descriptor

  • [out] alarms – Alarms

Returns

ESP_OK to indicate success

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

Parameters

  • dev – Device descriptor

  • alarms – Alarms

Returns

ESP_OK to indicate success

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.

Parameters

  • dev – Device descriptor

  • alarms – Alarms

Returns

ESP_OK to indicate success

esp_err_t ds3231_disable_alarm_ints(i2c_dev_t *dev, ds3231_alarm_t alarms)

Disable alarm interrupts.

Does not (re-)enable squarewave

Parameters

  • dev – Device descriptor

  • alarms – Alarm

Returns

ESP_OK to indicate success

esp_err_t ds3231_enable_32khz(i2c_dev_t *dev)

Enable the output of 32khz signal.

Supported only by DS3231

Parameters

dev – Device descriptor

Returns

ESP_OK to indicate success

esp_err_t ds3231_disable_32khz(i2c_dev_t *dev)

Disable the output of 32khz signal.

Supported only by DS3231

Parameters

dev – Device descriptor

Returns

ESP_OK to indicate success

esp_err_t ds3231_enable_squarewave(i2c_dev_t *dev)

Enable the squarewave output.

Disables alarm interrupt functionality.

Parameters

dev – Device descriptor

Returns

ESP_OK to indicate success

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.

Parameters

dev – Device descriptor

Returns

ESP_OK to indicate success

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.

Parameters

  • dev – Device descriptor

  • freq – Squarewave frequency

Returns

ESP_OK to indicate success

esp_err_t ds3231_get_raw_temp(i2c_dev_t *dev, int16_t *temp)

Get the raw temperature value.

Supported only by DS3231

Parameters

  • dev – Device descriptor

  • [out] temp – Raw temperature value

Returns

ESP_OK to indicate success

esp_err_t ds3231_get_temp_integer(i2c_dev_t *dev, int8_t *temp)

Get the temperature as an integer.

Supported only by DS3231

Parameters

  • dev – Device descriptor

  • [out] temp – Temperature, degrees Celsius

Returns

ESP_OK to indicate success

esp_err_t ds3231_get_temp_float(i2c_dev_t *dev, float *temp)

Get the temperature as a float.

Supported only by DS3231

Parameters

  • dev – Device descriptor

  • [out] temp – Temperature, degrees Celsius

Returns

ESP_OK to indicate success