FastArduino v1.10
C++ library to build fast but small Arduino/AVR projects
Loading...
Searching...
No Matches
devices::rtc::DS1307< MANAGER > Class Template Reference

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
 
I2CDeviceoperator= (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
MANAGERone 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
datetimethe 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
managerreference 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
futurea SetDatetimeFuture passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
futurea GetDatetimeFuture passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
SIZEthe number of bytes to be written; address + SIZE must be less than ram_size().
Parameters
futurea SetRamFuture<SIZE> passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
futurean SetRam1Future passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
SIZEthe number of bytes to read; address + SIZE must be less than ram_size().
Parameters
futurean GetRamFuture passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
futurean GetRam1Future passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
futurea HaltClockFuture passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
futurean EnableOutputFuture passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
futurea DisableOutputFuture passed by the caller, that will be updated once the current I2C action is finished.
Return values
0if 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
datetimethe 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
trueif the operation succeeded
falseif 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
datetimea reference to a tm variable that will be filled with current date and time from the RTC chip
Return values
trueif the operation succeeded
falseif 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
trueif the operation succeeded
falseif 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
frequencyone of the supported RTC frequencies, defined in SquareWaveFrequency enum
Return values
trueif the operation succeeded
falseif 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_valuevalue to force on SQW/OUT pin
Return values
trueif the operation succeeded
falseif 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
addressthe address of the cell to write, must be between 0 and ram_size().
datathe value to put at address
Return values
trueif the operation succeeded
falseif 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
addressthe 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
SIZEthe number of bytes to be written; address + SIZE must be less than ram_size().
Parameters
addressthe address of the first cell to write, must be between 0 and ram_size().
datapointer to a buffer containing the values to write
Return values
trueif the operation succeeded
falseif 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
SIZEthe number of bytes to read; address + SIZE must be less than ram_size().
Parameters
addressthe address of the first cell to read, must be between 0 and ram_size().
datapointer to a buffer where read values will be copied
Return values
trueif the operation succeeded
falseif 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
Tthe type of data to be written
Parameters
addressthe address where to write data, must be between 0 and ram_size() - sizeof(T).
datathe actual data of type T, to be written
Return values
trueif the operation succeeded
falseif 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
Tthe type of data to be read
Parameters
addressthe address where to find data to read, must be between 0 and ram_size() - sizeof(T).
dataa reference to a variable that will be copied the read content
Return values
trueif the operation succeeded
falseif 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: