DS1302 RTC class. More...

#include <ErriezDS1302.h>

Public Member Functions
	ErriezDS1302 (uint8_t clkPin, uint8_t ioPin, uint8_t cePin)
	Constructor DS1302 RTC. More...

bool	begin ()
	Initialize and detect DS1302 RTC. More...

bool	isRunning ()
	Read RTC CH (Clock Halt) from seconds register. More...

bool	clockEnable (bool enable=true)
	Enable or disable oscillator. More...

time_t	getEpoch ()
	Read Unix UTC epoch time_t. More...

bool	setEpoch (time_t t)
	Write Unix epoch UTC time to RTC. More...

bool	read (struct tm *dt)
	Read date and time from RTC. More...

bool	write (const struct tm *dt)
	Write date and time to RTC. More...

bool	setTime (uint8_t hour, uint8_t min, uint8_t sec)
	Write time to RTC. More...

bool	getTime (uint8_t hour, uint8_t min, uint8_t *sec)
	Read time from RTC. More...

bool	setDateTime (uint8_t hour, uint8_t min, uint8_t sec, uint8_t mday, uint8_t mon, uint16_t year, uint8_t wday)
	Set date time. More...

bool	getDateTime (uint8_t hour, uint8_t min, uint8_t sec, uint8_t mday, uint8_t mon, uint16_t year, uint8_t *wday)
	Get date time. More...

uint8_t	bcdToDec (uint8_t bcd)
	BCD to decimal conversion. More...

uint8_t	decToBcd (uint8_t dec)
	Decimal to BCD conversion. More...

uint8_t	readRegister (uint8_t reg)
	Read register. More...

bool	writeRegister (uint8_t reg, uint8_t value)
	Write register. More...

bool	readBuffer (uint8_t reg, void *buffer, uint8_t len)
	Read buffer from RTC clock registers. More...

bool	writeBuffer (uint8_t reg, void *buffer, uint8_t len)
	Write buffer to RTC clock registers. More...

void	writeByteRAM (uint8_t addr, uint8_t value)
	Write a byte to RAM. More...

void	writeBufferRAM (uint8_t *buf, uint8_t len)
	Write buffer to RAM address 0x00 (burst write) More...

uint8_t	readByteRAM (uint8_t addr)
	Read byte from RAM. More...

void	readBufferRAM (uint8_t *buf, uint8_t len)
	Read buffer from RAM address 0x00 (burst read) More...

Detailed Description

DS1302 RTC class.

Definition at line 128 of file ErriezDS1302.h.

Constructor & Destructor Documentation

◆ ErriezDS1302()

ErriezDS1302::ErriezDS1302	(	uint8_t	clkPin,
		uint8_t	ioPin,
		uint8_t	cePin
	)

Constructor DS1302 RTC.

Parameters

clkPin	Clock pin
ioPin	I/O pin.
cePin	Chip select pin. (In previous versions RST pin which is the same)

Definition at line 44 of file ErriezDS1302.cpp.

Member Function Documentation

◆ bcdToDec()

uint8_t ErriezDS1302::bcdToDec ( uint8_t bcd )

BCD to decimal conversion.

Parameters

bcd	BCD encoded value.

Returns: Decimal value.

Definition at line 515 of file ErriezDS1302.cpp.

◆ begin()

bool ErriezDS1302::begin ( )

Initialize and detect DS1302 RTC.

Call this function from setup().

Return values

true	RTC detected.
false	RTC not detected.

Definition at line 70 of file ErriezDS1302.cpp.

◆ clockEnable()

bool ErriezDS1302::clockEnable ( bool enable = true )

Enable or disable oscillator.

Clear or set CH (Clock Halt) bit to seconds register

Parameters

enable true: Enable RTC clock.
false: Stop RTC clock.

Return values

true	Success.
false	Oscillator enable failed.

Definition at line 134 of file ErriezDS1302.cpp.

◆ decToBcd()

uint8_t ErriezDS1302::decToBcd ( uint8_t dec )

Decimal to BCD conversion.

Parameters

dec	Decimal value.

Returns: BCD encoded value.

Definition at line 527 of file ErriezDS1302.cpp.

◆ getDateTime()

bool ErriezDS1302::getDateTime	(	uint8_t *	hour,
		uint8_t *	min,
		uint8_t *	sec,
		uint8_t *	mday,
		uint8_t *	mon,
		uint16_t *	year,
		uint8_t *	wday
	)

Get date time.

Parameters

hour	Hours 0..23
min	Minutes 0..59
sec	Seconds 0..59
mday	Day of the month 1..31
mon	Month 1..12 (1=January)
year	Year 2000..2099
wday	Day of the week 0..6 (0=Sunday, .. 6=Saturday)

Return values

true	Success.
false	Get date/time failed.

Definition at line 417 of file ErriezDS1302.cpp.

◆ getEpoch()

time_t ErriezDS1302::getEpoch ( )

Read Unix UTC epoch time_t.

Returns: Unix epoch time_t seconds since 1970.

Definition at line 159 of file ErriezDS1302.cpp.

◆ getTime()

bool ErriezDS1302::getTime	(	uint8_t *	hour,
		uint8_t *	min,
		uint8_t *	sec
	)

Read time from RTC.

Read hour, minute and second registers from RTC.

Parameters

hour	Hours 0..23.
min	Minutes 0..59.
sec	Seconds 0..59.

Return values

true	Success.
false	Invalid second, minute or hour read from RTC. The time is set to zero.

Definition at line 339 of file ErriezDS1302.cpp.

◆ isRunning()

bool ErriezDS1302::isRunning ( )

Read RTC CH (Clock Halt) from seconds register.

The application is responsible for checking the CH (Clock Halt) bit before reading date/time date. This function may be used to judge the validity of the date/time registers.

Return values

true	RTC clock is running.
false	The date/time data is invalid when the CH bit is set. The application should enable the oscillator, or program a new date/time.

Definition at line 110 of file ErriezDS1302.cpp.

◆ read()

bool ErriezDS1302::read ( struct tm * dt )

Read date and time from RTC.

Read all RTC registers at once to prevent a time/date register change in the middle of the register read operation.

Parameters

dt	Date and time struct tm.

Return values

true	Success
false	Read failed.

Definition at line 219 of file ErriezDS1302.cpp.

◆ readBuffer()

bool ErriezDS1302::readBuffer	(	uint8_t	reg,
		void *	buffer,
		uint8_t	readLen
	)

Read buffer from RTC clock registers.

Parameters

reg	RTC register number 0x00..0x07.
buffer	Buffer.
readLen	Buffer length. Reading is only allowed within valid RTC registers.

Return values

true	Success
false	Read failed.

Definition at line 624 of file ErriezDS1302.cpp.

◆ readBufferRAM()

void ErriezDS1302::readBufferRAM	(	uint8_t *	buf,
		uint8_t	len
	)

Read buffer from RAM address 0x00 (burst read)

Parameters

buf	Data buffer
len	Buffer length

Definition at line 498 of file ErriezDS1302.cpp.

◆ readByteRAM()

uint8_t ErriezDS1302::readByteRAM ( uint8_t addr )

Read byte from RAM.

Parameters

addr	RAM address 0..0x1E

Returns: RAM byte 0..0xFF

Definition at line 479 of file ErriezDS1302.cpp.

◆ readRegister()

uint8_t ErriezDS1302::readRegister ( uint8_t reg )

Read register.

Please refer to the RTC datasheet.

Parameters

reg	RTC register number 0x00..0x09.

Returns: value 8-bit unsigned register value.

Definition at line 541 of file ErriezDS1302.cpp.

◆ setDateTime()

bool ErriezDS1302::setDateTime	(	uint8_t	hour,
		uint8_t	min,
		uint8_t	sec,
		uint8_t	mday,
		uint8_t	mon,
		uint16_t	year,
		uint8_t	wday
	)

Set date time.

Parameters

hour	Hours 0..23
min	Minutes 0..59
sec	Seconds 0..59
mday	Day of the month 1..31
mon	Month 1..12 (1=January)
year	Year 2000..2099
wday	Day of the week 0..6 (0=Sunday, .. 6=Saturday)

Return values

true	Success.
false	Set date/time failed.

Definition at line 377 of file ErriezDS1302.cpp.

◆ setEpoch()

bool ErriezDS1302::setEpoch ( time_t t )

Write Unix epoch UTC time to RTC.

Parameters

t	time_t time

Return values

true	Success.
false	Set epoch failed.

Definition at line 191 of file ErriezDS1302.cpp.

◆ setTime()

bool ErriezDS1302::setTime	(	uint8_t	hour,
		uint8_t	min,
		uint8_t	sec
	)

Write time to RTC.

Write hour, minute and second registers to RTC.

Parameters

hour	Hours 0..23.
min	Minutes 0..59.
sec	Seconds 0..59.

Return values

true	Success.
false	Set time failed.

Definition at line 308 of file ErriezDS1302.cpp.

◆ write()

bool ErriezDS1302::write ( const struct tm * dt )

Write date and time to RTC.

Write all RTC registers at once to prevent a time/date register change in the middle of the register write operation. This function enables the oscillator.

Parameters

dt	Date/time struct tm. Providing invalid date/time data may result in unpredictable behavior.

Return values

true	Success.
false	Write failed.

Definition at line 274 of file ErriezDS1302.cpp.

◆ writeBuffer()

bool ErriezDS1302::writeBuffer	(	uint8_t	reg,
		void *	buffer,
		uint8_t	writeLen
	)

Write buffer to RTC clock registers.

Please refer to the RTC datasheet.

Parameters

reg	RTC register number 0x00..0x09.
buffer	Buffer.
writeLen	Buffer length. Writing is only allowed within valid RTC registers.

Return values

true	Success
false	Write failed.

Definition at line 593 of file ErriezDS1302.cpp.

◆ writeBufferRAM()

void ErriezDS1302::writeBufferRAM	(	uint8_t *	buf,
		uint8_t	len
	)

Write buffer to RAM address 0x00 (burst write)

Parameters

buf	Data buffer
len	Buffer length 0x01..0x1E

Definition at line 462 of file ErriezDS1302.cpp.

◆ writeByteRAM()

void ErriezDS1302::writeByteRAM	(	uint8_t	addr,
		uint8_t	value
	)

Write a byte to RAM.

Parameters

addr	RAM address 0..0x1E
value	RAM byte 0..0xFF

Definition at line 447 of file ErriezDS1302.cpp.

◆ writeRegister()

bool ErriezDS1302::writeRegister	(	uint8_t	reg,
		uint8_t	value
	)

Write register.

Please refer to the RTC datasheet.

Parameters

reg	RTC register number 0x00..0x09.
value	8-bit unsigned register value.

Return values

true	Success
false	Write register failed

Definition at line 567 of file ErriezDS1302.cpp.

The documentation for this class was generated from the following files:

src/ErriezDS1302.h
src/ErriezDS1302.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ErriezDS1302()

Member Function Documentation

◆ bcdToDec()

◆ begin()

◆ clockEnable()

◆ decToBcd()

◆ getDateTime()

◆ getEpoch()

◆ getTime()

◆ isRunning()

◆ read()

◆ readBuffer()

◆ readBufferRAM()

◆ readByteRAM()

◆ readRegister()

◆ setDateTime()

◆ setEpoch()

◆ setTime()

◆ write()

◆ writeBuffer()

◆ writeBufferRAM()

◆ writeByteRAM()

◆ writeRegister()