rtc.h File Reference

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

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

Go to the source code of this file.

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

Functions
bool	pc_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	pc_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	pc_rtc_begin ()
	Initialize the I2C bus for the RTC.
uint32_t	pc_rtc_read_epoch ()
	Read the current time from the RTC over I2C.
bool	pc_rtc_set_epoch (uint32_t epoch)
	Set the RTC to epoch over I2C.
uint32_t	pc_rtc_time_source ()
	A TimeSourceFn wrapper (returns pc_rtc_read_epoch()) to register with pc_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 pc_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 PC_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

pc_rtc_regs_to_epoch()

bool pc_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).

pc_rtc_epoch_to_regs()

void pc_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.

pc_rtc_begin()

bool pc_rtc_begin

(

)

Initialize the I2C bus for the RTC.

Returns

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

pc_rtc_read_epoch()

uint32_t pc_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.

pc_rtc_set_epoch()

bool pc_rtc_set_epoch

(

uint32_t

epoch

)

Set the RTC to epoch over I2C.

Returns

true if the write succeeded.

pc_rtc_time_source()

uint32_t pc_rtc_time_source

(

)

A TimeSourceFn wrapper (returns pc_rtc_read_epoch()) to register with pc_time_source_add().

Returns

the RTC time, or 0 when unavailable.