I2C device driver for the DS1307 RTC chip. More...

#include <fastarduino/devices/ds1307.h>

Inheritance diagram for devices::rtc::DS1307< MANAGER >:

Collaboration diagram for devices::rtc::DS1307< MANAGER >:

Classes
class	DisableOutputFuture
	Create a future to be used by asynchronous method disable_output(DisableOutputFuture&). More...

class	EnableOutputFuture
	Create a future to be used by asynchronous method enable_output(EnableOutputFuture&). More...

class	GetRam1Future
	Create a future to be used by asynchronous method get_ram(GetRam1Future&). More...

class	GetRamFuture
	Create a future to be used by asynchronous method get_ram(GetRamFuture<SIZE>&). More...

class	HaltClockFuture
	Create a future to be used by asynchronous method halt_clock(HaltClockFuture&). More...

class	SetRam1Future
	Create a future to be used by asynchronous method set_ram(SetRam1Future&). More...

class	SetRamFuture
	Create a future to be used by asynchronous method set_ram(SetRamFuture<SIZE>&). More...

Public Types
using	SetDatetimeFuture = TWriteRegisterFuture< TIME_ADDRESS, tm, DatetimeConverterToDevice >
	Create a future to be used by asynchronous method set_datetime(SetDatetimeFuture&). More...

using	GetDatetimeFuture = TReadRegisterFuture< TIME_ADDRESS, tm, DatetimeConverterFromDevice >
	Create a future to be used by asynchronous method get_datetime(GetDatetimeFuture&). More...

Public Types inherited from i2c::I2CDevice< MANAGER >
using	MANAGER = MANAGER
	the type of I2C Manager that can handle this device. More...

Public Member Functions
	DS1307 (MANAGER &manager)
	Create a new device driver for a DS1307 chip. More...

int	set_datetime (SetDatetimeFuture &future)
	Change date and time of the RTC chip connected to this driver. More...

int	get_datetime (GetDatetimeFuture &future)
	Get the current date and time from the RTC chip. More...

template<uint8_t SIZE>
int	set_ram (SetRamFuture< SIZE > &future)
	Set several cells of the chip internal RAM to specified values. More...

int	set_ram (SetRam1Future &future)
	Set one cell of the chip internal RAM to the specified value. More...

template<uint8_t SIZE>
int	get_ram (GetRamFuture< SIZE > &future)
	Get values of several cells from the chip internal RAM. More...

int	get_ram (GetRam1Future &future)
	Get the value of one cell of the chip internal RAM. More...

int	halt_clock (HaltClockFuture &future)
	Disable the RTC oscillator, hence the time will not be updated anymore. More...

int	enable_output (EnableOutputFuture &future)
	Enable square wave output to the SQW/OUT pin of the RTC chip. More...

int	disable_output (DisableOutputFuture &future)
	Enable square wave output to the SQW/OUT pin of the RTC chip. More...

bool	set_datetime (const tm &datetime)
	Change date and time of the RTC chip connected to this driver. More...

bool	get_datetime (tm &datetime)
	Get the current date and time from the RTC chip. More...

bool	halt_clock ()
	Disable the RTC oscillator, hence the time will not be updated anymore. More...

bool	enable_output (SquareWaveFrequency frequency=SquareWaveFrequency::FREQ_1HZ)
	Enable square wave output to the SQW/OUT pin of the RTC chip. More...

bool	disable_output (bool output_value=false)
	Disable square wave output to the SQW/OUT pin of the RTC chip. More...

bool	set_ram (uint8_t address, uint8_t data)
	Set one cell of the chip internal RAM to the specified value. More...

uint8_t	get_ram (uint8_t address)
	Get the value of one cell of the chip internal RAM. More...

template<uint8_t SIZE>
bool	set_ram (uint8_t address, const uint8_t(&data)[SIZE])
	Set several cells of the chip internal RAM to specified values. More...

template<uint8_t SIZE>
bool	get_ram (uint8_t address, uint8_t(&data)[SIZE])
	Get values of several cells from the chip internal RAM. More...

template<typename T >
bool	set_ram (uint8_t address, const T &data)
	Write any type of data to the chip internal RAM. More...

template<typename T >
bool	get_ram (uint8_t address, T &data)
	Read any type of data from the chip internal RAM. More...

Static Public Member Functions
static constexpr uint8_t	ram_size ()
	Get the size of the additional RAM size of the chip. More...

Additional Inherited Members
Protected Types inherited from i2c::I2CDevice< MANAGER >
using	ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE
	The abstract base class of all futures to be defined for a device. More...

using	FUTURE = typename MANAGER::template FUTURE< OUT, IN >
	The template base class of all futures to be defined for a device. More...

Protected Member Functions inherited from i2c::I2CDevice< MANAGER >
	I2CDevice (MANAGER &manager, uint8_t device, UNUSED Mode< MODE > mode, bool auto_stop)
	Create a new I2C device. More...

	I2CDevice (const I2CDevice &)=delete

I2CDevice &	operator= (const I2CDevice &)=delete

void	set_device (uint8_t device)
	Change the I2C address of this device. More...

int	launch_commands (ABSTRACT_FUTURE &future, utils::range< I2CLightCommand > commands)
	Launch execution (asynchronously or synchronously, depending on MANAGER) of a chain of I2CLightCommand items (constructed with `read()` and `write()` methods). More...

int	async_read (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading). More...

bool	sync_read (T &result)
	Helper method that launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading); the method blocks until the end of the I2C transaction. More...

int	async_write (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing only one write (typically for device register writing). More...

int	async_multi_write (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing several register writes. More...

bool	sync_write (const T &value)
	Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction. More...

bool	sync_write ()
	Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction. More...

Static Protected Member Functions inherited from i2c::I2CDevice< MANAGER >
static constexpr I2CLightCommand	read (uint8_t read_count=0, bool finish_future=false, bool stop=false)
	Build a read I2CLightCommand that can be later pushed to the I2C Manager for proper handling. More...

static constexpr I2CLightCommand	write (uint8_t write_count=0, bool finish_future=false, bool stop=false)
	Build a write I2CLightCommand that can be later pushed to the I2C Manager for proper handling. More...

Detailed Description

template<typename MANAGER>
class devices::rtc::DS1307< MANAGER >

I2C device driver for the DS1307 RTC chip.

Note that this chip only supports standard I2C mode (100 KHz).

Template Parameters

MANAGER one of FastArduino available I2C Manager

Definition at line 116 of file ds1307.h.

Member Typedef Documentation

◆ SetDatetimeFuture

template<typename MANAGER >

using devices::rtc::DS1307< MANAGER >::SetDatetimeFuture = TWriteRegisterFuture<TIME_ADDRESS, tm, DatetimeConverterToDevice>

Create a future to be used by asynchronous method set_datetime(SetDatetimeFuture&).

This is used by set_datetime() to pass input settings, and it shall be used by the caller to determine when the I2C transaction is finished.

Parameters

datetime the new date/time to set on the RTC chip; all values must be properly set and be correct, in particular, note that tm::tm_wday must be set correctly by yourself (the RTC chip does not calculate it itself).

See also: set_datetime(SetDatetimeFuture&)

Definition at line 225 of file ds1307.h.

◆ GetDatetimeFuture

template<typename MANAGER >

using devices::rtc::DS1307< MANAGER >::GetDatetimeFuture = TReadRegisterFuture<TIME_ADDRESS, tm, DatetimeConverterFromDevice>

Create a future to be used by asynchronous method get_datetime(GetDatetimeFuture&).

This is used by get_datetime() to get device data, and it shall be used by the caller to determine when the I2C transaction is finished.

See also: get_datetime(GetDatetimeFuture&)

Definition at line 256 of file ds1307.h.

Constructor & Destructor Documentation

◆ DS1307()

template<typename MANAGER >

devices::rtc::DS1307< MANAGER >::DS1307 ( MANAGER & manager )

inlineexplicit

Create a new device driver for a DS1307 chip.

Parameters

manager reference to a suitable MANAGER for this device

Definition at line 201 of file ds1307.h.

Member Function Documentation

◆ ram_size()

template<typename MANAGER >

static constexpr uint8_t devices::rtc::DS1307< MANAGER >::ram_size ( )

inlinestaticconstexpr

Get the size of the additional RAM size of the chip.

Definition at line 206 of file ds1307.h.

◆ set_datetime() [1/2]

template<typename MANAGER >

int devices::rtc::DS1307< MANAGER >::set_datetime ( SetDatetimeFuture & future )

inline

Change date and time of the RTC chip connected to this driver.

Warning: Asynchronous API!

Parameters

future a SetDatetimeFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: SetDatetimeFuture; set_datetime(const tm&); errors

Definition at line 244 of file ds1307.h.

◆ get_datetime() [1/2]

template<typename MANAGER >

int devices::rtc::DS1307< MANAGER >::get_datetime ( GetDatetimeFuture & future )

inline

Get the current date and time from the RTC chip.

Warning: Asynchronous API!

Parameters

future a GetDatetimeFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: GetDatetimeFuture; get_datetime(tm&); errors

Definition at line 275 of file ds1307.h.

◆ set_ram() [1/5]

template<typename MANAGER >

template<uint8_t SIZE>

int devices::rtc::DS1307< MANAGER >::set_ram ( SetRamFuture< SIZE > & future )

inline

Set several cells of the chip internal RAM to specified values.

Warning: Asynchronous API!

Template Parameters

SIZE	the number of bytes to be written; `address + SIZE` must be less than `ram_size()`.

Parameters

future a SetRamFuture<SIZE> passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: SetRamFuture<SIZE>; set_ram(uint8_t, const uint8_t(&)[]); get_ram(GetRamFuture<SIZE>&); errors

Definition at line 341 of file ds1307.h.

◆ set_ram() [2/5]

template<typename MANAGER >

int devices::rtc::DS1307< MANAGER >::set_ram ( SetRam1Future & future )

inline

Set one cell of the chip internal RAM to the specified value.

Warning: Asynchronous API!

Parameters

future an SetRam1Future passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: SetRam1Future; get_ram(GetRam1Future&); set_ram(uint8_t, uint8_t); errors

Definition at line 391 of file ds1307.h.

◆ get_ram() [1/5]

template<typename MANAGER >

template<uint8_t SIZE>

int devices::rtc::DS1307< MANAGER >::get_ram ( GetRamFuture< SIZE > & future )

inline

Get values of several cells from the chip internal RAM.

Warning: Asynchronous API!

Template Parameters

SIZE	the number of bytes to read; `address + SIZE` must be less than `ram_size()`.

Parameters

future an GetRamFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: GetRamFuture<SIZE>; set_ram(SetRamFuture<SIZE>&); get_ram(uint8_t, uint8_t*, uint8_t); errors

Definition at line 446 of file ds1307.h.

◆ get_ram() [2/5]

template<typename MANAGER >

int devices::rtc::DS1307< MANAGER >::get_ram ( GetRam1Future & future )

inline

Get the value of one cell of the chip internal RAM.

Warning: Asynchronous API!

Parameters

future an GetRam1Future passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: GetRam1Future; get_ram(uint8_t, uint8_t&); set_ram(SetRam1Future&); errors

Definition at line 494 of file ds1307.h.

◆ halt_clock() [1/2]

template<typename MANAGER >

int devices::rtc::DS1307< MANAGER >::halt_clock ( HaltClockFuture & future )

inline

Disable the RTC oscillator, hence the time will not be updated anymore.

If you want to re-enable the clock, you need to set a new date/time with set_datetime().

Warning: Asynchronous API!

Parameters

future a HaltClockFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: HaltClockFuture; set_datetime(); halt_clock(); errors

Definition at line 537 of file ds1307.h.

◆ enable_output() [1/2]

template<typename MANAGER >

int devices::rtc::DS1307< MANAGER >::enable_output ( EnableOutputFuture & future )

inline

Enable square wave output to the SQW/OUT pin of the RTC chip.

Warning: Asynchronous API!

Parameters

future an EnableOutputFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: EnableOutputFuture; enable_output(SquareWaveFrequency); disable_output(DisableOutputFuture&); errors

Definition at line 580 of file ds1307.h.

◆ disable_output() [1/2]

template<typename MANAGER >

int devices::rtc::DS1307< MANAGER >::disable_output ( DisableOutputFuture & future )

inline

Enable square wave output to the SQW/OUT pin of the RTC chip.

Warning: Asynchronous API!

Parameters

future a DisableOutputFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: DisableOutputFuture; disable_output(bool); enable_output(); errors

Definition at line 623 of file ds1307.h.

◆ set_datetime() [2/2]

template<typename MANAGER >

bool devices::rtc::DS1307< MANAGER >::set_datetime ( const tm & datetime )

inline

Change date and time of the RTC chip connected to this driver.

Warning: Blocking API!

Parameters

datetime the new date/time to set on the RTC chip; all values must be properly set and be correct, in particular, note that tm::tm_wday must be set correctly by yourself (the RTC chip does not calculate it itself).

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_datetime(SetDatetimeFuture&)

Definition at line 643 of file ds1307.h.

◆ get_datetime() [2/2]

template<typename MANAGER >

bool devices::rtc::DS1307< MANAGER >::get_datetime ( tm & datetime )

inline

Get the current date and time from the RTC chip.

Warning: Blocking API!

Parameters

datetime a reference to a tm variable that will be filled with current date and time from the RTC chip

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_datetime(GetDatetimeFuture&)

Definition at line 659 of file ds1307.h.

◆ halt_clock() [2/2]

template<typename MANAGER >

bool devices::rtc::DS1307< MANAGER >::halt_clock ( )

inline

Disable the RTC oscillator, hence the time will not be updated anymore.

If you want to re-enable the clock, you need to set a new date/time with set_datetime().

Warning: Blocking API!

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_datetime(); halt_clock(HaltClockFuture&)

Definition at line 676 of file ds1307.h.

◆ enable_output() [2/2]

template<typename MANAGER >

bool devices::rtc::DS1307< MANAGER >::enable_output ( SquareWaveFrequency frequency = SquareWaveFrequency::FREQ_1HZ )

inline

Enable square wave output to the SQW/OUT pin of the RTC chip.

Warning: Blocking API!

Parameters

frequency one of the supported RTC frequencies, defined in SquareWaveFrequency enum

Return values

true	if the operation succeeded
false	if the operation failed

See also: disable_output(); enable_output(EnableOutputFuture&)

Definition at line 693 of file ds1307.h.

◆ disable_output() [2/2]

template<typename MANAGER >

bool devices::rtc::DS1307< MANAGER >::disable_output ( bool output_value = false )

inline

Disable square wave output to the SQW/OUT pin of the RTC chip.

Warning: Blocking API!

Parameters

output_value value to force on SQW/OUT pin

Return values

true	if the operation succeeded
false	if the operation failed

See also: enable_output(); disable_output(DisableOutputFuture&)

Definition at line 709 of file ds1307.h.

◆ set_ram() [3/5]

template<typename MANAGER >

bool devices::rtc::DS1307< MANAGER >::set_ram	(	uint8_t	address,
		uint8_t	data
	)

inline

Set one cell of the chip internal RAM to the specified value.

Warning: Blocking API!

Parameters

address	the address of the cell to write, must be between `0` and `ram_size()`.
data	the value to put at `address`

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_ram(uint8_t); set_ram(SetRam1Future&)

Definition at line 727 of file ds1307.h.

◆ get_ram() [3/5]

template<typename MANAGER >

uint8_t devices::rtc::DS1307< MANAGER >::get_ram ( uint8_t address )

inline

Get the value of one cell of the chip internal RAM.

Warning: Blocking API!

Parameters

address the address of the cell to read, must be between 0 and ram_size().

Returns: the value read at address

See also: set_ram(uint8_t, uint8_t); get_ram(GetRam1Future&)

Definition at line 745 of file ds1307.h.

◆ set_ram() [4/5]

template<typename MANAGER >

template<uint8_t SIZE>

bool devices::rtc::DS1307< MANAGER >::set_ram	(	uint8_t	address,
		const uint8_t(&)	data[SIZE]
	)

inline

Set several cells of the chip internal RAM to specified values.

Warning: Blocking API!

Template Parameters

SIZE	the number of bytes to be written; `address + SIZE` must be less than `ram_size()`.

Parameters

address	the address of the first cell to write, must be between `0` and `ram_size()`.
data	pointer to a buffer containing the values to write

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_ram(uint8_t, uint8_t(&)[]); set_ram(SetRamFuture<SIZE>&)

Definition at line 769 of file ds1307.h.

◆ get_ram() [4/5]

template<typename MANAGER >

template<uint8_t SIZE>

bool devices::rtc::DS1307< MANAGER >::get_ram	(	uint8_t	address,
		uint8_t(&)	data[SIZE]
	)

inline

Get values of several cells from the chip internal RAM.

Warning: Blocking API!

Template Parameters

SIZE	the number of bytes to read; `address + SIZE` must be less than `ram_size()`.

Parameters

address	the address of the first cell to read, must be between `0` and `ram_size()`.
data	pointer to a buffer where read values will be copied

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_ram(uint8_t, const uint8_t(&)[]); get_ram(GetRamFuture<SIZE>&)

Definition at line 791 of file ds1307.h.

◆ set_ram() [5/5]

template<typename MANAGER >

template<typename T >

bool devices::rtc::DS1307< MANAGER >::set_ram	(	uint8_t	address,
		const T &	data
	)

inline

Write any type of data to the chip internal RAM.

Warning: Blocking API!

Template Parameters

T	the type of data to be written

Parameters

address	the address where to write data, must be between `0` and `ram_size() - sizeof(T)`.
data	the actual data of type `T`, to be written

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_ram(uint8_t, T&); set_ram(SetRamFuture<SIZE>&)

Definition at line 815 of file ds1307.h.

◆ get_ram() [5/5]

template<typename MANAGER >

template<typename T >

bool devices::rtc::DS1307< MANAGER >::get_ram	(	uint8_t	address,
		T &	data
	)

inline

Read any type of data from the chip internal RAM.

Note that this method only copies bytes to a variable of some type, no constructor will be called; hence, it is preferrable to use only simple struct types.

Warning: Blocking API!

Template Parameters

T	the type of data to be read

Parameters

address	the address where to find data to read, must be between `0` and `ram_size() - sizeof(T)`.
data	a reference to a variable that will be copied the read content

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_ram(uint8_t, const T&); get_ram(GetRamFuture<SIZE>&)

Definition at line 841 of file ds1307.h.

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

fastarduino/devices/ds1307.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ SetDatetimeFuture

◆ GetDatetimeFuture

Constructor & Destructor Documentation

◆ DS1307()

Member Function Documentation

◆ ram_size()

◆ set_datetime() [1/2]

◆ get_datetime() [1/2]

◆ set_ram() [1/5]

◆ set_ram() [2/5]

◆ get_ram() [1/5]

◆ get_ram() [2/5]

◆ halt_clock() [1/2]

◆ enable_output() [1/2]

◆ disable_output() [1/2]

◆ set_datetime() [2/2]

◆ get_datetime() [2/2]

◆ halt_clock() [2/2]

◆ enable_output() [2/2]

◆ disable_output() [2/2]

◆ set_ram() [3/5]

◆ get_ram() [3/5]

◆ set_ram() [4/5]

◆ get_ram() [4/5]

◆ set_ram() [5/5]

◆ get_ram() [5/5]