Driver for the MAX313xx I2C real-time clock family. More...

Detailed Description

Driver for the MAX313xx I2C real-time clock family.

The driver can be used directly in an application or through the Wall-Clock Time Helper Functions module by adding one of the following lines to your application's Makefile (depending on the device you have):

USEMODULE += walltime_impl_max31331

USEMODULE += walltime_impl_max31343

Implementation Status and Supported Devices

The driver does not handle interrupts from the real-time clock. The application has to configure the appropriate pin with gpio_init_int and provide a callback.

Furthermore there is no support for the built-in User Storage Memory.

Only ALARM1 is supported, ALARM2 has limited capabilities compared to ALARM1. The Countdown Timer is also not supported yet.

The driver has support for the MAX31331 and MAX31343 devices, although not all features of each device is implemented.

Files
file	max313xx.h
	Driver interface for the MAX313xx I2C real-time clock.

Data Structures
struct	max313xx_t
	Device descriptor for the MAX313xx RTC. More...

struct	max313xx_params_t
	Configuration parameters for MAX313xx initialization. More...

Enumerations
enum	max313xx_sqw_freq_t { MAX313xx_SQW_1HZ = 0 , MAX313xx_SQW_2HZ = 1 , MAX313xx_SQW_4HZ = 2 , MAX313xx_SQW_8HZ = 3 , MAX313xx_SQW_16HZ = 4 , MAX313xx_SQW_32HZ = 5 }
	Square-wave output frequency selection. More...

enum	max313xx_ttsint_t { MAX313xx_TTSINT_1S = 0x0 , MAX313xx_TTSINT_2S = 0x1 , MAX313xx_TTSINT_4S = 0x2 , MAX313xx_TTSINT_8S = 0x3 , MAX313xx_TTSINT_16S = 0x4 , MAX313xx_TTSINT_32S = 0x5 , MAX313xx_TTSINT_64S = 0x6 , MAX313xx_TTSINT_128S = 0x7 }
	Automatic temperature conversion interval. More...

enum	max313xx_trickle_res_t { MAX313xx_TRICKLE_RES_3K = 0x0U , MAX313xx_TRICKLE_RES_6K = 0x2U , MAX313xx_TRICKLE_RES_11K = 0x3U }
	Trickle charger resistor selection. More...

Functions
int	max313xx_init (max313xx_t dev, const max313xx_params_t params)
	Initialize MAX313xx device.

int	max313xx_get_time (const max313xx_t dev, struct tm time)
	Read current time from device.

int	max313xx_set_time (const max313xx_t dev, const struct tm time)
	Set current time on device.

int	max313xx_poweron (const max313xx_t *dev)
	Enable RTC oscillator (power on timekeeping).

int	max313xx_poweroff (const max313xx_t *dev)
	Disable RTC oscillator (stop timekeeping).

int	max313xx_set_alarm (const max313xx_t dev, const struct tm time)
	Set alarm time registers.

int	max313xx_get_alarm (const max313xx_t dev, struct tm time)
	Get the currently configured alarm time.

int	max313xx_set_alarm_int (const max313xx_t *dev, bool enable)
	Enable or disable the alarm interrupt.

int	max313xx_set_sqw (const max313xx_t *dev, max313xx_sqw_freq_t freq)
	Configure the square-wave (SQW) output frequency.

int	max313xx_get_temp (const max313xx_t dev, int16_t temp_centi)
	Read temperature in centi-degrees Celsius (°C * 100)

int	max313xx_trickle_charge_enable (const max313xx_t *dev, bool diode, max313xx_trickle_res_t res)
	Enable the trickle charger.

int	max313xx_trickle_charge_disable (const max313xx_t *dev)
	Disable the trickle charger.

int	max313xx_temp_set_automode (const max313xx_t *dev, bool enable, max313xx_ttsint_t ttsint)
	Configure automatic temperature conversion mode and interval.

Enumeration Type Documentation

◆ max313xx_sqw_freq_t

enum max313xx_sqw_freq_t

Square-wave output frequency selection.

Selects the output frequency of the SQW pin. The exact mapping is defined by the MAX31343 datasheet.

Note: Only supported on the MAX31343.

Definition at line 71 of file max313xx.h.

◆ max313xx_trickle_res_t

enum max313xx_trickle_res_t

Trickle charger resistor selection.

Selects the series resistor in the trickle charging path. Corresponds to TRICKLE bits [1:2] for the MAX31331 and to D_TRICKLE bits [1:0] for the MAX31343.

Enumerator
MAX313xx_TRICKLE_RES_3K	3 kOhm
MAX313xx_TRICKLE_RES_6K	6 kOhm
MAX313xx_TRICKLE_RES_11K	11 kOhm

Definition at line 108 of file max313xx.h.

◆ max313xx_ttsint_t

enum max313xx_ttsint_t

Automatic temperature conversion interval.

Defines the interval for automatic temperature measurements when temperature AUTOMODE is enabled.

The values correspond to the TTSINT field (TS_Config[5:3]).

Note: Only supported on the MAX31343.

Enumerator
MAX313xx_TTSINT_1S	update temperature every 1s
MAX313xx_TTSINT_2S	update temperature every 2s
MAX313xx_TTSINT_4S	update temperature every 4s
MAX313xx_TTSINT_8S	update temperature every 8s
MAX313xx_TTSINT_16S	update temperature every 16s
MAX313xx_TTSINT_32S	update temperature every 32s
MAX313xx_TTSINT_64S	update temperature every 64s
MAX313xx_TTSINT_128S	update temperature every 128s

Definition at line 90 of file max313xx.h.

Function Documentation

◆ max313xx_get_alarm()

int max313xx_get_alarm	(	const max313xx_t *	dev,
		struct tm *	time )

Get the currently configured alarm time.

Note: This function does not check the masking bits. If masking bits are set, not all of the configured time parameters might be considered by the RTC for a match.

Parameters

[in]	dev	device descriptor
[out]	time	receives the stored alarm time

Return values

0	Success
-EIO	I2C communication error

◆ max313xx_get_temp()

int max313xx_get_temp	(	const max313xx_t *	dev,
		int16_t *	temp_centi )

Read temperature in centi-degrees Celsius (°C * 100)

Example: 84.75°C -> 8475

Note: Only supported on the MAX31343.

Parameters

[in]	dev	device descriptor
[out]	temp_centi	temperature in centi-degC

Return values

0	Success
-EIO	I2C communication error
-ENOTSUP	RTC variant does not have a temperature sensor

◆ max313xx_get_time()

int max313xx_get_time	(	const max313xx_t *	dev,
		struct tm *	time )

Read current time from device.

Parameters

[in]	dev	device descriptor
[out]	time	time structure to fill

Return values

0	Success
-EIO	I2C communication error or invalid time read from device

◆ max313xx_init()

int max313xx_init	(	max313xx_t *	dev,
		const max313xx_params_t *	params )

Initialize MAX313xx device.

This function initializes the device and checks the Oscillator Stop Flag (OSF). If OSF is set (indicating the oscillator was stopped, e.g., after power loss), the current time may be invalid and should be set using max313xx_set_time(). The OSF flag is automatically cleared when the time registers are written.

Note: After power-on or if the oscillator was stopped, the caller should check if the time is valid and set it if necessary.

Parameters

[out]	dev	device descriptor
[in]	params	device parameters

Return values

0	Success
-EINVAL	Invalid argument (NULL pointer)
-EIO	I2C communication error
-ENODATA	Oscillator was stopped; time is invalid. Call max313xx_set_time() before using max313xx_get_time().

◆ max313xx_poweroff()

int max313xx_poweroff ( const max313xx_t * dev )

Disable RTC oscillator (stop timekeeping).

Clears ENOSC bit in RTC_CFG1.

Parameters

[in] dev device descriptor

Return values

0	Success
-EIO	I2C communication error

◆ max313xx_poweron()

int max313xx_poweron ( const max313xx_t * dev )

Enable RTC oscillator (power on timekeeping).

Sets ENOSC bit in RTC_CFG1.

Parameters

[in] dev device descriptor

Return values

0	Success
-EIO	I2C communication error

◆ max313xx_set_alarm()

int max313xx_set_alarm	(	const max313xx_t *	dev,
		const struct tm *	time )

Set alarm time registers.

Writes the alarm time to the device. The alarm interrupt (A1IE) is disabled before writing and must be explicitly re-enabled afterwards using max313xx_set_alarm_int(), as required by the datasheet.

Note: Per datasheet requirement, the alarm interrupt (A1IE) must not be enabled until at least 1 second after calling this function. Use max313xx_set_alarm_int() after the required delay.

Parameters

[in]	dev	device descriptor
[in]	time	alarm time to store

Return values

0	Success
-ERANGE	Time values are out of supported range (year must be 2000-2099)
-EIO	I2C communication error

◆ max313xx_set_alarm_int()

int max313xx_set_alarm_int	(	const max313xx_t *	dev,
		bool	enable )

Enable or disable the alarm interrupt.

Controls the alarm interrupt enable bit (A1IE) in the interrupt enable register. Disabling the alarm also clears the alarm flag (A1F).

Note: When enabling the alarm after max313xx_set_alarm(), wait at least 1 second as required by the datasheet before calling this function.

Parameters

[in]	dev	device descriptor
[in]	enable	true to enable alarm interrupt, false to disable

Return values

0	Success
-EIO	I2C communication error

◆ max313xx_set_sqw()

int max313xx_set_sqw	(	const max313xx_t *	dev,
		max313xx_sqw_freq_t	freq )

Configure the square-wave (SQW) output frequency.

This function enables and configures the SQW output according to the selected frequency.

Note: Only supported on the MAX31343.

Parameters

[in]	dev	device descriptor
[in]	freq	square-wave frequency selection

Return values

0	Success
-ERANGE	Invalid frequency value
-EIO	I2C communication error
-ENOTSUP	RTC variant does not have a square wave output

◆ max313xx_set_time()

int max313xx_set_time	(	const max313xx_t *	dev,
		const struct tm *	time )

Set current time on device.

Note: The new time is set after one second. Reading back the time immediately will result in a wrong time.

Parameters

[in]	dev	device descriptor
[in]	time	time structure to set

Return values

0	Success
-ERANGE	Time values are out of supported range (year must be 2000-2099)
-EIO	I2C communication error

◆ max313xx_temp_set_automode()

int max313xx_temp_set_automode	(	const max313xx_t *	dev,
		bool	enable,
		max313xx_ttsint_t	ttsint )

Configure automatic temperature conversion mode and interval.

Note: Only supported on the MAX31343.

Parameters

[in]	dev	device descriptor
[in]	enable	true to set AUTOMODE=1, false to set AUTOMODE=0
[in]	ttsint	value written to TS_Config[5:3]

Return values

0	Success
-ERANGE	Invalid ttsint value
-EIO	I2C communication error
-ENOTSUP	RTC variant does not have a temperature sensor

◆ max313xx_trickle_charge_disable()

int max313xx_trickle_charge_disable ( const max313xx_t * dev )

Disable the trickle charger.

Parameters

[in] dev device descriptor

Return values

0	Success
-EIO	I2C communication error

◆ max313xx_trickle_charge_enable()

int max313xx_trickle_charge_enable	(	const max313xx_t *	dev,
		bool	diode,
		max313xx_trickle_res_t	res )

Enable the trickle charger.

The trickle charger can be used to slowly charge a supercapacitor or rechargeable backup battery connected to VBAT. The charging current is determined by the selected diode path and series resistor: I = (VCC - V_diode - V_BAT) / R

Parameters

[in]	dev	device descriptor
[in]	diode	diode path selection
[in]	res	series resistor selection

Return values

0	Success
-EIO	I2C communication error

Detailed Description

Implementation Status and Supported Devices

Files

Data Structures

Enumerations

Functions

Enumeration Type Documentation

◆ max313xx_sqw_freq_t

◆ max313xx_trickle_res_t

◆ max313xx_ttsint_t

Function Documentation

◆ max313xx_get_alarm()

◆ max313xx_get_temp()

◆ max313xx_get_time()

◆ max313xx_init()

◆ max313xx_poweroff()

◆ max313xx_poweron()

◆ max313xx_set_alarm()

◆ max313xx_set_alarm_int()

◆ max313xx_set_sqw()

◆ max313xx_set_time()

◆ max313xx_temp_set_automode()

◆ max313xx_trickle_charge_disable()

◆ max313xx_trickle_charge_enable()