I2C real-time-clock driver (DS1307 / DS3231) - a battery-backed time source. More...

#include <stddef.h>
#include <stdint.h>

Macros
#define	RTC_REG_COUNT 7
	Number of time registers read from the RTC (seconds..year).

Functions
bool	rtc_regs_to_epoch (const uint8_t regs[RTC_REG_COUNT], uint32_t *epoch)
	Convert the 7 raw RTC time registers (BCD: sec, min, hour, dow, date, month, year) to a Unix timestamp. Pure - no I2C. Handles both 24-hour and 12-hour (AM/PM) hour encodings and masks the DS1307 clock-halt / DS3231 century bits.

void	rtc_epoch_to_regs (uint32_t epoch, uint8_t regs[RTC_REG_COUNT])
	Convert a Unix timestamp to the 7 RTC time registers (BCD, 24-hour). Pure - no I2C. The day-of-week register is filled (1=Mon..7=Sun) for completeness.

bool	rtc_begin ()
	Initialize the I2C bus for the RTC.

uint32_t	rtc_read_epoch ()
	Read the current time from the RTC over I2C.

bool	rtc_set_epoch (uint32_t epoch)
	Set the RTC to `epoch` over I2C.

uint32_t	rtc_time_source ()
	A TimeSourceFn wrapper (returns rtc_read_epoch()) to register with detws_time_source_add().

Detailed Description

I2C real-time-clock driver (DS1307 / DS3231) - a battery-backed time source.

A DS1307 or DS3231 keeps the wall-clock time running from a coin cell when the ESP32 is off or offline. This reads it (and can set it) over I2C, and plugs into the time-source chain so detws_time_now() - and the NTP server - can use it: GPS when locked, the RTC when GPS and the internet are gone, upstream NTP otherwise. Both chips expose the same seven BCD time registers at address 0x68, so one driver serves both. Zero heap; gated by DETWS_ENABLE_RTC.

The BCD <-> Unix-epoch conversion (12/24-hour, leap years, range validation) is pure and host-tested; only the register read/write (Wire) touches hardware.

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file rtc.h.

Macro Definition Documentation

◆ RTC_REG_COUNT

#define RTC_REG_COUNT 7

Number of time registers read from the RTC (seconds..year).

Definition at line 28 of file rtc.h.

Function Documentation

◆ rtc_regs_to_epoch()

bool rtc_regs_to_epoch	(	const uint8_t	regs[RTC_REG_COUNT],
		uint32_t *	epoch
	)

Convert the 7 raw RTC time registers (BCD: sec, min, hour, dow, date, month, year) to a Unix timestamp. Pure - no I2C. Handles both 24-hour and 12-hour (AM/PM) hour encodings and masks the DS1307 clock-halt / DS3231 century bits.

Parameters

regs	the 7 register bytes as read from register 0.
epoch	out: seconds since 1970-01-01 UTC.

Returns: true on a valid time; false if a field is out of range (bad/uninitialized RTC).

◆ rtc_epoch_to_regs()

void rtc_epoch_to_regs	(	uint32_t	epoch,
		uint8_t	regs[RTC_REG_COUNT]
	)

Convert a Unix timestamp to the 7 RTC time registers (BCD, 24-hour). Pure - no I2C. The day-of-week register is filled (1=Mon..7=Sun) for completeness.

◆ rtc_begin()

bool rtc_begin ( )

Initialize the I2C bus for the RTC.

Returns: true on a host build (no-op) or on ESP32.

◆ rtc_read_epoch()

uint32_t rtc_read_epoch ( )

Read the current time from the RTC over I2C.

Returns: seconds since 1970-01-01 UTC, or 0 if the RTC is absent / holds an invalid time.

◆ rtc_set_epoch()

bool rtc_set_epoch ( uint32_t epoch )

Set the RTC to epoch over I2C.

Returns: true if the write succeeded.

◆ rtc_time_source()

uint32_t rtc_time_source ( )

A TimeSourceFn wrapper (returns rtc_read_epoch()) to register with detws_time_source_add().

Returns: the RTC time, or 0 when unavailable.

Macros

Functions