RTCSAMC – Library

This library allows to work with the real time clock (RTC) embedded in every dice device. It allows to set and read the hardware real time clock and set alarms (e.g. for wakeups, see also LowPower lib). The library is derived from the Arduino RTC library which servers as the programming reference. The following information emphasises on additional functions and examples.

The RTC operates also in low power sleep mode (details) and can be used to wake up the system. After the device is powered the RTC starts operating from a defined date, which means it has to be set to the correct time first. In order to do so, the application can get the current time in different ways. Either manually entered by the user, by means of the NTP protocol via the internet or by GPS.
To maintain the RTC-time, the device must not be switched off completely, but must enter the power-saving sleep mode instead.

Dice libraries internally work with ‘epoch‘ time. This is the number of seconds passed since 1.1.1970. This value is handy to calculate time spans for example. Find functions to set and to read the RTC time and alarms etc. using the epoch time as well as functions to generate time-stamp strings etc. further down.

To use this library

#include <RTCSAMC.h>

Object / Handle

rtc

Start the RTC

rtc.begin();

Additional methods

Set and read the RTC see Arduino RTC documentation
rtc.isConfigured() – returns true if rtc.begin() was called and hence the RTC is running
rtc.isReasonable() – returns true if the current RTC is > 1.1.2020
rtc.printTime() – retuns a string in hh:mm:ss format of the current RTC time.
rtc.printDate() – returns a string in dd/mm/yy format of the current RTC time.
rtc.printTimeStamp() – returns a sting in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) of the current RTC time.
rtc.printTimeStamp(epoch) – returns a sting in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) of (uint32_t) epoch.
rtc.getEpoch() – returns (uint32_t) the number of seconds elapsed since 1/1/1970. (see ‘epoch‘ time)
rtc.setEpoch( epoch ) – set the RTC using the epoch time (uint32_t epoch)
rtc.adjust( epoch ) – see setEpoch()
rtc.updateEpoch( epoch , max_deviation) – checks if epoch (uint32_t) is appropriate and sets the RTC, but only if the current RTC time deviates more than max_deviation (uint32_t) from the new epoch time.
rtc.now() – returns a DateTime object of the current RTC time.

Examples

// Manually (eg. from user/console input etc.)
#include <RTCSAMC.h>
void setup()
{
  rtc.begin();
  rtc.setTime(hours, minutes, seconds);
  rtc.setDate(day, month, year);
}
....

// GPS (distributed on the CAN bus eg. by dice-GNSS)
// Note: DICE_GPS.h also includes the RTCSAMC.h lib

#include "DICE_GPS.h"
void setup()
{
	GPS.begin();
	... // the RTC will be kept up to date by the GPS background process
}
...

// NTP internet protocol
see example: RTCSAMC -> RTCfromNTP 

// https://www.epochconverter.com/
uint32_t epoch = 1735689600; // e.g. 1.1.2025
rtc.updateEpoch( epoch, 3 ); // write to rtc only if +/-3sec  off current rtc time

  rtc.setAlarmTime(17, 00, 10);
  rtc.enableAlarm(rtc.MATCH_HHMMSS);
  LowPower.sleep(); // include 'LowPowerSAMC.h'
  v_resetSystem();

RTCSAMC library notes & features

The library will be included automatically by the LowPowerSAMC- Library. Include the LowPowerSAMC.h library and use the sleep() method to put the device in low-power sleep() mode. This also allows to set further wakeup trigger sources (e.g. ignition pin) other than the RTC.

Further information

LowPowerSAMC- Library
Power and Reset management
DICE_GPS- Library
consoleRTC.h
Arduino – RTC