RTC exported functions

RTC exported write protection and initialization mode functions.

group RTC_Exported_Functions_Write_Init

Write protection and initialization mode.

RTC write protection.

The RTC peripheral has its own write protection. After backup domain reset, some of the RTC registers are protected against parasitic write access.

Calling HAL_RTC_DisableWriteProtection and HAL_RTC_EnableWriteProtection disables and enables the write protection respectively.

Initialization mode

The initialization mode of the RTC permits to initialize and configure the RTC calendar. Entering this mode stops the calendar counter.

Calling HAL_RTC_EnterInitMode and HAL_RTC_ExitInitMode makes the RTC enter and exit initialization mode, respectively.

Functions

hal_status_t HAL_RTC_EnableWriteProtection ( void )

Enable the RTC registers write protection.

Note

Not all RTC registers are concerned by the write protection.

Return values :

HAL_OK –

hal_status_t HAL_RTC_DisableWriteProtection ( void )

Disable the RTC registers write protection.

Note

Not all RTC registers are concerned by the write protection.

Return values :

HAL_OK –

hal_status_t HAL_RTC_EnterInitMode ( void )

Enter the RTC initialization mode.

Warning

The RTC initialization mode is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

  • HAL_OK –

  • HAL_ERROR – RTC doesn’t enter initialization mode before the RTC timeout duration.

hal_status_t HAL_RTC_ExitInitMode ( void )

Exit the RTC initialization mode.

Warning

the RTC initialization mode is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

  • HAL_OK –

  • HAL_ERROR – Calendar resynchronization is still pending after timeout duration.

RTC exported configuration functions

group RTC_Exported_Functions_Config

Configuration functions for prescaler values and RTC mode.

RTC clock and prescalers

The RTC clock named RTCCLK is configured by the RCC driver by using HAL_RCC_RTC_SetKernelClkSource. The RTCCLK source can be LSE, LSI or HSE. The RTC peripheral has got a programmable prescaler stage which can be configured to generate a 1Hz clock. To minimize consumption, the prescaler is split into 2 programmable prescalers:

  • A 7-bit asynchronous prescaler (PREDIV_A).

  • A 15-bit synchronous prescaler (PREDIV_S).

When using both prescalers, it’s recommended to configure the asynchronous prescaler to a high value to minimize consumption. By default, the asynchronous and synchronous are set to 128 and 256, to obtain a clock frequency of 1 Hz with a RTCCLK configured to an LSE of 32.768 kHz.

The following equation gives us the clock frequency after the first prescaler : freq_async_clk = freq_rtcclk/(1+hal_rtc_config_t::asynch_prediv)

The following equation gives us the clock frequency after the two prescalers : freq_sync_clk = freq_rtcclk/((1+ hal_rtc_config_t::asynch_prediv)(1+ hal_rtc_config_t::synch_prediv))

The values of the prescalers can be changed by calling HAL_RTC_SetConfig and setting the value of hal_rtc_config_t::asynch_prediv and hal_rtc_config_t::synch_prediv. To change the values of the prescalers, the RTC needs to be in initialization mode by calling HAL_RTC_EnterInitMode .

RTC running modes.

RTC supports three modes of operating.

  • BCD mode for Binary-Coded Decimal

  • Binary mode

  • Mixed mode

The mode is chosen by selecting the value of hal_rtc_config_t::mode and call the HAL_RTC_SetConfig .

Binary-Coded Decimal mode

The BCD mode is a feature that allows the RTC to store and display time and date information in a BCD format. BCD is a way of representing decimal numbers using four bits per digit, with each digit ranging from 0 to 9.

In BCD mode the subseconds down-counter is clocked by the signal after the first prescaler. When the down-counter reaches 0, it’s reloaded with the value of the synchronous prescaler. Only the first 16 bits of the subsecond register are used in BCD mode.

Binary mode

In binary mode the subseconds down-counter is clocked by the signal after the first prescaler. The subsecond register is extended to 32-bit length and is free running. The value of the synchronous register does not care and the time and date registers are not used.

In this mode the users can use all functions that include the keyword Binary in their names, that are optimized for it.

Mixed mode

This mode, as stated by its name, is a mix between the two previous modes. The subseconds down-counter is extended to 32 bits length and it’s free running. The time and date calendar in BCD are also functional.

The down-counter is still clocked by the signal after the asynchronous prescaler but the seconds of the calendar are incremented each time the least significant bits of the subsecond register reach 0. The number of bits taken in account are defined by the user by using the HAL_RTC_SetConfig and changing the value of hal_rtc_config_t::seconds_update.

To change the RTC mode, the RTC needs to be in initialization mode by calling HAL_RTC_EnterInitMode .

Functions

hal_status_t HAL_RTC_SetConfig ( const hal_rtc_config_t * p_config )

Program the RTC prescalers values and the RTC mode according to the specified parameters.

Warning

The RTC configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC configuration must be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

p_config – pointer to a RTC configuration instance.

Return values :

  • HAL_OK. –

  • HAL_INVALID_PARAM – p_config is NULL.

void HAL_RTC_GetConfig ( hal_rtc_config_t * p_config )

Retrieve the RTC prescalers values and the RTC mode.

Parameters :

p_config – pointer to a RTC configuration instance.

RTC exported low power configuration functions

group RTC_Exported_Functions_Low_Power

Low power configuration functions.

It is possible to drastically reduce the RTC power consumption by setting the RTC to low power mode. In this configuration the whole RTC is clocked by the ck_apre.

When the division factor of the asynchronous prescaler is not a power of 2 (( hal_rtc_config_t::asynch_prediv +1) % 2 == 0), the low power mode can’t be activated.

Functions

hal_status_t HAL_RTC_EnableUltraLowPowerMode ( void )

Enable the RTC ultra low power mode.

Note

When ( hal_rtc_config_t::asynch_prediv + 1) is not a power of 2 , calling this function won’t enable the low power mode.

Warning

The RTC low power configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_status_t HAL_RTC_DisableUltraLowPowerMode ( void )

Disable the RTC ultra low power mode.

Warning

The RTC configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_rtc_ultra_low_power_mode_status_t HAL_RTC_IsEnabledUltraLowPowerMode ( void )

Check if the RTC ultra low power mode is enabled or not.

Return values :

hal_rtc_ultra_low_power_mode_status_t – Ultra low power mode status.

RTC exported calendar functions

group RTC_Exported_Functions_Calendar

Exported calendar functions.

The calendar of RTC store and display time and date information in a BCD format. It includes subseconds, seconds, minutes, hours, weekday, date, month, year. The calendar only works when using the BCD and mixed mode otherwise only the subseconds down-counter register works.

Calendar configuration

Calendar hour format and shadow registers.

The user can set the hour format to 24 hours or 12 hours format by programming the hal_rtc_calendar_config_t::hour_format and calling HAL_RTC_CALENDAR_SetConfig function.

Shadow registers

The shadow registers mirror the values of the calendar date and time registers. When the shadow registers are not bypassed the application reads the values of date and time in the shadow registers. Reading the time locks the values in calendar shadow registers to ensure consistency between time and date values, reading the date unlocks them. The user needs to call the function HAL_RTC_CALENDAR_GetTime before HAL_RTC_CALENDAR_GetDate , or call only HAL_RTC_CALENDAR_GetDateTime functions to retrieve the time and date correctly.

The application can have direct access to the date and time registers by bypassing the shadow registers. Use the hal_rtc_calendar_config_t::bypass_shadow_register to configure the shadow register bypass.

Other calendar services

Reference clock detection

In BCD mode only, the update of the RTC calendar can be synchronized to a reference clock. This reference clock is used to compensate for the imprecision of the calendar seconds update frequency.

This detection is only enabled if the prescaler are set to their default values which are 128 and 256 for hal_rtc_config_t::asynch_prediv and hal_rtc_config_t::synch_prediv respectively.

Binary mode

A dedicated API is given to optimize the code when using the binary mode. The function HAL_RTC_CALENDAR_GetBinaryTime retrieves the value of the subseconds down-counter register.

Summer time and hour increment decrement

The functions HAL_RTC_CALENDAR_EnableSummerTimeMemorization and HAL_RTC_CALENDAR_DisableSummerTimeMemorization allow an application to keep information about the summer time status. Those functions don’t alter the hours registers and the application needs to increment or decrement the hours by using HAL_RTC_CALENDAR_AddOneHour and HAL_RTC_CALENDAR_SubtractOneHour respectively, which are independent of the summer time memorization bit.

Subseconds underflow

In binary mode or mixed mode, the user can enable the sub-seconds underflow interruption. This interruption triggers when the subseconds down-counter underflows.

Functions

hal_status_t HAL_RTC_CALENDAR_SetConfig ( const hal_rtc_calendar_config_t * p_config_calendar )

Program the bypass shadow registers and calendar hour format according to the specified parameters.

Warning

The RTC calendar configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC calendar configuration needs to be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

p_config_calendar – pointer to an RTC calendar configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config_calendar is NULL.

void HAL_RTC_CALENDAR_GetConfig ( hal_rtc_calendar_config_t * p_config_calendar )

Retrieve the bypass shadow registers and calendar hour format configuration.

Parameters :

p_config_calendar – pointer to an RTC calendar configuration instance.

hal_status_t HAL_RTC_CALENDAR_SetTime ( const hal_rtc_time_t * p_time )

Program the RTC time.

Note

hal_rtc_time_t::microsec field is ignored because it is not used in the SetTime function.

Note

hal_rtc_time_t::millisec field is ignored because it is not used in the SetTime function.

Note

hal_rtc_time_t::subsec field is ignored because it is not used in the SetTime function.

Warning

The RTC time configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC time configuration needs to be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

p_time – pointer to an RTC time instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_time is NULL.

hal_status_t HAL_RTC_CALENDAR_GetTime ( hal_rtc_time_t * p_time )

Retrieve the RTC time.

Note

When using the shadow registers (default): Reading RTC current time locks the values in calendar shadow registers to ensure consistency between time and date values. Call HAL_RTC_CALENDAR_GetDate to unlock the time value.

Parameters :

p_time – pointer to an RTC time instance.

Return values :

  • HAL_OK –

  • HAL_ERROR – when a timeout occurs on the shadow register flag

hal_status_t HAL_RTC_CALENDAR_SetDate ( const hal_rtc_date_t * p_date )

Program the RTC date.

Warning

The RTC date configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC date configuration needs to be called when RTC is in initialized mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

p_date – pointer to an RTC date instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_date is NULL.

hal_status_t HAL_RTC_CALENDAR_GetDate ( hal_rtc_date_t * p_date )

Retrieve the RTC date.

Parameters :

p_date – pointer to an RTC date instance.

Return values :

  • HAL_OK –

  • HAL_ERROR – when a timeout occurs on the shadow register flag

hal_status_t HAL_RTC_CALENDAR_SetDateTime ( const hal_rtc_date_t * p_date , const hal_rtc_time_t * p_time )

Program the RTC date and time.

Note

hal_rtc_time_t::microsec field is ignored because it is not used in the SetDateTime function.

Note

hal_rtc_time_t::millisec field is ignored because it is not used in the SetDateTime function.

Note

hal_rtc_time_t::subsec field is ignored because it is not used in the SetDateTime function.

Warning

The RTC date and time configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC date and time configuration needs to be called when RTC is in initialized mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

  • p_date – pointer to an RTC date instance.

  • p_time – pointer to an RTC time instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_date or p_time are NULL.

hal_status_t HAL_RTC_CALENDAR_GetDateTime ( hal_rtc_date_t * p_date , hal_rtc_time_t * p_time )

Retrieve the RTC date and time.

Parameters :

  • p_date – pointer to an RTC date instance.

  • p_time – pointer to an RTC time instance.

Return values :

  • HAL_OK –

  • HAL_ERROR – when a timeout occurs on the shadow register flag

hal_status_t HAL_RTC_CALENDAR_EnableReferenceClock ( void )

Enable the reference clock detection.

Note

The detection only works when RTC is set to BCD mode only HAL_RTC_MODE_BCD, the synchronous prescaler hal_rtc_config_t::synch_prediv and the asynchronous prescaler hal_rtc_config_t::asynch_prediv are set to 0x00FF (default value) and to 0x007F (default-value) respectively.

Warning

The RTC reference clock configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC reference clock configuration needs to be called when RTC is in initialized mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_DisableReferenceClock ( void )

Disable the reference clock detection.

Warning

The RTC reference clock configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC reference clock configuration needs to be called when RTC is in initialized mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Return values :

HAL_OK –

hal_rtc_calendar_reference_clock_status_t HAL_RTC_CALENDAR_IsEnabledReferenceClock ( void )

Check if the reference clock detection is enabled or disabled.

Return values :

hal_rtc_calendar_reference_clock_status_t – Reference clock detection status

hal_status_t HAL_RTC_CALENDAR_AddOneHour ( void )

Add one hour to the calendar in one single operation without going through the initialization procedure.

Warning

The RTC hour increment is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_SubtractOneHour ( void )

Subtract one hour to the calendar in one single operation without through the initialization procedure.

Warning

The RTC hour decrement is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_EnableSummerTimeMemorization ( void )

Enable the summer time memorization bit status.

Warning

The RTC summer time memorization bit is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_DisableSummerTimeMemorization ( void )

Disable the summer time memorization bit status.

Warning

The RTC summer time memorization bit is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_rtc_calendar_summer_time_status_t HAL_RTC_CALENDAR_IsEnabledSummerTimeMemorization ( void )

Check if the summer time memorization bit is enabled or disabled.

Return values :

hal_rtc_calendar_summer_time_status_t – Summer time memorization bit status.

uint32_t HAL_RTC_CALENDAR_GetBinaryTime ( void )

Retrieve the subsecond register value.

Return values :

uint32_t – Value of the subsecond register.

hal_status_t HAL_RTC_CALENDAR_EnableITSubSecondsUnderflow ( void )

Enable the subsecond register underflow interruption.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_DisableITSubSecondsUnderflow ( void )

Disable the subsecond register underflow interruption.

Return values :

HAL_OK –

hal_rtc_calendar_it_underflow_status_t HAL_RTC_CALENDAR_IsEnabledITSubSecondsUnderflow ( void )

Check if the subsecond register underflow interruption is enabled or disabled.

Return values :

hal_rtc_calendar_it_underflow_status_t – Subsecond register underflow interruption status

hal_rtc_calendar_status_t HAL_RTC_CALENDAR_IsInitialized ( void )

Check if the calendar is initialized.

Return values :

hal_rtc_calendar_status_t – Calendar initialization status.

RTC exported output functions

group RTC_Exported_Functions_Output

Exported output functions.

To enable the output signals the application must call HAL_RTC_OUTPUT_Enable . To use the RTC_OUT1 as input all outputs must be disabled on RTC_OUT1, therefore the application can disable all outputs by calling HAL_RTC_OUTPUT_Disable or configure the outputs on RTC_OUT2 by calling HAL_RTC_OUTPUT_Enable with hal_rtc_output_t values containing only OUT2 in their names.

Configuration of the TAMPALRM output signal

The TAMPALRM outputs i the OR between rtc_tamp_evt and ALARM output.

ALARM output can be selected between alarm A, alarm B or wake-up outputs.

Depending on the user needs the polarity, the output type and the use of a pull-up can be configured by using HAL_RTC_OUTPUT_SetConfigTampalarm . When configuring the output to an open-drain, the GPIO must be set as input by using the HAL_GPIO_Init from the GPIO driver.

Configuration of the calibration output signal

The calibration output signal corresponds to the RTCCLK clock signal after the 6th stage of the asynchronous prescaler or the 8th stage of the synchronous prescaler (and all the asynchronous prescaler).

To choose between these two configurations, the application needs to call the HAL_RTC_OUTPUT_SetConfigCalib

Asynchronous clock calibration

The calibration clock is the output of the 6th stage of the asynchronous prescaler. Thus, only the 6 first bits are used to define the calibration frequency. The frequency of the output is (freq_RTCCLK / (PREDIV_A[5:0]+1)), PREDIV_A given by hal_rtc_config_t::asynch_prediv.

If low power mode is disabled and the value of the asynchronous prescaler is strictly below 0x20, the calibration signal output doesn’t work.

With the prescaler at default values and using LSE, the clock frequency is 512Hz.

Synchronous clock calibration

The calibration output is the output of the 8th stage of the synchronous prescaler. Thus, only the 8 first bits are used to define the calibration frequency. The frequency of the output is (freq_RTCCLK/((PREDIV_A+1) * (PREDIV_S[7:0] +1)). PREDIV_S and PREDIV_A given by hal_rtc_config_t::synch_prediv and hal_rtc_config_t::asynch_prediv respectively.

With the prescaler at default values and using LSE, the clock frequency is 1Hz.

Functions

hal_status_t HAL_RTC_OUTPUT_SetConfigTampalarm ( const hal_rtc_output_tampalarm_config_t * p_config )

Program the tampalarm configuration.

Warning

When configuring tampalarm in open-drain mode HAL_RTC_OUTPUT_TAMPALARM_TYPE_OPENDRAIN The RTC_OUT1 GPIO must be set to input in GPIO driver.

Parameters :

p_config – pointer to the tampalarm configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config is NULL.

void HAL_RTC_OUTPUT_GetConfigTampalarm ( hal_rtc_output_tampalarm_config_t * p_config )

Retrieve the tampalarm configuration.

Parameters :

p_config – pointer to the tampalarm configuration instance.

hal_status_t HAL_RTC_OUTPUT_SetConfigCalib ( const hal_rtc_output_calib_config_t * p_config )

Program the calibration output configuration.

Note

When using the synchronous calibration (1Hz by default), the calibration output is the output of the 8th stage of the synchronous prescaler. Thus only the 8 first bits are used to define the calibration frequency The frequency of the output is (f_RTCCLK/((PREDIV_A+1) * (PREDIV_S[7:0] +1)).

Note

When using the asynchronous calibration (512Hz by default), the calibration output is the output of the asynchronous prescaler 6th stage. Thus only the 6 first bits are used to define the calibration frequency. The frequency of the output is (f_RTCCLK / (PREDIV_A[5:0]+1)).

Warning

If low power mode is disabled and the value of the asynchronous prescaler hal_rtc_config_t::asynch_prediv is strictly below 0x20, the calibration signal output doesn’t work.

Parameters :

p_config – pointer to the calibration output configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config is NULL.

void HAL_RTC_OUTPUT_GetConfigCalib ( hal_rtc_output_calib_config_t * p_config )

Retrieve the calibration output configuration.

Parameters :

p_config – pointer to the calibration output configuration instance.

hal_status_t HAL_RTC_OUTPUT_Enable ( hal_rtc_output_t output )

Enable the output of the calibration signal or/and tampalarm signal.

Parameters :

output – Value of hal_rtc_output_t.

Return values :

HAL_OK –

hal_status_t HAL_RTC_OUTPUT_Disable ( void )

Disable the output RTC output.

Return values :

HAL_OK –

hal_rtc_output_status_t HAL_RTC_OUTPUT_IsEnabled ( hal_rtc_output_t output )

Check if the RTC output is enabled or disabled.

Parameters :

output – Value of hal_rtc_output_t representing the output configuration to be checked.

Return values :

hal_rtc_output_status_t:HAL_RTC_OUTPUT_DISABLED – RTC output status.

RTC exported calendar calibration functions

group RTC_Exported_Functions_Calibration

Exported calibration functions.

Smooth digital calibration

The RTC frequency can be calibrated with a very small resolution of about 0.954 ppm with a range from -487.1 ppm to 488.5 ppm. This adjustment is made on the RTCCLK or the clock after the asynchronous prescaler when low power mode is enabled.

To activate the smooth calibration, one needs to call HAL_RTC_EnableCalibration with the parameters pulse_add or subtracted_pulses set to HAL_RTC_CALIBRATION_PULSE_INSERTED or a value different from 0 respectively. The subtracted_pulses specifies the number of pulses of the clock to be masked during the calibration cycle chosen by the calibration_period. If calibration_period is set to HAL_RTC_CALIBRATION_PERIOD_16SEC or HAL_RTC_CALIBRATION_PERIOD_8SEC the first bit and the two first bit are stuck at 0 respectively.

Setting the pulse_add parameter inserts one extra pulse every 2^11 cycles which doesn’t dependent on the calibration period.

The frequency after calibration is given by this formula freq_calib = freq_RTCCLK x [1 + ( pulse_add x 512 - subtracted_pulses) / (2^20 + subtracted_pulses - pulse_add x 512)]

When the value of the asynchronous prescaler hal_rtc_config_t::asynch_prediv is inferior to 3 no pulses are inserted, thus making the parameter pulse_add is ignored.

To stop the calibration call HAL_RTC_DisableCalibration . To retrieve the status of the calibration call HAL_RTC_IsEnabledCalibration .

Synchronization of RTC the calendar

After reading the subsecond register and calculating an offset with the remote clock, the goal of this feature is to synchronize the RTC by adding/subtracting the offset to synchronize the RTC with the remote clock. The shift operation consists of adding or subtracting some subseconds depending on the parameters of the HAL_RTC_ShiftCalibration . The param add_one_sec adds one second to the time register and the param fraction_sec_to_subtract subtract some subseconds to the subsecond register.

The shift operation doesn’t work properly in different cases:

  1. In BCD mode :HAL_RTC_MODE_BCD, if the reference clock is enabled.

  2. In BCD mode :HAL_RTC_MODE_BCD, the 15th value of the subsecond register is equal to 1.

  3. In mixed mode :HAL_RTC_MODE_MIX, the fraction_sec_to_subtract [14, hal_rtc_config_t::seconds_update ] must be equal to 0.

  4. In mixed mode :HAL_RTC_MODE_MIX the BCD increment value hal_rtc_config_t::seconds_update in the subsecond register must be equal to 0.

Functions

hal_status_t HAL_RTC_EnableCalibration ( hal_rtc_calibration_period_t calibration_period , hal_rtc_calibration_pulse_t pulse_add , uint32_t subtracted_pulses )

Enable the smooth calibration parameters.

Note

To activate the smooth calibration, the parameters pulse_add or subtracted_pulses must be set to HAL_RTC_CALIBRATION_PULSE_INSERTED or a value different from 0 respectively. If calibration_period is set to HAL_RTC_CALIBRATION_PERIOD_16SEC or HAL_RTC_CALIBRATION_PERIOD_8SEC the first bit and the two first bit are stuck at 0 respectively. If PREDIV_A ( hal_rtc_config_t::asynch_prediv) is inferior to 3, the bit CALP set by pulse_add is always equal to 0, thus pulse_add is ignored. The frequency after calibration is given by this formula : F_CAL = F_RTCCLK x [1 + ( pulse_add x 512 - subtracted_pulses) / (2^20 + subtracted_pulses - pulse_add x 512)]

Warning

The RTC calibration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

When in low power mode (by using HAL_RTC_EnableUltraLowPowerMode ) the calibration mechanism is applied on the RTCCLK after going through the asynchronous prescaler.

Parameters :

  • calibration_period – Select the smooth calibration period, values from hal_rtc_calibration_period_t.

  • pulse_add – Choose between increasing the frequency by one pulse every 2^11 pulses or nothing hal_rtc_calibration_pulse_t.

  • subtracted_pulses – Number of pulses to subtract out of 2^20 pulses.

Return values :

  • HAL_OK –

  • HAL_ERROR – if a recalibration operation is still ongoing after RTC timeout duration.

hal_status_t HAL_RTC_DisableCalibration ( void )

Disable the smooth calibration parameters.

Warning

The RTC calibration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

  • HAL_OK –

  • HAL_ERROR – if a recalibration operation is still ongoing after RTC timeout duration.

hal_rtc_calibration_status_t HAL_RTC_IsEnabledCalibration ( void )

Check if the smooth calibration is enabled.

Return values :

hal_rtc_calibration_status_t – RTC smooth calibration status.

hal_status_t HAL_RTC_ShiftCalibration ( hal_rtc_calibration_shift_second_t add_one_sec , uint32_t fraction_sec_to_subtract )

Shift the RTC clock (Subsecond Register) by a fraction of a second.

Note

the RTC calibration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

This feature is not compatible with the reference clock detection feature enabled by HAL_RTC_CALENDAR_EnableReferenceClock

Warning

This function will not decrease the number of seconds nor overflow the subsecond register.

Parameters :

  • add_one_sec – Choose between adding one second to the clock.

  • fraction_sec_to_subtract – Number of fraction of a second to subtract.

Return values :

  • HAL_OK –

  • HAL_ERROR – if the shift operation is still pending after RTC timeout duration. if the reference clock detection is enabled. In BCD mode :HAL_RTC_MODE_BCD the 15th value of the subsecond register is equal to 1. In mixed mode :HAL_RTC_MODE_MIX the fraction_sec_to_subtract [14, hal_rtc_config_t::seconds_update ] must be equal to 0, In mixed mode :HAL_RTC_MODE_MIX the BCD increment value hal_rtc_config_t::seconds_update in the subsecond register must be equal to 0.

RTC exported alarm functions

group RTC_Exported_Functions_Alarms

Exported alarms functions.

The RTC unit provides two programmable alarms. The alarms triggers when the calendar subseconds, seconds, minutes, hours, month day or weekday match the values of the alarm. Each field can be independently masked by setting hal_rtc_alarm_date_time_t::mask. When the alarm triggers it can be automatically cleared by setting the parameter hal_rtc_alarm_config_t::auto_clear to :HAL_ALARM_AUTO_CLEAR_ENABLE.

To update the alarms configuration, RTC needs to be in initialization mode or the alarms must be disabled by using HAL_RTC_EnterInitMode or HAL_RTC_ALARM_Stop respectively.

Binary mode

When using the binary mode only the subsecond registers are compared. A dedicated API is given to optimize the code. The subseconds down-counter register can be reloaded every time the alarms triggers which means that the subseconds down-counter register is running from 0xFFFF FFFF to the value set in the subseconds registers of the alarm. This can only be used in binary mode. This is configured by setting hal_rtc_alarm_config_t::subsec_auto_reload to HAL_RTC_ALARM_SUBSECONDS_AUTO_RELOAD_ENABLE.

Functions

hal_status_t HAL_RTC_ALARM_SetConfig ( hal_rtc_alarm_t alarm , const hal_rtc_alarm_config_t * p_config_alarm )

Configure the alarm parameters.

Note

hal_rtc_alarm_config_t::subsec_auto_reload is only used in binary mode.

Parameters :

  • alarm – Select the alarm A or B.

  • p_config_alarm – Pointer to the alarm configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config_alarm is NULL.

  • HAL_ERROR – if the alarm is started AND the RTC is not in initialization mode. or if p_config_alarm->subsec_auto_reload is set to LL_RTC_ALMA_SUBSECONDBIN_AUTOCLR_YES and RTC is in BCD or Mixed mode.

void HAL_RTC_ALARM_GetConfig ( hal_rtc_alarm_t alarm , hal_rtc_alarm_config_t * p_config_alarm )

Retrieve the alarm configuration.

Parameters :

  • alarm – Select the alarm A or B.

  • p_config_alarm – Pointer to the alarm configuration instance.

hal_status_t HAL_RTC_ALARM_SetDateTime ( hal_rtc_alarm_t alarm , const hal_rtc_alarm_date_time_t * p_date_time )

Configure the alarm date and time.

Warning

The synchronous prescaler value, hal_rtc_config_t::synch_prediv, must be superior to 3 when seconds are unmasked.

Parameters :

  • alarm – Select the alarm A or B.

  • p_date_time – Pointer to the alarm date and time instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_date_time is NULL.

  • HAL_ERROR – if the alarm is started AND the RTC is not in initialization mode.

void HAL_RTC_ALARM_GetDateTime ( hal_rtc_alarm_t alarm , hal_rtc_alarm_date_time_t * p_date_time )

Retrieve the alarm date and time.

Parameters :

  • alarm – Select the alarm A or B.

  • p_date_time – Pointer to the alarm date and time instance.

hal_status_t HAL_RTC_ALARM_Start ( hal_rtc_alarm_t alarm , uint32_t interruption )

Start the alarm.

Parameters :
Return values :

HAL_OK –

hal_status_t HAL_RTC_ALARM_Stop ( hal_rtc_alarm_t alarm )

Stop the alarm.

Parameters :

alarm – Select the alarm A or B.

Return values :

HAL_OK –

hal_status_t HAL_RTC_ALARM_PollForEvent ( hal_rtc_alarm_t alarm , uint32_t timeout_ms )

Poll for alarm event.

Parameters :

  • alarm – Select the alarm A or B.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_OK –

  • HAL_TIMEOUT – when reaching the timeout during polling.

hal_status_t HAL_RTC_ALARM_SetBinaryTime ( hal_rtc_alarm_t alarm , uint32_t alarm_subsecond )

Program the alarm subseconds.

Note

This function can be used only in binary mode, but can be used in BCD or mixed mode. Prefer HAL_RTC_ALARM_SetDateTime to program the alarm in BCD or mixed mode.

Parameters :

  • alarm – Select the alarm A or B.

  • alarm_subsecond – Alarm subsecond value. Value between 0x0 and 0xFFFFFFFF.

Return values :

  • HAL_OK –

  • HAL_ERROR –

uint32_t HAL_RTC_ALARM_GetBinaryTime ( hal_rtc_alarm_t alarm )

Retrieve the alarm subseconds.

Note

This function must be used only in binary mode, but can be used in BCD or mixed mode. Prefer HAL_RTC_ALARM_GetDateTime to retrieve alarm subseconds alarm in BCD or mixed mode.

Parameters :

alarm – Select the alarm A or B.

Return values :

uint32_t – Alarm subseconds.

hal_status_t HAL_RTC_ALARM_SetBinarySubSecondMask ( hal_rtc_alarm_t alarm , uint32_t alarm_subsecond_mask )

Program the alarm subseconds mask.

Note

This function must be used only in binary mode, but can be used in BCD or mixed mode. Prefer HAL_RTC_ALARM_SetDateTime to program the alarm in BCD or mixed mode.

Parameters :

  • alarm – Select the alarm A or B.

  • alarm_subsecond_mask – Alarm subsecond mask. Value between 0x0 to 0x3F.

Return values :

HAL_OK –

uint32_t HAL_RTC_ALARM_GetBinarySubSecondMask ( hal_rtc_alarm_t alarm )

Retrieve the alarm subseconds mask.

Note

This function must be used in binary mode, but can be used in BCD or mixed mode. Prefer HAL_RTC_ALARM_GetDateTime to retrieve alarm subseconds mask in BCD or mixed mode.

Parameters :

alarm – Select the alarm A or B.

Return values :

uint32_t – Alarm subseconds mask.

RTC exported time stamp functions

group RTC_Exported_Functions_Timestamp

Exported timestamp functions.

Timestamp is enabled by setting the TSE bit of RTC_CR register to 1. When TSE is set: The calendar is saved in the timestamp registers (RTC_TSSSR, RTC_TSTR, RTC_TSDR) when a timestamp event is detected on the RTC_TS pin.

When TAMPTS is set: The calendar is saved in the timestamp registers (RTC_TSSSR, RTC_TSTR, RTC_TSDR) when an internal or external tamper event is detected.

After a timestamp event, by calling the HAL_RTC_TIMESTAMP_GetDateTime , the application can retrieves the date and time of the last timestamp event and clear the timestamp registers.

Functions

hal_status_t HAL_RTC_TIMESTAMP_SetConfig ( const hal_rtc_timestamp_config_t * p_config_timestamp )

Configure the RTC timestamp.

Parameters :

p_config_timestamp – pointer to an RTC timestamp configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config_timestamp is NULL.

void HAL_RTC_TIMESTAMP_GetConfig ( hal_rtc_timestamp_config_t * p_config_timestamp )

Retrieve the RTC timestamp configuration.

Parameters :

p_config_timestamp – pointer to an RTC timestamp configuration instance.

hal_status_t HAL_RTC_TIMESTAMP_EnablePinSource ( void )

Enable the RTC timestamp from the external pin (RTC_TS).

Return values :

HAL_OK –

hal_status_t HAL_RTC_TIMESTAMP_DisablePinSource ( void )

Disable the RTC timestamp from the external pin (RTC_TS).

Return values :

HAL_OK –

hal_rtc_timestamp_status_t HAL_RTC_TIMESTAMP_IsEnabledPinSource ( void )

Check if the RTC timestamps from the external pin (RTC_TS) is enabled.

Return values :

hal_rtc_timestamp_status_t – RTC timestamp from the external pin status.

hal_status_t HAL_RTC_TIMESTAMP_EnableInternalSource ( void )

Enable the RTC timestamp on the internal event.

Return values :

HAL_OK –

hal_status_t HAL_RTC_TIMESTAMP_DisableInternalSource ( void )

Disable the RTC timestamp on the internal event.

Return values :

HAL_OK –

hal_rtc_timestamp_status_t HAL_RTC_TIMESTAMP_IsEnabledInternalSource ( void )

Check if the RTC timestamp on the internal event is enabled.

Return values :

hal_rtc_timestamp_status_t – RTC timestamp from the external pin status

hal_status_t HAL_RTC_TIMESTAMP_EnableTamperSource ( void )

Enable the RTC timestamp on tamper event.

Return values :

HAL_OK –

hal_status_t HAL_RTC_TIMESTAMP_DisableTamperSource ( void )

Disable the RTC timestamp on tamper event.

Return values :

HAL_OK –

hal_rtc_timestamp_tamper_status_t HAL_RTC_TIMESTAMP_IsEnabledTamperSource ( void )

Check if the RTC timestamp on tamper event is enabled or not.

Return values :

hal_rtc_timestamp_tamper_status_t – RTC timestamp on tamper event status.

hal_status_t HAL_RTC_TIMESTAMP_EnableIT ( void )

Enable the RTC timestamp interrupt.

Return values :

HAL_OK –

hal_status_t HAL_RTC_TIMESTAMP_DisableIT ( void )

Disable the RTC timestamp interrupt.

Return values :

HAL_OK –

hal_rtc_timestamp_it_status_t HAL_RTC_TIMESTAMP_IsEnabledIT ( void )

Check if the RTC timestamp interrupt is enabled.

Return values :

hal_rtc_timestamp_it_status_t – RTC timestamp interrupt status.

hal_status_t HAL_RTC_TIMESTAMP_GetDateTime ( hal_rtc_time_t * p_time , hal_rtc_date_t * p_date , hal_rtc_timestamp_information_t * p_info )

Retrieve the RTC timestamp time and the source of the timestamp event.

Parameters :

  • p_time – pointer to a RTC timestamp time instance.

  • p_date – pointer to a RTC timestamp date instance.

  • p_info – pointer to a hal_rtc_timestamp_information_t value. It is used to retrieve the flag of the timestamp event.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_date or p_time are NULL.

  • HAL_ERROR – when an overflow occurred

hal_status_t HAL_RTC_TIMESTAMP_PollForEvent ( uint32_t timeout_ms )

Poll for timestamp event.

Parameters :

timeout_ms – Timeout duration

Return values :

  • HAL_OK –

  • HAL_TIMEOUT – if timeout is reached

hal_status_t HAL_RTC_TIMESTAMP_GetBinaryTime ( uint32_t * p_time_subseconds , hal_rtc_timestamp_information_t * p_info )

Retrieve the RTC timestamp subsecond register value.

Parameters :

  • p_time_subseconds – pointer to an uint32_t to retrieve the value of the subseconds of the timestamp.

  • p_info – pointer to a hal_rtc_timestamp_information_t value. It is used to retrieve the flag of the timestamp event.

Return values :

  • HAL_OK –

  • HAL_ERROR – if an overflow occurred

RTC exported wake-up timer functions

group RTC_Exported_Functions_WakeUp_Timer

Exported wake-up timer functions.

The wake-up timer is a 16 bits auto-reload down-counter. The wake-up timer clock input can be:

  • The RTCCLK divided by a dedicated prescaler of 2,4,8,16 values.

  • The synchronous clock that is configured by changing the values of the RTC prescalers hal_rtc_config_t::asynch_prediv and hal_rtc_config_t::synch_prediv.

The application needs to call HAL_RTC_WAKEUP_SetConfig and configure hal_rtc_wakeup_config_t::clock to choose the input clock of the wake-up timer. When using the synchronous clock input, the wake-up timer can behave like a 17 bits auto-reload down-counter by setting the value HAL_RTC_WAKEUP_TIMER_CLOCK_SECONDS_ADD_1BIT to hal_rtc_wakeup_config_t::clock. In this case the 16 bits down-counter reaches 0 two times, the first time it reloads automatically but triggers a wake-up event. The second time it doesn’t reload automatically but also triggers a wake-up event.

By setting the parameter p_auto_clear_time to a non-zero value in function HAL_RTC_WAKEUP_SetPeriod , the wake-up timer flag is cleared by hardware when the auto-reload down counter reaches this value.

If the users want to configure the wake-up timer without using physical time units, it can be done by using HAL_RTC_WAKEUP_SetAutoReloadAndAutoClear .

Functions

hal_status_t HAL_RTC_WAKEUP_SetConfig ( const hal_rtc_wakeup_config_t * p_config_wakeup_timer )

Configure the RTC wake-up timer.

Parameters :

p_config_wakeup_timer – pointer to an RTC wake-up timer configuration instance.

Return values :

  • HAL_OK –

  • HAL_ERROR – If not in initialization mode and wake-up timer is started. If not in initialization mode and WUTWF is still unset after RTC timeout duration.

  • HAL_INVALID_PARAM – when p_config_wakeup_timer is NULL.

void HAL_RTC_WAKEUP_GetConfig ( hal_rtc_wakeup_config_t * p_config_wakeup_timer )

Retrieve the configuration of the RTC wake-up timer.

Parameters :

p_config_wakeup_timer – pointer to an RTC wake-up timer configuration instance.

hal_status_t HAL_RTC_WAKEUP_SetPeriod ( const hal_rtc_time_t * p_auto_reload_time , const hal_rtc_time_t * p_auto_clear_time )

Program the RTC wake-up timer auto-reload time and auto-reload clear flag time.

Note

hal_rtc_time_t::am_pm field is ignored because it is not used in the SetPeriod function.

Note

hal_rtc_time_t::subsec field is ignored because it is not used in the SetPeriod function.

Parameters :

  • p_auto_reload_time – pointer to an RTC time instance representing the wake-up reload period.

  • p_auto_clear_time – pointer to an RTC time instance representing the wake-up auto-clear flag time.

Return values :

  • HAL_OK –

  • HAL_ERROR – the wake-up timer is still in use. the wake-up timer frequency is smaller than 1Hz, use HAL_RTC_WAKEUP_SetAutoReloadAndAutoClear . auto-reload time is shorter than auto-reload clear flag time. the value of the auto-reload time is too big or too small for the wake-up timer counter. auto-reload time is shorter than auto-reload clear flag time the value of the auto-reload time is too big or too small for the wake-up timer counter. The wake-up write flag is still cleared after timeout.

  • HAL_INVALID_PARAM – p_period is NULL.

void HAL_RTC_WAKEUP_GetPeriod ( hal_rtc_time_t * p_auto_reload_time , hal_rtc_time_t * p_auto_clear_time )

Retrieve the RTC wake-up timer auto-reload and auto-reload clear value.

Parameters :

  • p_auto_reload_time – pointer to an RTC time instance representing the wake-up reload period.

  • p_auto_clear_time – pointer to an RTC time instance representing the wake-up auto-clear flag time.

hal_status_t HAL_RTC_WAKEUP_Start ( uint32_t interruption )

Start the wake-up timer.

Parameters :

interruption – Specifies the wake-up timer mode.

Return values :

HAL_OK –

hal_status_t HAL_RTC_WAKEUP_Stop ( void )

Stops the wake-up timer.

Return values :

HAL_OK –

hal_status_t HAL_RTC_WAKEUP_PollForEvent ( uint32_t timeout_ms )

Poll for wake-up timer event.

Parameters :

timeout_ms – Timeout duration.

Return values :

  • HAL_OK –

  • HAL_TIMEOUT – If WUTF is unset after timeout duration.

hal_status_t HAL_RTC_WAKEUP_SetAutoReloadAndAutoClear ( uint32_t wakeup_timer_auto_reload , uint32_t wakeup_timer_auto_clear )

Program the RTC wake-up timer auto-reload and auto-reload clear value in binary.

Parameters :

  • wakeup_timer_auto_reload – wake-up timer auto-reload time in binary

  • wakeup_timer_auto_clear – wake-up timer auto-reload clear value in binary

Return values :

  • HAL_OK –

  • HAL_ERROR – If WUTF is unset after timeout duration.

uint32_t HAL_RTC_WAKEUP_GetAutoReload ( void )

Retrieve the wake-up timer auto-reload value.

Return values :

uint32_t – Auto-reload value

uint32_t HAL_RTC_WAKEUP_GetAutoClear ( void )

Retrieve wake-up timer auto-reload output clear value.

Return values :

uint32_t – Auto-reload output clear value.

RTC exported IRQ functions

group RTC_Exported_Functions_IRQ

IRQ handler exported functions.

IRQ handler functions to manage the different interruptions:

  • Alarm A and alarm B

  • Timestamps

  • Wake-up timer

  • Subsecond register underflow in Binary mode.

Functions

void HAL_RTC_IRQHandler ( void )

Handle RTC interrupt request.

void HAL_RTC_ALARM_IRQHandler ( void )

Handle alarm interrupt request.

void HAL_RTC_TIMESTAMP_IRQHandler ( void )

Handle timestamp request.

Note

Inside the callback it is necessary to call HAL_RTC_TIMESTAMP_GetDateTime to clear the different timestamp flags (TSF, ITSF, TSOVF).

void HAL_RTC_WAKEUP_IRQHandler ( void )

Handle wake-up timer interrupt request.

void HAL_RTC_SubSecondsUnderflow_IRQHandler ( void )

Handle sub-seconds register underflow interrupt request.

RTC exported callback functions

group RTC_Exported_Functions_Callback

Callback exported functions.

Callback functions that user can overwrite for the different interruption:

  • Alarm A

  • Alarm B

  • Wake-up timer

  • Timestamp

  • Subsecond register underflow only in Binary mode.

When rewriting the timestamp callback function, HAL_RTC_TimestampEventCallback it’s necessary to call HAL_RTC_TIMESTAMP_GetDateTime or HAL_RTC_TIMESTAMP_GetBinaryTime to clear the timestamp flags (TSF, ITSF, TSOVF).

Functions

void HAL_RTC_AlarmAEventCallback ( void )

Alarm A callback.

void HAL_RTC_AlarmBEventCallback ( void )

Alarm B callback.

void HAL_RTC_TimestampEventCallback ( void )

Timestamp callback.

Note

When rewriting this function it’s necessary to call HAL_RTC_TIMESTAMP_GetDateTime or HAL_RTC_TIMESTAMP_GetBinaryTime to clear the different timestamp flags

void HAL_RTC_WakeUpTimerEventCallback ( void )

Wake-up timer callback.

void HAL_RTC_SubSecondsUnderflowEventCallback ( void )

SSRU callback.