Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
maxim_ds3231.h File Reference

Real-time clock control based on the DS3231 counter API. More...

#include <time.h>
#include <zephyr/drivers/counter.h>
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/sys/notify.h>
#include <zephyr/syscalls/maxim_ds3231.h>

Go to the source code of this file.

Data Structures

struct  maxim_ds3231_alarm
 Information defining the alarm configuration. More...
 
struct  maxim_ds3231_syncpoint
 Register the RTC clock against system clocks. More...
 

Macros

#define MAXIM_DS3231_ALARM1   BIT(0)
 Bit in ctrl or ctrl_stat associated with alarm 1.
 
#define MAXIM_DS3231_ALARM2   BIT(1)
 Bit in ctrl or ctrl_stat associated with alarm 2.
 
#define MAXIM_DS3231_REG_CTRL_A1IE   MAXIM_DS3231_ALARM1
 ctrl bit for alarm 1 interrupt enable.
 
#define MAXIM_DS3231_REG_CTRL_A2IE   MAXIM_DS3231_ALARM2
 ctrl bit for alarm 2 interrupt enable.
 
#define MAXIM_DS3231_REG_CTRL_INTCN   BIT(2)
 ctrl bit for ISQ functionality.
 
#define MAXIM_DS3231_REG_CTRL_RS_Pos   3
 ctrl bit offset for square wave output frequency.
 
#define MAXIM_DS3231_REG_CTRL_RS_Msk   (0x03 << MAXIM_DS3231_REG_CTRL_RS_Pos)
 ctrl mask to isolate RS bits.
 
#define MAXIM_DS3231_REG_CTRL_RS_1Hz   0x00
 ctrl RS field value for 1 Hz square wave.
 
#define MAXIM_DS3231_REG_CTRL_RS_1KiHz   0x01
 ctrl RS field value for 1024 Hz square wave.
 
#define MAXIM_DS3231_REG_CTRL_RS_4KiHz   0x02
 ctrl RS field value for 4096 Hz square wave.
 
#define MAXIM_DS3231_REG_CTRL_RS_8KiHz   0x03
 ctrl RS field value for 8192 Hz square wave.
 
#define MAXIM_DS3231_REG_CTRL_CONV   BIT(5)
 ctrl bit to write to trigger temperature conversion.
 
#define MAXIM_DS3231_REG_CTRL_BBSQW   BIT(6)
 ctrl bit to write to enable square wave output in battery mode.
 
#define MAXIM_DS3231_REG_CTRL_EOSCn   BIT(7),
 ctrl bit to write to disable the oscillator.
 
#define MAXIM_DS3231_REG_STAT_A1F   MAXIM_DS3231_ALARM1
 ctrl_stat bit indicating alarm1 has triggered.
 
#define MAXIM_DS3231_REG_STAT_A2F   MAXIM_DS3231_ALARM2
 ctrl_stat bit indicating alarm2 has triggered.
 
#define MAXIM_DS3231_REG_STAT_BSY   BIT(2)
 Flag indicating a temperature conversion is in progress.
 
#define MAXIM_DS3231_REG_STAT_EN32kHz   BIT(3)
 Set to enable 32 KiHz open drain signal.
 
#define MAXIM_DS3231_REG_STAT_OSF   BIT(7)
 Flag indicating the oscillator has been off since last cleared.
 
#define MAXIM_DS3231_ALARM_FLAGS_IGNSE   BIT(0)
 Control alarm behavior on match in seconds field.
 
#define MAXIM_DS3231_ALARM_FLAGS_IGNMN   BIT(1)
 Control alarm behavior on match in minutes field.
 
#define MAXIM_DS3231_ALARM_FLAGS_IGNHR   BIT(2)
 Control alarm behavior on match in hours field.
 
#define MAXIM_DS3231_ALARM_FLAGS_IGNDA   BIT(3)
 Control alarm behavior on match in day/date field.
 
#define MAXIM_DS3231_ALARM_FLAGS_DOW   BIT(4)
 Control match on day of week versus day of month.
 
#define MAXIM_DS3231_ALARM_FLAGS_AUTODISABLE   BIT(7)
 Indicates that the alarm should be disabled once it fires.
 

Typedefs

typedef void(* maxim_ds3231_alarm_callback_handler_t) (const struct device *dev, uint8_t id, uint32_t syncclock, void *user_data)
 Signature for DS3231 alarm callbacks.
 
typedef void(* maxim_ds3231_notify_callback) (const struct device *dev, struct sys_notify *notify, int res)
 Signature used to notify a user of the DS3231 that an asynchronous operation has completed.
 

Functions

static uint32_t maxim_ds3231_read_syncclock (const struct device *dev)
 Read the local synchronization clock.
 
static uint32_t maxim_ds3231_syncclock_frequency (const struct device *dev)
 Get the frequency of the synchronization clock.
 
int maxim_ds3231_ctrl_update (const struct device *dev, uint8_t set_bits, uint8_t clear_bits)
 Set and clear specific bits in the control register.
 
int maxim_ds3231_stat_update (const struct device *dev, uint8_t set_bits, uint8_t clear_bits)
 Read the ctrl_stat register then set and clear bits in it.
 
int maxim_ds3231_get_alarm (const struct device *dev, uint8_t id, struct maxim_ds3231_alarm *cfg)
 Read a DS3231 alarm configuration.
 
int maxim_ds3231_set_alarm (const struct device *dev, uint8_t id, const struct maxim_ds3231_alarm *cfg)
 Configure a DS3231 alarm.
 
int maxim_ds3231_synchronize (const struct device *dev, struct sys_notify *notify)
 Synchronize the RTC against the local clock.
 
int maxim_ds3231_req_syncpoint (const struct device *dev, struct k_poll_signal *signal)
 Request to update the synchronization point.
 
int maxim_ds3231_get_syncpoint (const struct device *dev, struct maxim_ds3231_syncpoint *syncpoint)
 Retrieve the most recent synchronization point.
 
int maxim_ds3231_set (const struct device *dev, const struct maxim_ds3231_syncpoint *syncpoint, struct sys_notify *notify)
 Set the RTC to a time consistent with the provided synchronization.
 
int maxim_ds3231_check_alarms (const struct device *dev)
 Check for and clear flags indicating that an alarm has fired.
 

Detailed Description

Real-time clock control based on the DS3231 counter API.

The Maxim DS3231 is a high-precision real-time clock with temperature-compensated crystal oscillator and support for configurable alarms.

The core Zephyr API to this device is as a counter, with the following limitations:

  • counter_read() and counter_*_alarm() cannot be invoked from interrupt context, as they require communication with the device over an I2C bus.
  • many other counter APIs, such as start/stop/set_top_value are not supported as the clock is always running.
  • two alarm channels are supported but are not equally capable: channel 0 supports alarms at 1 s resolution, while channel 1 supports alarms at 1 minute resolution.

Most applications for this device will need to use the extended functionality exposed by this header to access the real-time-clock features. The majority of these functions must be invoked from supervisor mode.

Macro Definition Documentation

◆ MAXIM_DS3231_ALARM1

#define MAXIM_DS3231_ALARM1   BIT(0)

Bit in ctrl or ctrl_stat associated with alarm 1.

◆ MAXIM_DS3231_ALARM2

#define MAXIM_DS3231_ALARM2   BIT(1)

Bit in ctrl or ctrl_stat associated with alarm 2.

◆ MAXIM_DS3231_ALARM_FLAGS_AUTODISABLE

#define MAXIM_DS3231_ALARM_FLAGS_AUTODISABLE   BIT(7)

Indicates that the alarm should be disabled once it fires.

Set the flag in the maxim_ds3231_alarm_configuration::alarm_flags field to cause the alarm to be disabled when the interrupt fires, prior to invoking the corresponding handler.

Leave false to allow the alarm to remain enabled so it will fire again on the next match.

◆ MAXIM_DS3231_ALARM_FLAGS_DOW

#define MAXIM_DS3231_ALARM_FLAGS_DOW   BIT(4)

Control match on day of week versus day of month.

Set the flag to match on day of week; clear it to match on day of month.

Bit maps to DY/DTn in corresponding maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_ALARM_FLAGS_IGNDA

#define MAXIM_DS3231_ALARM_FLAGS_IGNDA   BIT(3)

Control alarm behavior on match in day/date field.

If clear the alarm fires only when the RTC day/date matches the alarm day/date, mediated by MAXIM_DS3231_ALARM_FLAGS_DAY. The bits for IGNHR, IGNMN, and IGNSE must be clear

If set the alarm day/date field is ignored and an alarm will be triggered based on IGNHR, IGNMN, and IGNSE.

Bit maps to A1M4 or A2M4 and is used in maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_ALARM_FLAGS_IGNHR

#define MAXIM_DS3231_ALARM_FLAGS_IGNHR   BIT(2)

Control alarm behavior on match in hours field.

If clear the alarm fires only when the RTC hours matches the alarm hours. The bits for IGNMN and IGNSE must be clear.

If set the alarm hours field is ignored and alarms will be triggered based on IGNMN and IGNSE. The bit for IGNDA must be set.

Bit maps to A1M3 or A2M3 and is used in maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_ALARM_FLAGS_IGNMN

#define MAXIM_DS3231_ALARM_FLAGS_IGNMN   BIT(1)

Control alarm behavior on match in minutes field.

If clear the alarm fires only when the RTC minutes matches the alarm minutes. The bit for IGNSE must be clear.

If set the alarm minutes field is ignored and alarms will be triggered based on IGNSE. The bits for IGNHR and IGNDA must both be set.

Bit maps to A1M2 or A2M2 and is used in maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_ALARM_FLAGS_IGNSE

#define MAXIM_DS3231_ALARM_FLAGS_IGNSE   BIT(0)

Control alarm behavior on match in seconds field.

If clear the alarm fires only when the RTC seconds matches the alarm seconds.

If set the alarm seconds field is ignored and an alarm will be triggered every second. The bits for IGNMN, IGNHR, and IGNDA must all be set.

This bit must be clear for the second alarm instance.

Bit maps to A1M1 and is used in maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_REG_CTRL_A1IE

#define MAXIM_DS3231_REG_CTRL_A1IE   MAXIM_DS3231_ALARM1

ctrl bit for alarm 1 interrupt enable.

◆ MAXIM_DS3231_REG_CTRL_A2IE

#define MAXIM_DS3231_REG_CTRL_A2IE   MAXIM_DS3231_ALARM2

ctrl bit for alarm 2 interrupt enable.

◆ MAXIM_DS3231_REG_CTRL_BBSQW

#define MAXIM_DS3231_REG_CTRL_BBSQW   BIT(6)

ctrl bit to write to enable square wave output in battery mode.

◆ MAXIM_DS3231_REG_CTRL_CONV

#define MAXIM_DS3231_REG_CTRL_CONV   BIT(5)

ctrl bit to write to trigger temperature conversion.

◆ MAXIM_DS3231_REG_CTRL_EOSCn

#define MAXIM_DS3231_REG_CTRL_EOSCn   BIT(7),

ctrl bit to write to disable the oscillator.

◆ MAXIM_DS3231_REG_CTRL_INTCN

#define MAXIM_DS3231_REG_CTRL_INTCN   BIT(2)

ctrl bit for ISQ functionality.

When clear the ISW signal provides a square wave. When set the ISW signal indicates alarm events.

Note
The driver expects to be able to control this bit.

◆ MAXIM_DS3231_REG_CTRL_RS_1Hz

#define MAXIM_DS3231_REG_CTRL_RS_1Hz   0x00

ctrl RS field value for 1 Hz square wave.

◆ MAXIM_DS3231_REG_CTRL_RS_1KiHz

#define MAXIM_DS3231_REG_CTRL_RS_1KiHz   0x01

ctrl RS field value for 1024 Hz square wave.

◆ MAXIM_DS3231_REG_CTRL_RS_4KiHz

#define MAXIM_DS3231_REG_CTRL_RS_4KiHz   0x02

ctrl RS field value for 4096 Hz square wave.

◆ MAXIM_DS3231_REG_CTRL_RS_8KiHz

#define MAXIM_DS3231_REG_CTRL_RS_8KiHz   0x03

ctrl RS field value for 8192 Hz square wave.

◆ MAXIM_DS3231_REG_CTRL_RS_Msk

#define MAXIM_DS3231_REG_CTRL_RS_Msk   (0x03 << MAXIM_DS3231_REG_CTRL_RS_Pos)

ctrl mask to isolate RS bits.

◆ MAXIM_DS3231_REG_CTRL_RS_Pos

#define MAXIM_DS3231_REG_CTRL_RS_Pos   3

ctrl bit offset for square wave output frequency.

Note
The driver will control the content of this field.

◆ MAXIM_DS3231_REG_STAT_A1F

#define MAXIM_DS3231_REG_STAT_A1F   MAXIM_DS3231_ALARM1

ctrl_stat bit indicating alarm1 has triggered.

If an alarm callback handler is registered this bit is cleared prior to invoking the callback with the flags indicating which alarms are ready.

◆ MAXIM_DS3231_REG_STAT_A2F

#define MAXIM_DS3231_REG_STAT_A2F   MAXIM_DS3231_ALARM2

ctrl_stat bit indicating alarm2 has triggered.

If an alarm callback handler is registered this bit is cleared prior to invoking the callback with the flags indicating which alarms are ready.

◆ MAXIM_DS3231_REG_STAT_BSY

#define MAXIM_DS3231_REG_STAT_BSY   BIT(2)

Flag indicating a temperature conversion is in progress.

◆ MAXIM_DS3231_REG_STAT_EN32kHz

#define MAXIM_DS3231_REG_STAT_EN32kHz   BIT(3)

Set to enable 32 KiHz open drain signal.

Note
This is a control bit, though it is positioned within the ctrl_stat register which otherwise contains status bits.

◆ MAXIM_DS3231_REG_STAT_OSF

#define MAXIM_DS3231_REG_STAT_OSF   BIT(7)

Flag indicating the oscillator has been off since last cleared.