DS3231 v0.6.1
An ESP-IDF driver for the DS3231 RTC
Loading...
Searching...
No Matches
ds3231.h File Reference

Public API for the DS3231 RTC driver. More...

#include <time.h>
#include <stdbool.h>
#include "driver/i2c_master.h"
#include "esp_err.h"

Go to the source code of this file.

Macros

#define DS3231_I2C_ADDR_DEFAULT   0x68
#define DS3231_I2C_CLK_SPEED   100000UL
#define DS3231_TIMEOUT_MS   50
#define DS3231_LOCK_TIMEOUT_MS   1000

Typedefs

typedef void * ds3231_handle_t
 Handle of a DS3231 device.

Enumerations

enum  ds3231_time_format_t { DS3231_TIME_FORMAT_12H , DS3231_TIME_FORMAT_24H }
 Time format of the device. More...
enum  ds3231_squarewave_freq_t { DS3231_FREQ_1HZ = 0x00 , DS3231_FREQ_1024HZ = 0x08 , DS3231_FREQ_4096HZ = 0x10 , DS3231_FREQ_8192HZ = 0x18 }
 Square wave output on the INT/SQW pin. More...
enum  ds3231_alarms_t { DS3231_ALARM_NONE = 0x00 , DS3231_ALARM_A1 = 0x01 , DS3231_ALARM_A2 = 0x02 , DS3231_ALARM_A1_A2 = 0x03 }
 Alarms whose interrupts are enabled. More...
enum  ds3231_alarm_flags_t { DS3231_ALARM_NO_INTERR = 0x00 , DS3231_ALARM1_FLAG_INTERR = 0x01 , DS3231_ALARM2_FLAG_INTERR = 0x02 , DS3231_ALARM1_ALARM2_FLAGS_INTERR = 0x03 }
 Alarm flags which sets by the device when the time matches the alarm. More...
enum  ds3231_alarm1_match_t {
  DS3231_ALARM1_INTERR_PER_SEC = 0x0F , DS3231_ALARM1_INTERR_MATCH_SEC = 0x0E , DS3231_ALARM1_INTERR_MATCH_MINSEC = 0x0C , DS3231_ALARM1_INTERR_MATCH_HOURMINSEC = 0x08 ,
  DS3231_ALARM1_INTERR_HOURMINSECDAY = 0x10 , DS3231_ALARM1_INTERR_HOURMINSECDATE = 0x00
}
 Match mode of alarm 1. More...
enum  ds3231_alarm2_match_t {
  DS3231_ALARM2_INTERR_PER_MIN = 0x07 , DS3231_ALARM2_INTERR_MATCH_MIN = 0x06 , DS3231_ALARM2_INTERR_MATCH_HOURMIN = 0x04 , DS3231_ALARM2_INTERR_MATCH_HOURMINDATE = 0x00 ,
  DS3231_ALARM2_INTERR_HOURMINDAY = 0x10
}
 Match mode of alarm 2. More...

Functions

esp_err_t ds3231_create (i2c_master_bus_handle_t i2c_bus, ds3231_handle_t *ds3231_handle)
 Initialize device handle.
void ds3231_delete (ds3231_handle_t ds3231_handle)
 Free device handle.
esp_err_t ds3231_get_time_valid (ds3231_handle_t ds3231_handle, bool *time_valid)
 Check validity of the time module saved.
esp_err_t ds3231_osc_battery_get_status (ds3231_handle_t ds3231_handle, bool *enabled)
 Check whether the oscillator is enabled when running on battery or not.
esp_err_t ds3231_osc_battery_set_status (ds3231_handle_t ds3231_handle, bool enabled)
 Enable or disable the oscillator when running on battery.
esp_err_t ds3231_get_time_format (ds3231_handle_t ds3231_handle, ds3231_time_format_t *timeformat)
 Get the current time format.
esp_err_t ds3231_set_time (ds3231_handle_t ds3231_handle, struct tm timeinfo, ds3231_time_format_t format)
 Set current date time.
esp_err_t ds3231_get_time (ds3231_handle_t ds3231_handle, struct tm *timeinfo, ds3231_time_format_t *format)
 Get the current date and time.
esp_err_t ds3231_get_temperature (ds3231_handle_t ds3231_handle, float *temp)
 Read temperature from the chip.
esp_err_t ds3231_get_aging (ds3231_handle_t ds3231_handle, int8_t *age)
 Get the aging offset.
esp_err_t ds3231_set_aging (ds3231_handle_t ds3231_handle, int8_t age)
 Set the aging offset.
esp_err_t ds3231_squarewave_set_freq (ds3231_handle_t ds3231_handle, ds3231_squarewave_freq_t freq)
 Set square wave frequency.
esp_err_t ds3231_squarewave_get_freq (ds3231_handle_t ds3231_handle, ds3231_squarewave_freq_t *freq)
 Get square wave frequency.
esp_err_t ds3231_squarewave_enable (ds3231_handle_t ds3231_handle)
 Enable generating of the square wave.
esp_err_t ds3231_squarewave_disable (ds3231_handle_t ds3231_handle)
 Disable generating of the square wave.
esp_err_t ds3231_squarewave_battery_enable (ds3231_handle_t ds3231_handle)
 Allow the device to run the square wave when powered from the battery.
esp_err_t ds3231_squarewave_battery_disable (ds3231_handle_t ds3231_handle)
 Disallow the device to run the square wave when powered from the battery.
esp_err_t ds3231_squarewave_32khz_enable (ds3231_handle_t ds3231_handle)
 Enable 32 kHz output.
esp_err_t ds3231_squarewave_32khz_disable (ds3231_handle_t ds3231_handle)
 Disable 32 kHz output.
esp_err_t ds3231_alarm_interr_get_status (ds3231_handle_t ds3231_handle, ds3231_alarms_t *interr)
 Get which alarm interrupts are enabled.
esp_err_t ds3231_alarm1_interr_enable (ds3231_handle_t ds3231_handle)
 Enable interrupts for alarm 1.
esp_err_t ds3231_alarm1_interr_disable (ds3231_handle_t ds3231_handle)
 Disable interrupts for alarm 1.
esp_err_t ds3231_alarm1_get_time (ds3231_handle_t ds3231_handle, ds3231_alarm1_match_t *interr, struct tm *timeinfo, ds3231_time_format_t *format)
 Read alarm 1 config (match mode and alarm time).
esp_err_t ds3231_alarm1_set_time (ds3231_handle_t ds3231_handle, ds3231_alarm1_match_t interr, struct tm timeinfo, ds3231_time_format_t format)
 Set the time of interrupt.
esp_err_t ds3231_alarm2_get_time (ds3231_handle_t ds3231_handle, ds3231_alarm2_match_t *interr, struct tm *timeinfo, ds3231_time_format_t *format)
 Read alarm 2 config (match mode and alarm time).
esp_err_t ds3231_alarm2_set_time (ds3231_handle_t ds3231_handle, ds3231_alarm2_match_t interr, struct tm timeinfo, ds3231_time_format_t format)
 Set the time of interrupt.
esp_err_t ds3231_alarm2_interr_enable (ds3231_handle_t ds3231_handle)
 Enable interrupts for alarm 2.
esp_err_t ds3231_alarm2_interr_disable (ds3231_handle_t ds3231_handle)
 Disable interrupts for alarm 2.
esp_err_t ds3231_alarm_get_flags (ds3231_handle_t ds3231_handle, ds3231_alarm_flags_t *interr)
 Get the flags of which alarm was triggered.
esp_err_t ds3231_alarm_clear_flags (ds3231_handle_t ds3231_handle, ds3231_alarm_flags_t interr)
 Clear interrupt flags.

Detailed Description

Public API for the DS3231 RTC driver.

Enumeration Type Documentation

◆ ds3231_alarm1_match_t

Match mode of alarm 1.

Enumerator
DS3231_ALARM1_INTERR_PER_SEC 

Alarm once per second

DS3231_ALARM1_INTERR_MATCH_SEC 

Alarm when seconds match

DS3231_ALARM1_INTERR_MATCH_MINSEC 

Alarm when minutes and seconds match

DS3231_ALARM1_INTERR_MATCH_HOURMINSEC 

Alarm when hours, minutes, and seconds match

DS3231_ALARM1_INTERR_HOURMINSECDAY 

Alarm when day of the week, hours, minutes, and seconds match

DS3231_ALARM1_INTERR_HOURMINSECDATE 

Alarm when date, hours, minutes, and seconds match

◆ ds3231_alarm2_match_t

Match mode of alarm 2.

Enumerator
DS3231_ALARM2_INTERR_PER_MIN 

Alarm once per minute

DS3231_ALARM2_INTERR_MATCH_MIN 

Alarm when minutes match

DS3231_ALARM2_INTERR_MATCH_HOURMIN 

Alarm when hours and minutes match

DS3231_ALARM2_INTERR_MATCH_HOURMINDATE 

Alarm when date, hours, and minutes match

DS3231_ALARM2_INTERR_HOURMINDAY 

Alarm when day of the week, hours, and minutes match

◆ ds3231_alarm_flags_t

Alarm flags which sets by the device when the time matches the alarm.

Enumerator
DS3231_ALARM_NO_INTERR 

No alarm has fired

DS3231_ALARM1_FLAG_INTERR 

Alarm 1 has fired

DS3231_ALARM2_FLAG_INTERR 

Alarm 2 has fired

DS3231_ALARM1_ALARM2_FLAGS_INTERR 

Both alarms have fired

◆ ds3231_alarms_t

Alarms whose interrupts are enabled.

Enumerator
DS3231_ALARM_NONE 

No alarm interrupts enabled

DS3231_ALARM_A1 

Alarm 1 interrupt enabled

DS3231_ALARM_A2 

Alarm 2 interrupt enabled

DS3231_ALARM_A1_A2 

Both alarm interrupts enabled

◆ ds3231_squarewave_freq_t

Square wave output on the INT/SQW pin.

Enumerator
DS3231_FREQ_1HZ 

1 Hz

DS3231_FREQ_1024HZ 

1.024 kHz

DS3231_FREQ_4096HZ 

4.096 kHz

DS3231_FREQ_8192HZ 

8.192 kHz

◆ ds3231_time_format_t

Time format of the device.

Enumerator
DS3231_TIME_FORMAT_12H 

12-hour format with AM/PM

DS3231_TIME_FORMAT_24H 

24-hour format

Function Documentation

◆ ds3231_alarm1_get_time()

esp_err_t ds3231_alarm1_get_time ( ds3231_handle_t ds3231_handle,
ds3231_alarm1_match_t * interr,
struct tm * timeinfo,
ds3231_time_format_t * format )

Read alarm 1 config (match mode and alarm time).

Note
Only fields relevant to the returned match mode are valid
Parameters
[in]ds3231_handleDevice handle
[out]interrAlarm match mode
[out]timeinfothe tm structure for time
[out]formatFormat in which the alarm hour is stored in the device. May be NULL
Returns
ESP_OK on success

◆ ds3231_alarm1_interr_disable()

esp_err_t ds3231_alarm1_interr_disable ( ds3231_handle_t ds3231_handle)

Disable interrupts for alarm 1.

Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_alarm1_interr_enable()

esp_err_t ds3231_alarm1_interr_enable ( ds3231_handle_t ds3231_handle)

Enable interrupts for alarm 1.

Note
You must turn off the square wave output with ds3231_squarewave_disable() before using alarm interrupts
Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_alarm1_set_time()

esp_err_t ds3231_alarm1_set_time ( ds3231_handle_t ds3231_handle,
ds3231_alarm1_match_t interr,
struct tm timeinfo,
ds3231_time_format_t format )

Set the time of interrupt.

Note
In the structure tm you can fill the necessarry values only
Warning
The formt must match the current time format (see ds3231_get_time_format())
Parameters
[in]ds3231_handleDevice handle
[in]interrNecessary interrupt matches
[in]timeinfothe tm structure for time
[in]formatFormat in which the alarm hour is stored in the device
Returns
ESP_OK on success

◆ ds3231_alarm2_get_time()

esp_err_t ds3231_alarm2_get_time ( ds3231_handle_t ds3231_handle,
ds3231_alarm2_match_t * interr,
struct tm * timeinfo,
ds3231_time_format_t * format )

Read alarm 2 config (match mode and alarm time).

Note
Only fields relevant to the returned match mode are valid
Parameters
[in]ds3231_handleDevice handle
[out]interrAlarm match mode
[out]timeinfothe tm structure for time
[out]formatFormat in which the alarm hour is stored in the device. May be NULL
Returns
ESP_OK on success

◆ ds3231_alarm2_interr_disable()

esp_err_t ds3231_alarm2_interr_disable ( ds3231_handle_t ds3231_handle)

Disable interrupts for alarm 2.

Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_alarm2_interr_enable()

esp_err_t ds3231_alarm2_interr_enable ( ds3231_handle_t ds3231_handle)

Enable interrupts for alarm 2.

Note
You must turn off the square wave output with ds3231_squarewave_disable() before using alarm interrupts
Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_alarm2_set_time()

esp_err_t ds3231_alarm2_set_time ( ds3231_handle_t ds3231_handle,
ds3231_alarm2_match_t interr,
struct tm timeinfo,
ds3231_time_format_t format )

Set the time of interrupt.

Note
In the structure tm you can fill the necessarry values only
Warning
The formt must match the current time format (see ds3231_get_time_format())
Parameters
[in]ds3231_handleDevice handle
[in]interrNecessary interrupt matches
[in]timeinfothe tm structure for time
[in]formatFormat in which the alarm hour is stored in the device
Returns
ESP_OK on success

◆ ds3231_alarm_clear_flags()

esp_err_t ds3231_alarm_clear_flags ( ds3231_handle_t ds3231_handle,
ds3231_alarm_flags_t interr )

Clear interrupt flags.

Parameters
[in]ds3231_handleDevice handle
[in]interrFlags to clear
Returns
ESP_OK on success

◆ ds3231_alarm_get_flags()

esp_err_t ds3231_alarm_get_flags ( ds3231_handle_t ds3231_handle,
ds3231_alarm_flags_t * interr )

Get the flags of which alarm was triggered.

Parameters
[in]ds3231_handleDevice handle
[out]interrFlag of the occurred interrupt
Returns
ESP_OK on success

◆ ds3231_alarm_interr_get_status()

esp_err_t ds3231_alarm_interr_get_status ( ds3231_handle_t ds3231_handle,
ds3231_alarms_t * interr )

Get which alarm interrupts are enabled.

Note
Parameters
[in]ds3231_handleDevice handle
[out]interrGet the enabled alarm interrupt
Returns
ESP_OK on success

◆ ds3231_create()

esp_err_t ds3231_create ( i2c_master_bus_handle_t i2c_bus,
ds3231_handle_t * ds3231_handle )

Initialize device handle.

Parameters
[in]i2c_busI2C bus handle
[out]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_delete()

void ds3231_delete ( ds3231_handle_t ds3231_handle)

Free device handle.

Parameters
[in]ds3231_handleDevice handle

◆ ds3231_get_aging()

esp_err_t ds3231_get_aging ( ds3231_handle_t ds3231_handle,
int8_t * age )

Get the aging offset.

Parameters
[in]ds3231_handleDevice handle
[out]ageAging offset
Returns
ESP_OK on success

◆ ds3231_get_temperature()

esp_err_t ds3231_get_temperature ( ds3231_handle_t ds3231_handle,
float * temp )

Read temperature from the chip.

Parameters
[in]ds3231_handleDevice handle
[out]tempTemperature, Celsius
Returns
ESP_OK on success

◆ ds3231_get_time()

esp_err_t ds3231_get_time ( ds3231_handle_t ds3231_handle,
struct tm * timeinfo,
ds3231_time_format_t * format )

Get the current date and time.

Note
The tm_isdst field is always sets to 0
This function doesn't check whether the time is valid. Use ds3231_get_time_valid() for it
Parameters
[in]ds3231_handleDevice handle
[out]timeinfoDate and time read from the device. Uses tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year and tm_wday
[out]formatFormat in which the time is stored in the device. May be NULL
Returns
ESP_OK on success

◆ ds3231_get_time_format()

esp_err_t ds3231_get_time_format ( ds3231_handle_t ds3231_handle,
ds3231_time_format_t * timeformat )

Get the current time format.

Parameters
[in]ds3231_handleDevice handle
[out]timeformatFormat of time
Returns
ESP_OK on success

◆ ds3231_get_time_valid()

esp_err_t ds3231_get_time_valid ( ds3231_handle_t ds3231_handle,
bool * time_valid )

Check validity of the time module saved.

Warning
The result is reliable only when battery is installed
Parameters
[in]ds3231_handleDevice handle
[out]time_validTrue if time is valid, false if not
Returns
ESP_OK on success

◆ ds3231_osc_battery_get_status()

esp_err_t ds3231_osc_battery_get_status ( ds3231_handle_t ds3231_handle,
bool * enabled )

Check whether the oscillator is enabled when running on battery or not.

Parameters
[in]ds3231_handleDevice handle
[out]enabledTrue if the oscillator is running on battery, false if it stops
Returns
ESP_OK on success

◆ ds3231_osc_battery_set_status()

esp_err_t ds3231_osc_battery_set_status ( ds3231_handle_t ds3231_handle,
bool enabled )

Enable or disable the oscillator when running on battery.

Parameters
[in]ds3231_handleDevice handle
[in]enabledTrue to keep the oscillator running on battery, false to stop
Returns
ESP_OK on success

◆ ds3231_set_aging()

esp_err_t ds3231_set_aging ( ds3231_handle_t ds3231_handle,
int8_t age )

Set the aging offset.

Parameters
[in]ds3231_handleDevice handle
[in]ageAging offset in range -128..127
Returns
ESP_OK on success

◆ ds3231_set_time()

esp_err_t ds3231_set_time ( ds3231_handle_t ds3231_handle,
struct tm timeinfo,
ds3231_time_format_t format )

Set current date time.

Note
Only years 2000-2099 are supported. The tm_yday and tm_isdst fields of the tm structure are ignored
Warning
The time format of the device is set by this function. If is_pm is NULL, the time will be stored in 24-hour format. Otherwise, it is stored in 12-hour format
Parameters
[in]ds3231_handleDevice handle
[in]timeinfoDate and time to set. Uses tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year and tm_wday. tm_hour must be 0-23 in 24-hour format and 1-12 in 12-hour format
[in]formatFormat in which the time is stored in the device
Returns
ESP_OK on success

◆ ds3231_squarewave_32khz_disable()

esp_err_t ds3231_squarewave_32khz_disable ( ds3231_handle_t ds3231_handle)

Disable 32 kHz output.

Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_squarewave_32khz_enable()

esp_err_t ds3231_squarewave_32khz_enable ( ds3231_handle_t ds3231_handle)

Enable 32 kHz output.

Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_squarewave_battery_disable()

esp_err_t ds3231_squarewave_battery_disable ( ds3231_handle_t ds3231_handle)

Disallow the device to run the square wave when powered from the battery.

Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_squarewave_battery_enable()

esp_err_t ds3231_squarewave_battery_enable ( ds3231_handle_t ds3231_handle)

Allow the device to run the square wave when powered from the battery.

Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_squarewave_disable()

esp_err_t ds3231_squarewave_disable ( ds3231_handle_t ds3231_handle)

Disable generating of the square wave.

Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_squarewave_enable()

esp_err_t ds3231_squarewave_enable ( ds3231_handle_t ds3231_handle)

Enable generating of the square wave.

Note
Set the square wave frequency with the ds3231_squarewave_set_freq() function first. Otherwise, the value currently stored in the device will be used.
Warning
Enabling the square wave, you automatically disable alarm interrupts
Parameters
[in]ds3231_handleDevice handle
Returns
ESP_OK on success

◆ ds3231_squarewave_get_freq()

esp_err_t ds3231_squarewave_get_freq ( ds3231_handle_t ds3231_handle,
ds3231_squarewave_freq_t * freq )

Get square wave frequency.

Parameters
[in]ds3231_handleDevice handle
[out]freqFrequency read from the device
Returns
ESP_OK on success

◆ ds3231_squarewave_set_freq()

esp_err_t ds3231_squarewave_set_freq ( ds3231_handle_t ds3231_handle,
ds3231_squarewave_freq_t freq )

Set square wave frequency.

Parameters
[in]ds3231_handleDevice handle
[in]freqFrequency to set
Returns
ESP_OK on success