M5Unified RTC8563 Class

• RTC8563 Class
  • begin
  • getVoltLow
  • getTime
  • getDate
  • getDateTime
  • setTime
  • setDate
  • setDateTime
  • setAlarmIRQ
  • setSystemTimeFromRtc
  • getIRQstatus
  • clearIRQ
  • disableIRQ

begin

Syntax:

bool begin(I2C_Class* i2c = nullptr);

Description:

• Initialize RTC

Parameters:

• I2C_Class* i2c:
  • Pointer to the I2C bus instance

Return:

• bool:
  • true: Initialization successful
  • false: Initialization failed

getVoltLow

Syntax:

bool getVoltLow(void);

Description:

• Check the status of the RTC power failure detector

Parameters:

• null

Return:

• bool:
  • true: No power failure
  • false: Power failure occurred

getTime

Syntax:

bool getTime(rtc_time_t* time) const;

Description:

• Get the current time

Parameters:

• rtc_time_t* time:
  • Pointer to the structure that receives the time information

Return:

• bool:
  • true: Read successful
  • false: Read failed

Syntax:

rtc_time_t getTime(void) const

Description:

• Get the current time

Parameters:

• null

Return:

• rtc_time_t time: Time information structure

struct __attribute__((packed)) rtc_time_t
{
  std::int8_t hours;
  std::int8_t minutes;
  std::int8_t seconds;
 
  rtc_time_t(std::int8_t hours_ = -1, std::int8_t minutes_ = -1, std::int8_t seconds_ = -1)
  : hours   { hours_   }
  , minutes { minutes_ }
  , seconds { seconds_ }
  {}
 
  rtc_time_t(const tm& t)
  : hours   { (int8_t)t.tm_hour }
  , minutes { (int8_t)t.tm_min  }
  , seconds { (int8_t)t.tm_sec  }
  {}
};

getDate

Syntax:

bool getDate(rtc_date_t* date) const;

Description:

• Get the current date

Parameters:

• rtc_date_t* date:
  • Pointer to the structure that receives the date information

Return:

• bool:
  • true: Read successful
  • false: Read failed

Syntax:

rtc_date_t getDate(void) const;

Description:

• Get the current date

Parameters:

• null

Return:

• rtc_date_t date: Date information structure

struct __attribute__((packed)) rtc_date_t
{
  /// year 1900-2099
  std::int16_t year;
 
  /// month 1-12
  std::int8_t month;
 
  /// date 1-31
  std::int8_t date;
 
  /// weekDay 0:sun / 1:mon / 2:tue / 3:wed / 4:thu / 5:fri / 6:sat
  std::int8_t weekDay;
 
  rtc_date_t(std::int16_t year_ = 2000, std::int8_t month_ = 1, std::int8_t date_ = -1, std::int8_t weekDay_ = -1)
  : year    { year_    }
  , month   { month_   }
  , date    { date_    }
  , weekDay { weekDay_ }
  {}
 
  rtc_date_t(const tm& t)
  : year    { (int16_t)(t.tm_year + 1900) }
  , month   { (int8_t )(t.tm_mon  + 1   ) }
  , date    { (int8_t ) t.tm_mday         }
  , weekDay { (int8_t ) t.tm_wday         }
  {}
};

getDateTime

Syntax:

bool getDateTime(rtc_datetime_t* datetime) const;

Description:

• Get the current time and date

Parameters:

• rtc_datetime_t* datetime:
  • Pointer to the structure that receives the time and date information

Return:

• bool:
  • true: Read successful
  • false: Read failed

Syntax:

rtc_datetime_t getDateTime(void) const
{
    rtc_datetime_t res;
    getDateTime(&res);
    return res;
}

Description:

• Get the current time and date

Parameters:

• null

Return:

• rtc_datetime_t datetime: Time and date information structure

struct __attribute__((packed)) rtc_datetime_t
{
  rtc_date_t date;
  rtc_time_t time;
  rtc_datetime_t() = default;
  rtc_datetime_t(const rtc_date_t& d, const rtc_time_t& t) : date { d }, time { t } {};
  rtc_datetime_t(const tm& t) : date { t }, time { t } {}
  tm get_tm(void) const;
  void set_tm(tm& time);
  void set_tm(tm* t) { if (t) set_tm(*t); }
};

setTime

Syntax:

void setTime(const rtc_time_t &time);

Description:

• Set the RTC time

Parameters:

• rtc_time_t* time:
  • Reference to the time information structure

Return:

• null

Syntax:

void setTime(const rtc_time_t* const time);

Description:

• Set the RTC time

Parameters:

• rtc_time_t* time:
  • Pointer to the time information structure

Return:

• null

setDate

Syntax:

void setDate(const rtc_date_t &date);

Description:

• Set the RTC date

Parameters:

• rtc_time_t* time:
  • Reference to the date information structure

Return:

• null

Syntax:

void setDate(const rtc_date_t* const date);

Description:

• Set the RTC date

Parameters:

• rtc_time_t* time:
  • Pointer to the date information structure

Return:

• null

setDateTime

Syntax:

void setDateTime(const rtc_datetime_t &datetime);

Description:

• Set the RTC time and date

Parameters:

• rtc_time_t* time:
  • Reference to the time and date information structure

Return:

• null

Syntax:

void setDateTime(const rtc_datetime_t* const datetime);

Description:

• Set the RTC time and date

Parameters:

• rtc_time_t* time:
  • Pointer to the time and date information structure

Return:

• null

Syntax:

void setDateTime(const tm* const datetime);

Description:

• Initialize the RTC time and date using the standard C/C++ time structure

Parameters:

• rtc_time_t* time:
  • Pointer to the standard time structure

Return:

• null

setAlarmIRQ

Syntax:

int setAlarmIRQ(int afterSeconds);

Description:

• Set timed interrupt signal, based on time information

Parameters:

• int afterSeconds: the set number of seconds.
  • 1 - 15,300. If 256 or more, 1-minute cycle. (max 255 minutes.)

Return:

• int(bool):
  • true: Set successfully
  • false: Set failed

Syntax:

int setAlarmIRQ(const rtc_time_t &time);

Description:

• Set timed interrupt signal, based on time information

Parameters:

• const rtc_time_t &time:
  • Reference to the time information structure

Return:

• int(bool):
  • true: Set successfully
  • false: Set failed

Syntax:

int setAlarmIRQ(const rtc_date_t &date, const rtc_time_t &time);

Description:

• Set timed interrupt signal, based on time, date information

Parameters:

• const rtc_date_t &date:
  • Reference to the date information structure
• const rtc_time_t &time:
  • Reference to the time information structure

Return:

• int(bool):
  • true: Set successfully
  • false: Set failed

setSystemTimeFromRtc

Syntax:

void setSystemTimeFromRtc(struct timezone* tz = nullptr);

Description:

• Initialize system time using RTC time information

Parameters:

• struct timezone* tz:
  • Time zone offset information

Return:

• null

getIRQstatus

Syntax:

bool getIRQstatus(void);

Description:

• Get the status of the timed interrupt signal

Parameters:

• null

Return:

• bool:
  • true: Interrupt signal has been generated
  • false: Interrupt signal has not been generated

clearIRQ

Syntax:

void clearIRQ(void);

Description:

• Clear the status of the timed interrupt signal

Parameters:

• null

Return:

• null

disableIRQ

Syntax:

void disableIRQ(void);

Description:

• Disable the timer interrupt

Parameters:

• null

Return:

• null