rtc.h File Reference

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

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	RtcNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Macros
#define	RTC_REG_COUNT   7

Functions
	PROTOCORE_NS_LAYOUT (RtcNs, regs_to_epoch, epoch_to_regs, begin, read_epoch, set_epoch, time_source)
proto_bool	protocore_rtc_regs_to_epoch (uint8_t *work, const uint8_t *regs, uint32_t *epoch)
	Convert the 7 raw RTC time registers (BCD: sec, min, hour, dow, .
void	protocore_rtc_epoch_to_regs (uint8_t *work, uint32_t epoch, uint8_t *regs)
	Convert a Unix timestamp to the 7 RTC time registers (BCD, .
proto_bool	protocore_rtc_begin (uint8_t *work)
	Initialize the I2C bus for the RTC. true; with no bus seam it is a .
uint32_t	protocore_rtc_read_epoch (uint8_t *work)
	Read the current time from the RTC over I2C.
proto_bool	protocore_rtc_set_epoch (uint8_t *work, uint32_t epoch)
	Set the RTC to epoch over I2C. true if the write succeeded.
void	protocore_rtc_time_source (uint8_t *work)
	A TimeSourceFn wrapper (returns protocore_rtc_read_epoch()) to .
uint8_t *	protocore_rtc_span (void)
	The PROTOCORE_I2C_DEVICE_BORROW bytes this module's state lives in.

Variables
PROTOCORE_NS RtcNs Rtc	PROTOCORE_UNUSED
	Module namespace.

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 protocore_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 PROTOCORE_ENABLE_RTC.

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

work is PROTOCORE_I2C_DEVICE_BORROW bytes the CALLER took, at an address it knows. It is not held past the call, so nothing here aliases it. How those bytes are carved is this module's and is never named here.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file rtc.h.

Macro Definition Documentation

RTC_REG_COUNT

#define RTC_REG_COUNT   7

Definition at line 31 of file rtc.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	RtcNs	,
		regs_to_epoch	,
		epoch_to_regs	,
		begin	,
		read_epoch	,
		set_epoch	,
		time_source
	)

protocore_rtc_regs_to_epoch()

proto_bool protocore_rtc_regs_to_epoch	(	uint8_t *	work,
		const uint8_t *	regs,
		uint32_t *	epoch
	)

Convert the 7 raw RTC time registers (BCD: sec, min, hour, dow, .

Parameters

work	PROTOCORE_RTC_BORROW bytes the caller took. Not held past the call.
regs	the 7 register bytes as read from register 0 RTC_REG_COUNT bytes
epoch	out: seconds since 1970-01-01 UTC

Returns

PROTO_TRUE on success.

protocore_rtc_epoch_to_regs()

void protocore_rtc_epoch_to_regs	(	uint8_t *	work,
		uint32_t	epoch,
		uint8_t *	regs
	)

Convert a Unix timestamp to the 7 RTC time registers (BCD, .

Parameters

work	PROTOCORE_RTC_BORROW bytes the caller took. Not held past the call.
epoch	Epoch
regs	RTC_REG_COUNT bytes

protocore_rtc_begin()

proto_bool protocore_rtc_begin

(

uint8_t *

work

)

Initialize the I2C bus for the RTC. true; with no bus seam it is a .

Parameters

work	PROTOCORE_RTC_BORROW bytes the caller took. Not held past the call.

Returns

PROTO_TRUE on success.

protocore_rtc_read_epoch()

uint32_t protocore_rtc_read_epoch

(

uint8_t *

work

)

Read the current time from the RTC over I2C.

Parameters

work	PROTOCORE_RTC_BORROW bytes the caller took. Not held past the call.

Returns

The uint32_t.

protocore_rtc_set_epoch()

proto_bool protocore_rtc_set_epoch	(	uint8_t *	work,
		uint32_t	epoch
	)

Set the RTC to epoch over I2C. true if the write succeeded.

Parameters

work	PROTOCORE_RTC_BORROW bytes the caller took. Not held past the call.
epoch	Epoch

Returns

PROTO_TRUE on success.

protocore_rtc_time_source()

void protocore_rtc_time_source

(

uint8_t *

work

)

A TimeSourceFn wrapper (returns protocore_rtc_read_epoch()) to .

Parameters

work	PROTOCORE_RTC_BORROW bytes the caller took. Not held past the call.

protocore_rtc_span()

uint8_t * protocore_rtc_span

(

void

)

The PROTOCORE_I2C_DEVICE_BORROW bytes this module's state lives in.

Stated beside the namespace rather than on it: an entry takes a borrow, and this is where that borrow comes from. Taken once from the end of the pool, which no mark and no release walks, so the state lasts the life of the program.

Returns

the span.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS RtcNs Rtc PROTOCORE_UNUSED

Initial value:

= {.regs_to_epoch = protocore_rtc_regs_to_epoch,
                                           .epoch_to_regs = protocore_rtc_epoch_to_regs,
                                           .begin = protocore_rtc_begin,
                                           .read_epoch = protocore_rtc_read_epoch,
                                           .set_epoch = protocore_rtc_set_epoch,
                                           .time_source = protocore_rtc_time_source}

Module namespace.

Definition at line 97 of file rtc.h.