ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
ds3231.h
Go to the documentation of this file.
1#pragma once
2
5#include "esphome/core/hal.h"
8
9#ifdef USE_BINARY_SENSOR
11#endif
12
13namespace esphome::ds3231 {
14
24
32
35class DS3231Component final : public Component, public i2c::I2CDevice {
36 public:
38 static constexpr size_t CALENDAR_LEN = 7;
39
40 void setup() override;
41 void loop() override;
42 void dump_config() override;
43
44 // ---- Configuration (set from codegen) ----
50 void set_battery_backed_square_wave(bool enabled) { this->battery_backed_square_wave_ = enabled ? 1 : 0; }
51 void set_output_32khz_config(bool enabled) { this->output_32khz_ = enabled ? 1 : 0; }
52 void set_aging_offset_config(int8_t offset) {
53 this->aging_offset_ = offset;
54 this->aging_offset_configured_ = true;
55 }
56 void set_auto_clear_alarms(bool auto_clear) { this->auto_clear_alarms_ = auto_clear; }
57 void set_alarm_check_interval(uint32_t interval) { this->alarm_check_interval_ = interval; }
58 void set_monitor_alarms(bool monitor) { this->monitor_alarms_ = monitor; }
59
61 template<typename F> void add_on_alarm_callback(F &&callback) {
62 this->alarm_callback_.add(std::forward<F>(callback));
63 }
64
65#ifdef USE_BINARY_SENSOR
67 SUB_BINARY_SENSOR(alarm_2)
68 SUB_BINARY_SENSOR(oscillator_stopped)
69#endif
70
71 // ---- Clock registers (used by the time platform) ----
73 bool read_calendar(uint8_t *raw);
75 bool write_calendar(const uint8_t *raw);
76
77 // ---- Temperature ----
78 bool read_temperature(float &out);
80
81 // ---- Alarms ----
83 void set_alarm_1(AlarmMode mode, uint8_t second, uint8_t minute, uint8_t hour, uint8_t day_of_month,
84 uint8_t day_of_week, bool enabled);
86 void set_alarm_2(AlarmMode mode, uint8_t minute, uint8_t hour, uint8_t day_of_month, uint8_t day_of_week,
87 bool enabled);
89 void enable_alarm(uint8_t alarm);
90 void disable_alarm(uint8_t alarm) { this->set_alarm_enabled_(alarm, false); }
92 void clear_alarm(uint8_t alarm);
94 bool is_alarm_triggered(uint8_t alarm);
95
96 // ---- Outputs and calibration ----
100 void disable_square_wave();
101 void set_output_32khz(bool enabled);
103 void set_aging_offset(int8_t offset);
104
105 protected:
106 static constexpr uint8_t CONTROL_A1IE = 0x01;
107 static constexpr uint8_t CONTROL_A2IE = 0x02;
108 static constexpr uint8_t CONTROL_INTCN = 0x04;
109 static constexpr uint8_t CONTROL_RS_MASK = 0x18;
110 static constexpr uint8_t CONTROL_RS_SHIFT = 3;
111 static constexpr uint8_t CONTROL_CONV = 0x20;
112 static constexpr uint8_t CONTROL_BBSQW = 0x40;
113 static constexpr uint8_t CONTROL_EOSC = 0x80;
114
115 static constexpr uint8_t STATUS_A1F = 0x01;
116 static constexpr uint8_t STATUS_A2F = 0x02;
117 static constexpr uint8_t STATUS_BSY = 0x04;
118 static constexpr uint8_t STATUS_EN32KHZ = 0x08;
119 static constexpr uint8_t STATUS_OSF = 0x80;
120 static constexpr uint8_t STATUS_FLAGS = STATUS_A1F | STATUS_A2F | STATUS_OSF;
121
123 static constexpr uint32_t ALARM_PULSE_TIMEOUT_ID = 0;
124
125 static void interrupt_handler(DS3231Component *arg);
126
130 bool update_control_(uint8_t mask, uint8_t value);
132 bool write_status_(uint8_t clear);
133 bool write_aging_offset_(int8_t offset);
135 bool clear_alarm_flag_(uint8_t alarm);
136 void set_alarm_enabled_(uint8_t alarm, bool enabled);
138 void write_alarm_(uint8_t alarm, const uint8_t *regs, size_t len, bool enabled);
140 void check_alarms_();
141 void publish_alarm_state_(uint8_t alarm, bool state);
143
146
148 uint8_t control_reg_{0};
149 uint8_t status_reg_{0};
150 int8_t aging_offset_{0};
154 int8_t output_32khz_{-1};
158 bool monitor_alarms_{false};
160 bool alarm_active_[2]{false, false};
161};
162
163} // namespace esphome::ds3231
BedjetMode mode
BedJet operating mode.
uint8_t raw[35]
Definition bl0939.h:0
uint16_le_t frequency
Definition bl0942.h:6
Hub for a single DS3231 real-time clock.
Definition ds3231.h:35
void enable_square_wave(SquareWaveFrequency frequency)
Switch INT/SQW to a square-wave output at frequency. Alarms then no longer drive the pin.
Definition ds3231.cpp:410
void write_alarm_(uint8_t alarm, const uint8_t *regs, size_t len, bool enabled)
Write the alarm registers, clear the stale flag and set the interrupt enable.
Definition ds3231.cpp:285
void set_output_32khz(bool enabled)
Definition ds3231.cpp:430
static constexpr uint8_t STATUS_FLAGS
Definition ds3231.h:120
static constexpr uint8_t STATUS_A1F
Definition ds3231.h:115
static constexpr uint8_t STATUS_OSF
Definition ds3231.h:119
static constexpr uint8_t CONTROL_A2IE
Definition ds3231.h:107
void set_aging_offset(int8_t offset)
Aging offset in LSB (about 0.1 ppm each at 25 degC); positive values slow the clock down.
Definition ds3231.cpp:439
bool write_status_(uint8_t clear)
Write the status register, clearing the flags in clear (writing 1 to a flag leaves it unchanged).
Definition ds3231.cpp:471
static constexpr uint8_t CONTROL_BBSQW
Definition ds3231.h:112
void set_square_wave_frequency(SquareWaveFrequency frequency)
Definition ds3231.h:46
static constexpr uint8_t CONTROL_RS_SHIFT
Definition ds3231.h:110
void check_alarms_()
Read the flags, fire triggers and update the binary sensors.
Definition ds3231.cpp:349
SquareWaveFrequency square_wave_frequency_
Definition ds3231.h:151
void clear_alarm(uint8_t alarm)
Clear the alarm flag, which also releases the INT/SQW line.
Definition ds3231.cpp:322
bool write_aging_offset_(int8_t offset)
Definition ds3231.cpp:478
static constexpr uint8_t CONTROL_A1IE
Definition ds3231.h:106
static constexpr uint8_t CONTROL_INTCN
Definition ds3231.h:108
bool read_temperature(float &out)
Definition ds3231.cpp:190
static void interrupt_handler(DS3231Component *arg)
Definition ds3231.cpp:45
static constexpr uint8_t STATUS_BSY
Definition ds3231.h:117
SUB_BINARY_SENSOR(alarm_1) SUB_BINARY_SENSOR(alarm_2) SUB_BINARY_SENSOR(oscillator_stopped) bool read_calendar(uint8_t *raw)
Read the calendar registers into raw. Fails if the oscillator was stopped since the time was last set...
static constexpr uint8_t STATUS_A2F
Definition ds3231.h:116
LazyCallbackManager< void(uint8_t)> alarm_callback_
Definition ds3231.h:145
void enable_alarm(uint8_t alarm)
Enable alarm. A match from while it was disabled is cleared first, so only the next one fires.
Definition ds3231.cpp:315
void set_output_32khz_config(bool enabled)
Definition ds3231.h:51
void disable_alarm(uint8_t alarm)
Definition ds3231.h:90
void set_alarm_2(AlarmMode mode, uint8_t minute, uint8_t hour, uint8_t day_of_month, uint8_t day_of_week, bool enabled)
Program alarm 2 (minute resolution, fires at second 00).
Definition ds3231.cpp:254
void set_aging_offset_config(int8_t offset)
Definition ds3231.h:52
static constexpr uint8_t STATUS_EN32KHZ
Definition ds3231.h:118
static constexpr uint8_t CONTROL_RS_MASK
Definition ds3231.h:109
static constexpr uint8_t CONTROL_EOSC
Definition ds3231.h:113
InternalGPIOPin * interrupt_pin_
Definition ds3231.h:144
void set_interrupt_pin(InternalGPIOPin *pin)
Definition ds3231.h:45
static constexpr uint32_t ALARM_PULSE_TIMEOUT_ID
Scheduler ids: one pulse timer per alarm (id + alarm - 1).
Definition ds3231.h:123
void set_alarm_enabled_(uint8_t alarm, bool enabled)
Definition ds3231.cpp:299
bool read_control_status_()
Read the control and status registers into the cached copies. Sets the warning flag on failure.
Definition ds3231.cpp:453
void set_auto_clear_alarms(bool auto_clear)
Definition ds3231.h:56
bool update_control_(uint8_t mask, uint8_t value)
Replace the bits in mask of the control register with value, on the chip and in the cache.
Definition ds3231.cpp:462
int8_t battery_backed_square_wave_
-1: leave the chip as it is, 0: off, 1: on.
Definition ds3231.h:153
void disable_square_wave()
Switch INT/SQW back to the (active-low) alarm interrupt output.
Definition ds3231.cpp:422
void set_alarm_1(AlarmMode mode, uint8_t second, uint8_t minute, uint8_t hour, uint8_t day_of_month, uint8_t day_of_week, bool enabled)
Program alarm 1. day_of_month is used in MONTHLY mode, day_of_week (1 = Sunday) in WEEKLY mode.
Definition ds3231.cpp:219
static constexpr uint8_t CONTROL_CONV
Definition ds3231.h:111
void set_monitor_alarms(bool monitor)
Definition ds3231.h:58
void set_alarm_check_interval(uint32_t interval)
Definition ds3231.h:57
void set_battery_backed_square_wave(bool enabled)
Definition ds3231.h:50
bool alarm_active_[2]
Set while an alarm flag has been reported, so a latched flag fires its trigger only once.
Definition ds3231.h:160
bool is_alarm_triggered(uint8_t alarm)
True while the alarm flag of alarm (1 or 2) is set on the chip.
Definition ds3231.cpp:343
void add_on_alarm_callback(F &&callback)
Register a void(uint8_t alarm) callback that runs when an enabled alarm (1 or 2) matches.
Definition ds3231.h:61
void publish_alarm_state_(uint8_t alarm, bool state)
Definition ds3231.cpp:394
bool write_calendar(const uint8_t *raw)
Write the calendar registers from raw and clear the oscillator-stop flag.
Definition ds3231.cpp:169
bool clear_alarm_flag_(uint8_t alarm)
Clear the flag of alarm and report it off. Returns false (state unchanged) if that fails.
Definition ds3231.cpp:324
static constexpr size_t CALENDAR_LEN
Seconds through year, the 7-byte BCD calendar the time platform decodes with time::DS_BCD_CALENDAR.
Definition ds3231.h:38
This Class provides the methods to read/write bytes from/to an i2c device.
Definition i2c.h:144
uint8_t second
uint8_t minute
uint8_t hour
bool state
Definition fan.h:2
std::vector< uint8_t > & out
Definition gif.cpp:49
AlarmMode
When an alarm fires. Alarm 1 supports every mode, alarm 2 has no seconds register and so no EVERY_SEC...
Definition ds3231.h:16
@ ALARM_MODE_WEEKLY
When day of week, hours, minutes (and seconds) match.
Definition ds3231.h:22
@ ALARM_MODE_EVERY_SECOND
Alarm 1 only.
Definition ds3231.h:17
@ ALARM_MODE_DAILY
When hours, minutes (and seconds) match.
Definition ds3231.h:20
@ ALARM_MODE_MONTHLY
When date, hours, minutes (and seconds) match.
Definition ds3231.h:21
@ ALARM_MODE_EVERY_MINUTE
Alarm 1: when the seconds match. Alarm 2: at second 00 of every minute.
Definition ds3231.h:18
@ ALARM_MODE_HOURLY
When minutes (and seconds) match.
Definition ds3231.h:19
SquareWaveFrequency
Frequency of the INT/SQW pin when it is a square-wave output (RS2:RS1 in the control register).
Definition ds3231.h:26
@ SQUARE_WAVE_4096HZ
Definition ds3231.h:29
@ SQUARE_WAVE_8192HZ
Definition ds3231.h:30
@ SQUARE_WAVE_1024HZ
Definition ds3231.h:28
uint32_t value
Definition hal.cpp:41
const void size_t len
Definition hal.h:68
static void uint32_t