DS3231 Real Time Clock

Driver for the Maxim DS3231 extremely accurate RTC. More...

Detailed Description

Driver for the Maxim DS3231 extremely accurate RTC.

About

This module implements a device driver for Maxim DS3231 RTC.

Implementation status

The current implementation does only support reading and setting of time registers as well as reading the temperature register and configuring the aging offset.

Setting alarms and configuring the square wave output is not yet supported.

Files

file  ds3231_params.h
 Default configuration for DS3231 devices.
 
file  ds3231.h
 Interface definition for the Maxim DS3231 RTC.
 

Data Structures

struct  ds3231_t
 Device descriptor for DS3231 devices. More...
 
struct  ds3231_params_t
 Set of configuration parameters for DS3231 devices. More...
 

Macros

#define DS3231_I2C_ADDR   0x68
 Default address of DS3231 sensors.
 

Enumerations

enum  { DS3231_OPT_BAT_ENABLE = 0x01, DS3221_OPT_32KHZ_ENABLE = 0x02, DS3231_OPT_INTER_ENABLE = 0x04 }
 Configuration options. More...
 
enum  ds3231_alm_1_mode_t {
  DS3231_AL1_TRIG_PER_S = 0x0F, DS3231_AL1_TRIG_S = 0x0E, DS3231_AL1_TRIG_M_S = 0x0C, DS3231_AL1_TRIG_H_M_S = 0x08,
  DS3231_AL1_TRIG_D_H_M_S = 0x00
}
 Alarm trigger type of alarm 1 for DS3231 devices. More...
 
enum  ds3231_alm_2_mode_t { DS3231_AL2_TRIG_PER_M = 0x07, DS3231_AL2_TRIG_M = 0x06, DS3231_AL2_TRIG_H_M = 0x04, DS3231_AL2_TRIG_D_H_M_S = 0x00 }
 Alarm trigger type of alarm 2 for DS3231 devices. More...
 

Functions

int ds3231_init (ds3231_t *dev, const ds3231_params_t *params)
 Initialize the given DS3231 device. More...
 
int ds3231_get_time (const ds3231_t *dev, struct tm *time)
 Get date and time from the device. More...
 
int ds3231_set_time (const ds3231_t *dev, const struct tm *time)
 Set date and time of the device. More...
 
int ds3231_set_alarm_1 (const ds3231_t *dev, struct tm *time, ds3231_alm_1_mode_t trigger)
 Set alarm 1 of the device. More...
 
int ds3231_set_alarm_2 (const ds3231_t *dev, struct tm *time, ds3231_alm_2_mode_t trigger)
 Set alarm 2 of the device. More...
 
int ds3231_clear_alarm_1_flag (const ds3231_t *dev)
 Clear alarm 1 flag (A1F) More...
 
int ds3231_clear_alarm_2_flag (const ds3231_t *dev)
 Clear alarm 2 flag (A2F) More...
 
int ds3231_get_alarm_1_flag (const ds3231_t *dev, bool *flag)
 Get the state of alarm 1 flag (A1F) More...
 
int ds3231_get_alarm_2_flag (const ds3231_t *dev, bool *flag)
 Get the state of alarm 2 flag (A2F) More...
 
int ds3231_toggle_alarm_1 (const ds3231_t *dev, bool enable)
 Enable/Disable alarm 1 interrupt on the device. More...
 
int ds3231_toggle_alarm_2 (const ds3231_t *dev, bool enable)
 Enable/Disable alarm 2 interrupt on the device. More...
 
int ds3231_get_aging_offset (const ds3231_t *dev, int8_t *offset)
 Get the configured aging offset (see datasheet for more information) More...
 
int ds3231_set_aging_offset (const ds3231_t *dev, int8_t offset)
 Set the aging offset (see datasheet for more information) More...
 
int ds3231_get_temp (const ds3231_t *dev, int16_t *temp)
 Get temperature from the device. More...
 
int ds3231_enable_bat (const ds3231_t *dev)
 Enable the backup battery. More...
 
int ds3231_disable_bat (const ds3231_t *dev)
 Disable the backup battery. More...
 
#define DS3231_FLAG_ALARM_1   0x01
 Alarm flags returned by the ds3231_await_alarm function.
 
#define DS3231_FLAG_ALARM_2   0x02
 

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Configuration options.

Enumerator
DS3231_OPT_BAT_ENABLE 

enable backup battery on startup

DS3221_OPT_32KHZ_ENABLE 

enable 32KHz output

DS3231_OPT_INTER_ENABLE 

enable the interrupt control

Definition at line 60 of file ds3231.h.

◆ ds3231_alm_1_mode_t

Alarm trigger type of alarm 1 for DS3231 devices.

Enumerator
DS3231_AL1_TRIG_PER_S 

alarm once per second

DS3231_AL1_TRIG_S 

alarm when seconds match

DS3231_AL1_TRIG_M_S 

alarm when minutes and seconds match

DS3231_AL1_TRIG_H_M_S 

alarm when H/M/S match

DS3231_AL1_TRIG_D_H_M_S 

alarm when D/H/M/S match

Definition at line 69 of file ds3231.h.

◆ ds3231_alm_2_mode_t

Alarm trigger type of alarm 2 for DS3231 devices.

Enumerator
DS3231_AL2_TRIG_PER_M 

alarm once per minute

DS3231_AL2_TRIG_M 

alarm when minutes match

DS3231_AL2_TRIG_H_M 

alarm when hours and minutes match

DS3231_AL2_TRIG_D_H_M_S 

alarm when D/H/M match

Definition at line 80 of file ds3231.h.

Function Documentation

◆ ds3231_clear_alarm_1_flag()

int ds3231_clear_alarm_1_flag ( const ds3231_t dev)

Clear alarm 1 flag (A1F)

Parameters
[in]devDS3231 device descriptor
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_clear_alarm_2_flag()

int ds3231_clear_alarm_2_flag ( const ds3231_t dev)

Clear alarm 2 flag (A2F)

Parameters
[in]devDS3231 device descriptor
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_disable_bat()

int ds3231_disable_bat ( const ds3231_t dev)

Disable the backup battery.

Parameters
[in]devDS3231 device descriptor
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_enable_bat()

int ds3231_enable_bat ( const ds3231_t dev)

Enable the backup battery.

Parameters
[in]devDS3231 device descriptor
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_get_aging_offset()

int ds3231_get_aging_offset ( const ds3231_t dev,
int8_t *  offset 
)

Get the configured aging offset (see datasheet for more information)

Parameters
[in]devDS3231 device descriptor
[out]offsetaging offset
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_get_alarm_1_flag()

int ds3231_get_alarm_1_flag ( const ds3231_t dev,
bool *  flag 
)

Get the state of alarm 1 flag (A1F)

Note
This function is not needed when ds3231_await_alarm is used
Parameters
[in]devDS3231 device descriptor
[out]flagCurrent value of the flag
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_get_alarm_2_flag()

int ds3231_get_alarm_2_flag ( const ds3231_t dev,
bool *  flag 
)

Get the state of alarm 2 flag (A2F)

Note
This function is not needed when ds3231_await_alarm is used
Parameters
[in]devDS3231 device descriptor
[out]flagCurrent value of the flag
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_get_temp()

int ds3231_get_temp ( const ds3231_t dev,
int16_t *  temp 
)

Get temperature from the device.

Parameters
[in]devDS3231 device descriptor
[out]tempcurrent value of the temperature register [in centi °C]
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_get_time()

int ds3231_get_time ( const ds3231_t dev,
struct tm *  time 
)

Get date and time from the device.

Parameters
[in]devDS3231 device descriptor
[out]timecurrent date and time from on device
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_init()

int ds3231_init ( ds3231_t dev,
const ds3231_params_t params 
)

Initialize the given DS3231 device.

Parameters
[out]devdevice descriptor of the targeted device
[in]paramsdevice configuration
Returns
0 on success
-EIO if no DS3231 device was found

◆ ds3231_set_aging_offset()

int ds3231_set_aging_offset ( const ds3231_t dev,
int8_t  offset 
)

Set the aging offset (see datasheet for more information)

Parameters
[in]devDS3231 device descriptor
[in]offsetaging offset
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_set_alarm_1()

int ds3231_set_alarm_1 ( const ds3231_t dev,
struct tm *  time,
ds3231_alm_1_mode_t  trigger 
)

Set alarm 1 of the device.

Parameters
[in]devDS3231 device descriptor
[in]timetarget date and time
[in]triggeralarm 1 trigger type
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_set_alarm_2()

int ds3231_set_alarm_2 ( const ds3231_t dev,
struct tm *  time,
ds3231_alm_2_mode_t  trigger 
)

Set alarm 2 of the device.

Parameters
[in]devDS3231 device descriptor
[in]timetarget date and time
[in]triggeralarm 2 trigger type
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_set_time()

int ds3231_set_time ( const ds3231_t dev,
const struct tm *  time 
)

Set date and time of the device.

Parameters
[in]devDS3231 device descriptor
[in]timetarget date and time
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_toggle_alarm_1()

int ds3231_toggle_alarm_1 ( const ds3231_t dev,
bool  enable 
)

Enable/Disable alarm 1 interrupt on the device.

Parameters
[in]devDS3231 device descriptor
[in]enableTrue to enable alarm, false to disable it
Returns
0 on success
-EIO on I2C communication error

◆ ds3231_toggle_alarm_2()

int ds3231_toggle_alarm_2 ( const ds3231_t dev,
bool  enable 
)

Enable/Disable alarm 2 interrupt on the device.

Parameters
[in]devDS3231 device descriptor
[in]enableTrue to enable alarm, false to disable it
Returns
0 on success
-EIO on I2C communication error