Driver for the MAX31343 I2C real-time clock with integrated MEMS oscillator. More...

Detailed Description

Driver for the MAX31343 I2C real-time clock with integrated MEMS oscillator.

The driver can be used directly in an application or through the Wall-Clock Time Helper Functions module by adding this to your application's Makefile:

USEMODULE += walltime_impl_max31343

Implementation Status

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 64 Byte built-in User Storage Memory.

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

Files
file	max31343.h
	Driver interface for the MAX31343 I2C real-time clock.

Data Structures
struct	max31343_t
	Device descriptor for the MAX31343 RTC. More...

struct	max31343_params_t
	Configuration parameters for MAX31343 initialization. More...

Enumerations
enum	max31343_sqw_freq_t { MAX31343_SQW_1HZ = 0 , MAX31343_SQW_2HZ = 1 , MAX31343_SQW_4HZ = 2 , MAX31343_SQW_8HZ = 3 , MAX31343_SQW_16HZ = 4 , MAX31343_SQW_32HZ = 5 }
	Square-wave output frequency selection. More...

enum	max31343_ttsint_t { MAX31343_TTSINT_1S = 0x0 , MAX31343_TTSINT_2S = 0x1 , MAX31343_TTSINT_4S = 0x2 , MAX31343_TTSINT_8S = 0x3 , MAX31343_TTSINT_16S = 0x4 , MAX31343_TTSINT_32S = 0x5 , MAX31343_TTSINT_64S = 0x6 , MAX31343_TTSINT_128S = 0x7 }
	Automatic temperature conversion interval. More...

enum	max31343_trickle_res_t { MAX31343_TRICKLE_RES_3K = 0x0U , MAX31343_TRICKLE_RES_6K = 0x2U , MAX31343_TRICKLE_RES_11K = 0x3U }
	Trickle charger resistor selection. More...

Functions
int	max31343_init (max31343_t dev, const max31343_params_t params)
	Initialize MAX31343 device.

int	max31343_get_time (const max31343_t dev, struct tm time)
	Read current time from device.

int	max31343_set_time (const max31343_t dev, const struct tm time)
	Set current time on device.

int	max31343_poweron (const max31343_t *dev)
	Enable RTC oscillator (power on timekeeping).

int	max31343_poweroff (const max31343_t *dev)
	Disable RTC oscillator (stop timekeeping).

int	max31343_set_alarm (const max31343_t dev, const struct tm time)
	Set alarm time registers.

int	max31343_get_alarm (const max31343_t dev, struct tm time)
	Get the currently configured alarm time.

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

int	max31343_set_sqw (const max31343_t *dev, max31343_sqw_freq_t freq)
	Configure the square-wave (SQW) output frequency.

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

int	max31343_trickle_charge_enable (const max31343_t *dev, bool diode, max31343_trickle_res_t res)
	Enable the trickle charger.

int	max31343_trickle_charge_disable (const max31343_t *dev)
	Disable the trickle charger.

int	max31343_temp_set_automode (const max31343_t *dev, bool enable, max31343_ttsint_t ttsint)
	Configure automatic temperature conversion mode and interval.

Enumeration Type Documentation

◆ max31343_sqw_freq_t

enum max31343_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.

Definition at line 63 of file max31343.h.

◆ max31343_trickle_res_t

enum max31343_trickle_res_t

Trickle charger resistor selection.

Selects the series resistor in the trickle charging path. Corresponds to D_TRICKLE bits [1:0].

Enumerator
MAX31343_TRICKLE_RES_3K	3 kOhm
MAX31343_TRICKLE_RES_6K	6 kOhm
MAX31343_TRICKLE_RES_11K	11 kOhm

Definition at line 97 of file max31343.h.

◆ max31343_ttsint_t

enum max31343_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]).

Enumerator
MAX31343_TTSINT_1S	update temperature every 1s
MAX31343_TTSINT_2S	update temperature every 2s
MAX31343_TTSINT_4S	update temperature every 4s
MAX31343_TTSINT_8S	update temperature every 8s
MAX31343_TTSINT_16S	update temperature every 16s
MAX31343_TTSINT_32S	update temperature every 32s
MAX31343_TTSINT_64S	update temperature every 64s
MAX31343_TTSINT_128S	update temperature every 128s

Definition at line 80 of file max31343.h.

Function Documentation

◆ max31343_get_alarm()

int max31343_get_alarm	(	const max31343_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

◆ max31343_get_temp()

int max31343_get_temp	(	const max31343_t *	dev,
		int16_t *	temp_centi )

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

Example: 84.75°C -> 8475

Parameters

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

Return values

0	Success
-EIO	I2C communication error

◆ max31343_get_time()

int max31343_get_time	(	const max31343_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

◆ max31343_init()

int max31343_init	(	max31343_t *	dev,
		const max31343_params_t *	params )

Initialize MAX31343 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 max31343_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 max31343_set_time() before using max31343_get_time().

◆ max31343_poweroff()

int max31343_poweroff ( const max31343_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

◆ max31343_poweron()

int max31343_poweron ( const max31343_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

◆ max31343_set_alarm()

int max31343_set_alarm	(	const max31343_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 max31343_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 max31343_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

◆ max31343_set_alarm_int()

int max31343_set_alarm_int	(	const max31343_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 max31343_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

◆ max31343_set_sqw()

int max31343_set_sqw	(	const max31343_t *	dev,
		max31343_sqw_freq_t	freq )

Configure the square-wave (SQW) output frequency.

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

Parameters

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

Return values

0	Success
-ERANGE	Invalid frequency value
-EIO	I2C communication error

◆ max31343_set_time()

int max31343_set_time	(	const max31343_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

◆ max31343_temp_set_automode()

int max31343_temp_set_automode	(	const max31343_t *	dev,
		bool	enable,
		max31343_ttsint_t	ttsint )

Configure automatic temperature conversion mode and interval.

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

◆ max31343_trickle_charge_disable()

int max31343_trickle_charge_disable ( const max31343_t * dev )

Disable the trickle charger.

Parameters

[in] dev device descriptor

Return values

0	Success
-EIO	I2C communication error

◆ max31343_trickle_charge_enable()

int max31343_trickle_charge_enable	(	const max31343_t *	dev,
		bool	diode,
		max31343_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

Files

Data Structures

Enumerations

Functions

Enumeration Type Documentation

◆ max31343_sqw_freq_t

◆ max31343_trickle_res_t

◆ max31343_ttsint_t

Function Documentation

◆ max31343_get_alarm()

◆ max31343_get_temp()

◆ max31343_get_time()

◆ max31343_init()

◆ max31343_poweroff()

◆ max31343_poweron()

◆ max31343_set_alarm()

◆ max31343_set_alarm_int()

◆ max31343_set_sqw()

◆ max31343_set_time()

◆ max31343_temp_set_automode()

◆ max31343_trickle_charge_disable()

◆ max31343_trickle_charge_enable()