Using RTC in FreeRTOS

Owned by Natalia Sofronova
Last updated: May 22, 2024
3 min read

This application note explains how to use the STM32H7 RTC in the FreeRTOS demo application.

1. Understanding RTC Interfaces

1.1. FreeRTOS RTC Implementation

The FreeRTOS BSP makes use of the STM32CubeH7 software component to provide a device driver for the STM32H7 RTC. The driver is configured (enabled / disabled) at the BSP build time, using the HAL_RTC_MODULE_ENABLED configuration option, defined in the stm32h7xx_hal_conf.h file.

1.2. FreeRTOS RTC C-Binding API

The RTC driver implements the following C-binding API:

Function

Description

Comments

HAL_StatusTypeDef HAL_RTC_Init(RTC_HandleTypeDef * hrtc)

 

Initialize the RTC according to the specified parameters in hrtc

hrtc is a RTC handle, data structures describing initialization of RTC (see below); returns one of {HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}

HAL_StatusTypeDef HAL_RTC_DeInit(RTC_HandleTypeDef * hrtc)

 

De-initialize the RTC peripheral

hrtc is a RTC handle; returns one of {HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}

HAL_StatusTypeDef HAL_RTC_GetDate(RTC_HandleTypeDef * hrtc, RTC_DateTypeDef * sDate, uint32_t Format)

 

Get RTC current date

hrtc is a RTC handle; sDate is a pointer to Date structure; Format is a value of RTC_FORMAT_BIN or RTC_FORMAT_BCD; returns one of {HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}

HAL_StatusTypeDef HAL_RTC_GetTime(RTC_HandleTypeDef * hrtc, RTC_TimeTypeDef * sTime, uint32_t Format)

 

Get RTC current time

hrtc is a RTC handle; sTime is a pointer to Time structure; Format is a value of RTC_FORMAT_BIN or RTC_FORMAT_BCD; returns one of {HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}

HAL_StatusTypeDef HAL_RTC_SetDate(RTC_HandleTypeDef * hrtc, RTC_DateTypeDef * sDate, uint32_t Format)

 

Set RTC current date

hrtc is a RTC handle, data structures describing initialization of RTC (see below); returns one of {HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}

HAL_StatusTypeDef HAL_RTC_SetTime(RTC_HandleTypeDef * hrtc, RTC_TimeTypeDef * sTime, uint32_t Format)

 

Get RTC current time

hrtc is a RTC handle; sTime is a pointer to Time structure; Format is a value of RTC_FORMAT_BIN or RTC_FORMAT_BCD; returns one of {HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}

The RTC_HandleTypeDef data structure used in the HAL_RTC_Init interface has the following definition:

typedef struct { RTC_TypeDef * Instance; /* Register base address */ RTC_InitTypeDef Init; /* RTC required parameters */ HAL_LockTypeDef Lock; /* RTC locking object */ __IO HAL_RTCStateTypeDef State; /* Time communication state */ } RTC_HandleTypeDef;

The RTC_InitTypeDef data structure used in RTC_HandleTypeDef has the following definition:

typedef struct { uint32_t HourFormat; /* Specifies the RTC Hour Format. */ uint32_t AsynchPrediv; /* Specifies the RTC Asynchronous Predivider value. */ uint32_t SynchPrediv; /* Specifies the RTC Synchronous Predivider value. */ uint32_t OutPut; /* Specifies which signal will be routed to the RTC output. */ uint32_t OutPutRemap; /* Specifies the remap for RTC output. */ uint32_t OutPutPolarity; /* Specifies the polarity of the output signal. */ uint32_t OutPutType; /* Specifies the RTC Output Pin mode. */ } RTC_InitTypeDef;

2. RTC CLI Command

The FreeRTOS application implements the following RTC related CLI command:

Command

Description

Comments

rtc_get_date

Get the RTC time and date

 

rtc_set_date YYYY:MM:DD:hh:mm

Set the RTC time and date

YYYY - year to be set; MM - month to be set; DD - date to be set; hh - hours to be set; mm - minutes to be set

3. Validating RTC Operation

Use the following step-wise procedure to validate the FreeRTOS RTC operation:

  1. Install a 3V Lithium battery CR1220 (or CR1216, CR1225, or any equivalent) in the BT1 battery holder.

  2. From the FreeRTOS Command Line Interface, set the RTC time and date to the current wall time:

    CLI> rtc_set_date 2019:05:09:12:00 CLI>

  3. Power off the board. Let it sit unpowered for at least 1 hour.

  4. Power on the target board and let it boot to the FreeRTOS CLI.

  5. Validate that the RTC time and date continue to match the current wall time: