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.

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.

int	ds3231_get_time (const ds3231_t dev, struct tm time)
	Get date and time from the device.

int	ds3231_set_time (const ds3231_t dev, const struct tm time)
	Set date and time of the device.

int	ds3231_set_alarm_1 (const ds3231_t dev, struct tm time, ds3231_alm_1_mode_t trigger)
	Set alarm 1 of the device.

int	ds3231_set_alarm_2 (const ds3231_t dev, struct tm time, ds3231_alm_2_mode_t trigger)
	Set alarm 2 of the device.

int	ds3231_clear_alarm_1_flag (const ds3231_t *dev)
	Clear alarm 1 flag (A1F)

int	ds3231_clear_alarm_2_flag (const ds3231_t *dev)
	Clear alarm 2 flag (A2F)

int	ds3231_get_alarm_1_flag (const ds3231_t dev, bool flag)
	Get the state of alarm 1 flag (A1F)

int	ds3231_get_alarm_2_flag (const ds3231_t dev, bool flag)
	Get the state of alarm 2 flag (A2F)

int	ds3231_toggle_alarm_1 (const ds3231_t *dev, bool enable)
	Enable/Disable alarm 1 interrupt on the device.

int	ds3231_toggle_alarm_2 (const ds3231_t *dev, bool enable)
	Enable/Disable alarm 2 interrupt on the device.

int	ds3231_get_aging_offset (const ds3231_t dev, int8_t offset)
	Get the configured aging offset (see datasheet for more information)

int	ds3231_set_aging_offset (const ds3231_t *dev, int8_t offset)
	Set the aging offset (see datasheet for more information)

int	ds3231_get_temp (const ds3231_t dev, int16_t temp)
	Get temperature from the device.

int	ds3231_enable_bat (const ds3231_t *dev)
	Enable the backup battery.

int	ds3231_disable_bat (const ds3231_t *dev)
	Disable the backup battery.

#define	DS3231_FLAG_ALARM_1 0x01
	Alarm flags returned by the ds3231_await_alarm function.

#define	DS3231_FLAG_ALARM_2 0x02

Macro Definition Documentation

◆ DS3231_FLAG_ALARM_1

#define DS3231_FLAG_ALARM_1 0x01

Alarm flags returned by the ds3231_await_alarm function.

Definition at line 53 of file ds3231.h.

◆ DS3231_FLAG_ALARM_2

#define DS3231_FLAG_ALARM_2 0x02

Definition at line 54 of file ds3231.h.

◆ DS3231_I2C_ADDR

#define DS3231_I2C_ADDR 0x68

Default address of DS3231 sensors.

Definition at line 47 of file ds3231.h.

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

enum 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

enum 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] dev DS3231 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] dev DS3231 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] dev DS3231 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] dev DS3231 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]	dev	DS3231 device descriptor
[out]	offset	aging 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]	dev	DS3231 device descriptor
[out]	flag	Current 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]	dev	DS3231 device descriptor
[out]	flag	Current 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]	dev	DS3231 device descriptor
[out]	temp	current 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]	dev	DS3231 device descriptor
[out]	time	current 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]	dev	device descriptor of the targeted device
[in]	params	device 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]	dev	DS3231 device descriptor
[in]	offset	aging 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]	dev	DS3231 device descriptor
[in]	time	target date and time
[in]	trigger	alarm 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]	dev	DS3231 device descriptor
[in]	time	target date and time
[in]	trigger	alarm 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]	dev	DS3231 device descriptor
[in]	time	target 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]	dev	DS3231 device descriptor
[in]	enable	True 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]	dev	DS3231 device descriptor
[in]	enable	True to enable alarm, false to disable it

Returns: 0 on success; -EIO on I2C communication error

Detailed Description

About

Implementation status

Files

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ DS3231_FLAG_ALARM_1

◆ DS3231_FLAG_ALARM_2

◆ DS3231_I2C_ADDR

Enumeration Type Documentation

◆ anonymous enum

◆ ds3231_alm_1_mode_t

◆ ds3231_alm_2_mode_t

Function Documentation

◆ ds3231_clear_alarm_1_flag()

◆ ds3231_clear_alarm_2_flag()

◆ ds3231_disable_bat()

◆ ds3231_enable_bat()

◆ ds3231_get_aging_offset()

◆ ds3231_get_alarm_1_flag()

◆ ds3231_get_alarm_2_flag()

◆ ds3231_get_temp()

◆ ds3231_get_time()

◆ ds3231_init()

◆ ds3231_set_aging_offset()

◆ ds3231_set_alarm_1()

◆ ds3231_set_alarm_2()

◆ ds3231_set_time()

◆ ds3231_toggle_alarm_1()

◆ ds3231_toggle_alarm_2()