Driver API for RTC (plib_rtc.h) More...

Data Structures
struct	RTC_TIME
	RTC time value, BCD-encoded per datasheet RTC_TIMR format. More...

struct	RTC_CALENDAR
	RTC calendar value, BCD-encoded per datasheet RTC_CALR format. More...

struct	RTC_TIME_ALARM
	Time alarm configuration. More...

struct	RTC_CALENDAR_ALARM
	Calendar alarm configuration. More...

Typedefs
typedef void(*	RTC_CALLBACK_HANDLER) (void)
	Function pointer type for RTC callback.

typedef uint8_t	RTC_CALENDAR_MODE
	RTC calendar mode identifier.

typedef uint8_t	RTC_HOUR_MODE
	RTC hour mode identifier.

typedef uint8_t	RTC_WAVEFORM_OUTPUT
	RTC output channel identifier.

typedef uint8_t	RTC_WAVEFORM_TYPE
	RTC waveform type identifier.

typedef uint8_t	RTC_TPERIOD
	RTC programmable-pulse period identifier.

typedef uint8_t	RTC_THIGH
	RTC programmable-pulse high-duration identifier.

typedef uint8_t	RTC_TIME_EVENT
	RTC time-event selector identifier.

typedef uint8_t	RTC_CALENDAR_EVENT
	RTC calendar-event selector identifier.

Functions
void	RTC_ClearUpdateRequest (void)
	Clears a latched UPDTIM/UPDCAL update request in RTC_CR. Use this to abort an in-progress or stale time/calendar update handshake (e.g. one left set by a previous run) before starting a fresh one.

bool	RTC_SetTime (const RTC_TIME *time_value)
	Sets the current time in the RTC peripheral.

bool	RTC_GetTime (RTC_TIME *time_value)
	Gets the current time from the RTC peripheral.

bool	RTC_SetCalendar (const RTC_CALENDAR *calendar)
	Sets the current calendar in the RTC peripheral.

bool	RTC_GetCalendar (RTC_CALENDAR *calendar)
	Gets the current calendar from the RTC peripheral.

bool	RTC_SetDateTime (const RTC_TIME time_value, const RTC_CALENDAR calendar)
	Sets both time and calendar atomically.

bool	RTC_SetTimeAlarm (const RTC_TIME_ALARM *alarm)
	Configures the time alarm.

bool	RTC_SetCalendarAlarm (const RTC_CALENDAR_ALARM *alarm)
	Configures the calendar alarm.

void	RTC_EnableInterrupt (uint32_t interrupt_mask)
	Enables one or more RTC interrupt sources.

void	RTC_DisableInterrupt (uint32_t interrupt_mask)
	Disables one or more RTC interrupt sources.

void	RTC_SetCallbackHandler (RTC_CALLBACK_HANDLER callback)
	Registers the callback handler to be invoked from the RTC ISR.

void	RTC_SelectCalendarMode (RTC_CALENDAR_MODE mode)
	Selects the calendar mode (Gregorian or Persian).

void	RTC_SetHourMode (RTC_HOUR_MODE mode)
	Sets the hour mode (12h or 24h).

void	RTC_SetWaveformOutput (RTC_WAVEFORM_OUTPUT output, RTC_WAVEFORM_TYPE type)
	Configures the RTCOUT0 or RTCOUT1 output waveform.

void	RTC_SetProgrammablePulse (RTC_TPERIOD period, RTC_THIGH high)
	Configures the programmable pulse generator (RTC_MR.TPERIOD/THIGH).

void	RTC_SetTimeEventSelection (RTC_TIME_EVENT event)
	Selects which time-event trigger asserts RTC_SR.TIMEV.

void	RTC_SetCalendarEventSelection (RTC_CALENDAR_EVENT event)
	Selects which calendar-event trigger asserts RTC_SR.CALEV.

void	RTC_ClearStatus (uint32_t status_mask)
	Clears one or more status flags via RTC_SCCR.

uint32_t	RTC_GetStatus (void)
	Reads RTC_SR.

Variables
uint8_t	RTC_TIME::hour

uint8_t	RTC_TIME::minute

uint8_t	RTC_TIME::second

uint8_t	RTC_TIME::am_pm

uint8_t	RTC_CALENDAR::century

uint8_t	RTC_CALENDAR::year

uint8_t	RTC_CALENDAR::month

uint8_t	RTC_CALENDAR::date

uint8_t	RTC_CALENDAR::day

uint8_t	RTC_TIME_ALARM::hour

uint8_t	RTC_TIME_ALARM::minute

uint8_t	RTC_TIME_ALARM::second

uint8_t	RTC_TIME_ALARM::am_pm

uint8_t	RTC_TIME_ALARM::enable_hour

uint8_t	RTC_TIME_ALARM::enable_minute

uint8_t	RTC_TIME_ALARM::enable_second

uint8_t	RTC_CALENDAR_ALARM::date

uint8_t	RTC_CALENDAR_ALARM::month

uint8_t	RTC_CALENDAR_ALARM::enable_date

uint8_t	RTC_CALENDAR_ALARM::enable_month

Description

Driver API for RTC (plib_rtc.h)

Usage Example

The following example demonstrates typical usage of the RTC peripheral:

/*******************************************************************************
 * @file configure_rtc.c
 * @brief RTC Clock/Calendar Mode configuration template
 *
 * @details
 * The RTC peripheral maintains a real-world
 * BCD-encoded clock-calendar (century, year, month, date, day-of-week,
 * hour, minute, second) clocked from the 32.768 kHz slow clock.
 *
 * Key concepts:
 * - Hour mode (12h / 24h) and calendar mode (Gregorian / Persian) are
 *   selected once at bring-up.
 * - Two output pins (RTCOUT0 / RTCOUT1) can drive prescaled clocks, the
 *   alarm flag, or a programmable pulse with configurable period and
 *   high-time.
 * - The TIMEV and CALEV interrupt sources fire on configurable time and
 *   calendar edges (e.g. midnight, week change, year change).
 * - Time and calendar alarms each have per-field enables so the user can
 *   match on any combination of hour/minute/second/date/month.
 *
 * Typical use cases:
 * - Real-time wall clock with periodic wake-up
 * - Scheduled alarms
 * - Time-stamped logging
 * - Generating a 1 Hz heartbeat on RTCOUT0
 *
 * In this template:
 * - Hour mode = 24-hour, calendar mode = Gregorian
 * - RTCOUT0 emits a 1 Hz square wave; RTCOUT1 emits a programmable pulse
 *   with a 1 s period and 31 ms high-time
 * - TIMEV fires at midnight; CALEV fires on month change
 * - Wall clock is stamped at 18-May-2026 23:59:55 (5 s before midnight)
 * - Time alarm fires at 00:00:10; calendar alarm fires on May 19
 * - The user callback is registered and ALR / SEC / TIMEV / CALEV are
 *   enabled at the RTC peripheral. The caller is responsible for enabling
 *   the RTC NVIC line.
 ******************************************************************************/
#include "plib_rtc.h"
#include <pic32c.h>
#include <stdint.h>
#include <stdbool.h>
 
/* Flags raised by the callback so the application can react. The application
 * clears these after handling. */
volatile bool rtc_alarm_triggered          = false;
volatile bool rtc_time_event_triggered     = false;
volatile bool rtc_calendar_event_triggered = false;
 
/* RTC interrupt callback. Reads the active flags and raises the matching
 * application-visible booleans. plib_rtc.c clears RTC_SR for us before
 * invoking this callback. */
void RTC_AlarmCallback(void)
{
    uint32_t flags = RTC_GetStatus();
 
    if ((flags & RTC_SR_ALARM_Msk) != 0U)
    {
        rtc_alarm_triggered = true;
    }
    if ((flags & RTC_SR_TIMEV_Msk) != 0U)
    {
        rtc_time_event_triggered = true;
    }
    if ((flags & RTC_SR_CALEV_Msk) != 0U)
    {
        rtc_calendar_event_triggered = true;
    }
}
 
int32_t configure_rtc(void)
{
    /* Disable every interrupt, clear pending status flags, and drop any
     * latched UPDTIM/UPDCAL so the next update handshake starts clean. */
    RTC_DisableInterrupt(RTC_IDR_Msk);
    RTC_ClearStatus(RTC_SCCR_Msk);
    RTC_ClearUpdateRequest();
 
    /* Hour mode and calendar mode. */
    RTC_SetHourMode(0U);                /* 0 = 24-hour, 1 = 12-hour */
    RTC_SelectCalendarMode(0U);         /* 0 = Gregorian, 1 = Persian */
 
    /* Waveform outputs: 1 Hz square on OUT0, programmable pulse on OUT1. */
    RTC_SetWaveformOutput(0U, RTC_MR_OUT0_FREQ1HZ_Val);
    RTC_SetWaveformOutput(1U, RTC_MR_OUT1_PROG_PULSE_Val);
    RTC_SetProgrammablePulse(RTC_MR_TPERIOD_P_1S_Val,
                             RTC_MR_THIGH_H_31MS_Val);
 
    /* Trigger TIMEV at midnight, CALEV on month change. */
    RTC_SetTimeEventSelection(RTC_CR_TIMEVSEL_MIDNIGHT_Val);
    RTC_SetCalendarEventSelection(RTC_CR_CALEVSEL_MONTH_Val);
 
    /* Stamp the wall clock 5 s before midnight on 18-May-2026 so the
     * rollover and alarms fire within seconds of the demo starting. */
    RTC_TIME initial_time = {
        .hour   = 0x23U,    /* 23 (BCD) */
        .minute = 0x59U,
        .second = 0x55U,
        .am_pm  = 0U
    };
    RTC_CALENDAR initial_calendar = {
        .century = 0x20U,   /* 2026 */
        .year    = 0x26U,
        .month   = 0x05U,   /* May */
        .date    = 0x18U,   /* 18th */
        .day     = 0x01U
    };
 
    RTC_ClearStatus(RTC_SCCR_SECCLR_Msk);
 
    (void)RTC_SetDateTime(&initial_time, &initial_calendar);
 
    /* Time alarm: fire at 00:00:10. */
    RTC_TIME_ALARM time_alarm = {
        .hour          = 0x00U,
        .minute        = 0x00U,
        .second        = 0x10U,
        .am_pm         = 0U,
        .enable_hour   = 1U,
        .enable_minute = 1U,
        .enable_second = 1U
    };
    (void)RTC_SetTimeAlarm(&time_alarm);
 
    /* Calendar alarm: fire on May 19. */
    RTC_CALENDAR_ALARM calendar_alarm = {
        .date         = 0x19U,
        .month        = 0x05U,
        .enable_date  = 1U,
        .enable_month = 1U
    };
    (void)RTC_SetCalendarAlarm(&calendar_alarm);
 
    /* Hand the callback to the PLIB. */
    RTC_SetCallbackHandler(&RTC_AlarmCallback);
 
    /* Enable the interrupt sources we're listening for. */
    RTC_EnableInterrupt(RTC_IER_ALREN_Msk
                      | RTC_IER_TIMEN_Msk
                      | RTC_IER_CALEN_Msk);
 
    return 0;
}

Typedef Documentation

◆ RTC_CALENDAR_EVENT

RTC_CALENDAR_EVENT

RTC calendar-event selector identifier.

Raw 2-bit code for RTC_CR.CALEVSEL. Accepted values are RTC_CR_CALEVSEL_*_Val macros from the device header.

◆ RTC_CALENDAR_MODE

RTC_CALENDAR_MODE

RTC calendar mode identifier.

Selects Gregorian or Persian calendar (RTC_MR.PERSIAN). Valid values: 0 (Gregorian), 1 (Persian).

◆ RTC_CALLBACK_HANDLER

typedef void(* RTC_CALLBACK_HANDLER) (void)

Function pointer type for RTC callback.

◆ RTC_HOUR_MODE

RTC_HOUR_MODE

RTC hour mode identifier.

Selects 24-hour or 12-hour time representation (RTC_MR.HRMOD). Valid values: 0 (24h), 1 (12h).

◆ RTC_THIGH

RTC_THIGH

RTC programmable-pulse high-duration identifier.

Raw 3-bit code for RTC_MR.THIGH. Accepted values are RTC_MR_THIGH_H_*_Val macros from the device header.

◆ RTC_TIME_EVENT

RTC_TIME_EVENT

RTC time-event selector identifier.

Raw 2-bit code for RTC_CR.TIMEVSEL. Accepted values are RTC_CR_TIMEVSEL_*_Val macros from the device header.

◆ RTC_TPERIOD

RTC_TPERIOD

RTC programmable-pulse period identifier.

Raw 2-bit code for RTC_MR.TPERIOD. Accepted values are RTC_MR_TPERIOD_P_*_Val macros from the device header.

◆ RTC_WAVEFORM_OUTPUT

RTC_WAVEFORM_OUTPUT

RTC output channel identifier.

Selects which RTCOUT pin (0 or 1) a waveform configuration targets.

◆ RTC_WAVEFORM_TYPE

RTC_WAVEFORM_TYPE

RTC waveform type identifier.

Raw 3-bit source code for the selected RTC_MR.OUTx field. Accepted values are the RTC_MR_OUT0_*_Val macros from the device header (e.g. RTC_MR_OUT0_FREQ1HZ_Val, RTC_MR_OUT0_ALARM_FLAG_Val).

Function Documentation

◆ RTC_ClearStatus()

void RTC_ClearStatus ( uint32_t status_mask )

Clears one or more status flags via RTC_SCCR.

Parameters

status_mask Bitwise OR of RTC_SCCR_*_Msk values from the DFP.

Returns: void

◆ RTC_ClearUpdateRequest()

void RTC_ClearUpdateRequest ( void )

Clears a latched UPDTIM/UPDCAL update request in RTC_CR. Use this to abort an in-progress or stale time/calendar update handshake (e.g. one left set by a previous run) before starting a fresh one.

Returns: void

◆ RTC_DisableInterrupt()

void RTC_DisableInterrupt ( uint32_t interrupt_mask )

Disables one or more RTC interrupt sources.

Parameters

interrupt_mask Bitwise OR of RTC_IDR_*_Msk values from the DFP.

Returns: void

◆ RTC_EnableInterrupt()

void RTC_EnableInterrupt ( uint32_t interrupt_mask )

Enables one or more RTC interrupt sources.

Parameters

interrupt_mask Bitwise OR of RTC_IER_*_Msk values from the DFP.

Returns: void

◆ RTC_GetCalendar()

bool RTC_GetCalendar ( RTC_CALENDAR * calendar )

Gets the current calendar from the RTC peripheral.

Parameters

calendar Pointer to destination structure. Must not be NULL.

Returns: true on success, false if RTC_SR.TDERR reports corrupted counters.

◆ RTC_GetStatus()

uint32_t RTC_GetStatus ( void )

Reads RTC_SR.

Returns: Bitwise OR of asserted RTC_SR_*_Msk flags.

◆ RTC_GetTime()

bool RTC_GetTime ( RTC_TIME * time_value )

Gets the current time from the RTC peripheral.

Parameters

time_value Pointer to destination structure. Must not be NULL.

Returns: true on success, false if RTC_SR.TDERR reports corrupted counters.

◆ RTC_SelectCalendarMode()

void RTC_SelectCalendarMode ( RTC_CALENDAR_MODE mode )

Selects the calendar mode (Gregorian or Persian).

Parameters

mode	RTC_CALENDAR_MODE value (0 = Gregorian, 1 = Persian).

Returns: void

◆ RTC_SetCalendar()

bool RTC_SetCalendar ( const RTC_CALENDAR * calendar )

Sets the current calendar in the RTC peripheral.

Parameters

calendar Pointer to BCD-encoded calendar. Must not be NULL.

Returns: true on success, false if the entry was rejected by RTC_VER.

Note: Blocks on the UPDCAL/ACKUPD handshake. Requires the 32.768 kHz slow clock (SLCK) to be running; if it is not, ACKUPD never asserts and this call does not return. Configure the slow clock before calling.

◆ RTC_SetCalendarAlarm()

bool RTC_SetCalendarAlarm ( const RTC_CALENDAR_ALARM * alarm )

Configures the calendar alarm.

Parameters

alarm Pointer to alarm configuration. Must not be NULL.

Returns: true on success, false if the entry was rejected by RTC_VER.

◆ RTC_SetCalendarEventSelection()

void RTC_SetCalendarEventSelection ( RTC_CALENDAR_EVENT event )

Selects which calendar-event trigger asserts RTC_SR.CALEV.

Parameters

event RTC_CALENDAR_EVENT value (raw RTC_CR.CALEVSEL code).

Returns: void

◆ RTC_SetCallbackHandler()

void RTC_SetCallbackHandler ( RTC_CALLBACK_HANDLER callback )

Registers the callback handler to be invoked from the RTC ISR.

Parameters

callback Pointer to the callback function (NULL to clear).

◆ RTC_SetDateTime()

bool RTC_SetDateTime	(	const RTC_TIME *	time_value,
		const RTC_CALENDAR *	calendar )

Sets both time and calendar atomically.

Parameters

time_value	Pointer to BCD-encoded time. Must not be NULL.
calendar	Pointer to BCD-encoded calendar. Must not be NULL.

Returns: true on success, false if either entry was rejected by RTC_VER.

Note: Blocks on the UPDTIM|UPDCAL/ACKUPD handshake. Requires the 32.768 kHz slow clock (SLCK) to be running; if it is not, ACKUPD never asserts and this call does not return. Configure the slow clock before calling.

◆ RTC_SetHourMode()

void RTC_SetHourMode ( RTC_HOUR_MODE mode )

Sets the hour mode (12h or 24h).

Parameters

mode	RTC_HOUR_MODE value (0 = 24h, 1 = 12h).

Returns: void

◆ RTC_SetProgrammablePulse()

void RTC_SetProgrammablePulse	(	RTC_TPERIOD	period,
		RTC_THIGH	high )

Configures the programmable pulse generator (RTC_MR.TPERIOD/THIGH).

Parameters

period	Pulse period selector.
high	Pulse high-duration selector.

Returns: void

◆ RTC_SetTime()

bool RTC_SetTime ( const RTC_TIME * time_value )

Sets the current time in the RTC peripheral.

Parameters

time_value Pointer to BCD-encoded time. Must not be NULL.

Returns: true on success, false if the entry was rejected by RTC_VER.

Note: Blocks on the UPDTIM/ACKUPD handshake. Requires the 32.768 kHz slow clock (SLCK) to be running; if it is not, ACKUPD never asserts and this call does not return. Configure the slow clock before calling.

◆ RTC_SetTimeAlarm()

bool RTC_SetTimeAlarm ( const RTC_TIME_ALARM * alarm )

Configures the time alarm.

Parameters

alarm Pointer to alarm configuration. Must not be NULL.

Returns: true on success, false if the entry was rejected by RTC_VER.

◆ RTC_SetTimeEventSelection()

void RTC_SetTimeEventSelection ( RTC_TIME_EVENT event )

Selects which time-event trigger asserts RTC_SR.TIMEV.

Parameters

event RTC_TIME_EVENT value (raw RTC_CR.TIMEVSEL code).

Returns: void

◆ RTC_SetWaveformOutput()

void RTC_SetWaveformOutput	(	RTC_WAVEFORM_OUTPUT	output,
		RTC_WAVEFORM_TYPE	type )

Configures the RTCOUT0 or RTCOUT1 output waveform.

Parameters

output	Which output to program (0 or 1).
type	Waveform source (raw RTC_MR_OUTx code).

Returns: void

Variable Documentation

◆ am_pm [1/2]

uint8_t RTC_TIME::am_pm

AM/PM (0=AM, 1=PM; 12h mode only)

◆ am_pm [2/2]

uint8_t RTC_TIME_ALARM::am_pm

AM/PM (12h mode only)

◆ century

uint8_t RTC_CALENDAR::century

Century (BCD, 0x19..0x20)

◆ date [1/2]

uint8_t RTC_CALENDAR::date

Day of month (BCD, 0x01-0x31)

◆ date [2/2]

uint8_t RTC_CALENDAR_ALARM::date

Day of month (BCD)

◆ day

uint8_t RTC_CALENDAR::day

Day of week (BCD, 0x01-0x07)

◆ enable_date

uint8_t RTC_CALENDAR_ALARM::enable_date

1 = match date, 0 = mask

◆ enable_hour

uint8_t RTC_TIME_ALARM::enable_hour

1 = match hour, 0 = mask

◆ enable_minute

uint8_t RTC_TIME_ALARM::enable_minute

1 = match minute, 0 = mask

◆ enable_month

uint8_t RTC_CALENDAR_ALARM::enable_month

1 = match month, 0 = mask

◆ enable_second

uint8_t RTC_TIME_ALARM::enable_second

1 = match second, 0 = mask

◆ hour [1/2]

uint8_t RTC_TIME::hour

Hour (BCD, 0x00-0x23 or 0x01-0x12)

◆ hour [2/2]

uint8_t RTC_TIME_ALARM::hour

Hour (BCD)

◆ minute [1/2]

uint8_t RTC_TIME::minute

Minute (BCD, 0x00-0x59)

◆ minute [2/2]

uint8_t RTC_TIME_ALARM::minute

Minute (BCD)

◆ month [1/2]

uint8_t RTC_CALENDAR::month

Month (BCD, 0x01-0x12)

◆ month [2/2]

uint8_t RTC_CALENDAR_ALARM::month

Month (BCD)

◆ second [1/2]

uint8_t RTC_TIME::second

Second (BCD, 0x00-0x59)

◆ second [2/2]

uint8_t RTC_TIME_ALARM::second

Second (BCD)

◆ year

uint8_t RTC_CALENDAR::year

Year within century (BCD, 0x00-0x99)

Data Structures

Typedefs

Functions

Variables

Description

Usage Example

Typedef Documentation

◆ RTC_CALENDAR_EVENT

◆ RTC_CALENDAR_MODE

◆ RTC_CALLBACK_HANDLER

◆ RTC_HOUR_MODE

◆ RTC_THIGH

◆ RTC_TIME_EVENT

◆ RTC_TPERIOD

◆ RTC_WAVEFORM_OUTPUT

◆ RTC_WAVEFORM_TYPE

Function Documentation

◆ RTC_ClearStatus()

◆ RTC_ClearUpdateRequest()

◆ RTC_DisableInterrupt()

◆ RTC_EnableInterrupt()

◆ RTC_GetCalendar()

◆ RTC_GetStatus()

◆ RTC_GetTime()

◆ RTC_SelectCalendarMode()

◆ RTC_SetCalendar()

◆ RTC_SetCalendarAlarm()

◆ RTC_SetCalendarEventSelection()

◆ RTC_SetCallbackHandler()

◆ RTC_SetDateTime()

◆ RTC_SetHourMode()

◆ RTC_SetProgrammablePulse()

◆ RTC_SetTime()

◆ RTC_SetTimeAlarm()

◆ RTC_SetTimeEventSelection()

◆ RTC_SetWaveformOutput()

Variable Documentation

◆ am_pm [1/2]

◆ am_pm [2/2]

◆ century

◆ date [1/2]

◆ date [2/2]

◆ day

◆ enable_date

◆ enable_hour

◆ enable_minute

◆ enable_month

◆ enable_second

◆ hour [1/2]

◆ hour [2/2]

◆ minute [1/2]

◆ minute [2/2]

◆ month [1/2]

◆ month [2/2]

◆ second [1/2]

◆ second [2/2]

◆ year