RTC Interface

RTC Platform interface

RTC Overview

A Real-Time Clock (RTC) is a hardware module or integrated circuit designed to keep track of the current time and date, even when the main system is powered off. It provides accurate timekeeping functionality for electronic systems and embedded devices, ensuring consistent tracking of time over extended periods.

RTC BUS Interface

The RTC bus interface specifies how the RTC is connected to the system for communication and operation:

  • RTC Interface Internal: The RTC is integrated within the internal memory of the device.

  • RTC Interface I2C : The RTC is connected externally via the I2C (Inter-Integrated Circuit) protocol.

  • RTC Interface SPI : The RTC is connected externally via the SPI (Serial Peripheral Interface) protocol.

Application Interface

The below table captures the functions that are to be called from the application layer.

API Functions

Function

Description

rs_rtc_open

To open the RTC interface.

rs_rtc_set_config

To configure the RTC time and interface.

rs_rtc_start

To starts the RTC timer

rs_rtc_set_time

To updates the RTC time with the given time

rs_rtc_get_time

To reads the current time from the RTC time and returns it.

rs_rtc_get_ticks

To reads the current time from the RTC Ticks and returns it.

rs_rtc_stop

To stops the RTC timer

rs_rtc_register_completion_callback

To registers the given callback function for completion of transfer function.

rs_rtc_convert_ticks_to_date_time

To convert ticks to the date time format.

rs_rtc_convert_date_time_to_sec

To convert the date time to seconds.

rs_rtc_convert_date_time_to_milisec

To convert the date time to milli seconds.

rs_rtc_close

To close the RTC interface.

Implementation Guide

Users can directly call the API’s though most of them will be called by device drivers.

  • Open the RTC Interface and configure the RTC.

  • Register the callback.

  • Read time when needed

  • Write time when needed

  • Close the RTC unit

Error Code

  • Every API’s for the RTC returns some success or failure values. Please refer below section,

Documentation from the relevant header as follows:

RTC Specific APIs.

Defines macros and functions specific to RTC functionality

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Defines

RS_RTC_INTERFACE_INTERNAL

RTC Bus Interface Internal device memory interface type

RS_RTC_INTERFACE_I2C

RTC Connected over I2C.

RS_RTC_INTERFACE_SPI

RTC Connected over SPI.

RS_RTC_BLOCKING

Operation mode Blocking Mode operation

RS_RTC_NON_BLOCKING

Non-Blocking Mode operation.

RS_RTC_PART_MICROCHIP_PCF85263

RTC part number for Microchip PCF85263

RS_RTC_PART_ATMEL_ABCD

RTC part number for Atmel ABCD.

RS_RTC_ALARM_NONE

No alarm triggered.

RS_RTC_SECONDS_ALARAM

Alarm triggered at the second interval.

RS_RTC_MINUTES_ALARAM

Alarm triggered at the minute interval.

RS_RTC_HOURS_ALARAM

Alarm triggered at the hour interval.

RS_RTC_INTERRUPT_NONE

No interrupt triggered.

RS_RTC_SECONDS_INTERRUPT

Interrupt triggered at the second interval.

RS_RTC_MINUTES_INTERRUPT

Interrupt triggered at the minute interval.

RS_RTC_HOURS_INTERRUPT

Interrupt triggered at the hour interval.

RS_RTC_GPIO_INTERRUPT_DISABLE

GPIO interrupt disabled.

RS_RTC_GPIO_INTERRUPT_ENABLE

GPIO interrupt enabled.

Typedefs

typedef struct tag_rs_rtc_config rs_rtc_config_t

Structure for setting up RTC configuration.

typedef struct tag_rs_rtc_instance rs_rtc_instance_t

Structure for RTC instance.

typedef void (*rs_rtc_callback_completion)(rs_handle_t handle, int32_t s32_result)

Callback function format.

This callback function is called on completion of given activity

Param handle:

[in] - Handle to the RTC interface

Param s32_result:

[in] - Result of the last operation requested in non-blocking mode

Return:

None

Functions

rs_handle_t rs_rtc_open(rs_rtc_instance_t *ptr_instance, rs_rtc_config_t *ptr_config)
rs_ret_val_t rs_rtc_start(rs_handle_t handle)

Starts the RTC timer.

This function requests the RTC logic to start the time keeping

Parameters:

handle – [in] - Handle to RTC device

Returns:

0 on success or error code on failure

void rs_rtc_set_config(rs_rtc_config_t *ptr_rtc_config, uint8_t u8_interface, uint16_t u16_slave_address, rs_handle_t interface_handle, uint8_t rtc_part_number, uint8_t u8_alaram_type, uint8_t u8_alaram_value, uint8_t u8_enable_gpio_interrupt, uint8_t u8_periodic_interrupt_type)
rs_ret_val_t rs_rtc_set_time(rs_handle_t handle, uint16_t u16_year, uint8_t u8_month, uint8_t u8_date, uint8_t u8_weekday, uint8_t u8_hours, uint8_t u8_minutes, uint8_t u8_seconds)

Updates the RTC time with the given time.

This function updates the RTC time with the given value and starts counting from there

This function updates the RTC time with the given value and starts counting from there

Parameters:

  • handle – [in] - Handle to RTC device

  • u16_year – [in] - Value of the year e.g. 2022, 2023

  • u8_month – [in] - Value of the month starting from 0 e.g. 0 for Jan, 1 for Feb, 11 for Dec

  • u8_date – [in] - Value of the date starting from 1 e.g. 2022, 2023

  • u8_weekday – [in] - Value of the Weekday starting from 0 e.g. 0 for Sunday, 1 for Mon and 6 for Sat

  • u8_hours – [in] - Value of the hour between 0 and 23 (both inclusive)

  • u8_minutes – [in] - Value of the minutes between 0 and 59 (both inclusive)

  • u8_seconds – [in] - Value of the seconds between 0 and 59 (both inclusive)

  • handle – [in] - Handle to RTC device

  • ptr_time – [in] - Structure pointer to set date time

Returns:

0 on success or error code on failure

Returns:

0 on success or error code on failure

rs_ret_val_t rs_rtc_get_time(rs_handle_t handle, uint16_t *ptr_year, uint8_t *ptr_month, uint8_t *ptr_date, uint8_t *ptr_weekday, uint8_t *ptr_hours, uint8_t *ptr_minutes, uint8_t *ptr_seconds)

Returns the RTC time.

This function reads the current time from the RTC time and returns it

This function reads the current time from the RTC time and returns it

Parameters:

  • handle – [in] - Handle to RTC device

  • ptr_year – [out] - Value of the year e.g. 2022, 2023

  • ptr_month – [out] - Value of the month starting from 0 e.g. 0 for Jan, 1 for Feb, 11 for Dec

  • ptr_date – [out] - Value of the date starting from 1 e.g. 2022, 2023

  • ptr_weekday – [out] - Value of the Weekday starting from 0 e.g. 0 for Sunday, 1 for Mon and 6 for Sat

  • ptr_hours – [out] - Value of the hour between 0 and 23 (both inclusive)

  • ptr_minutes – [out] - Value of the minutes between 0 and 59 (both inclusive)

  • ptr_seconds – [out] - Value of the seconds between 0 and 59 (both inclusive)

  • handle – [in] - Handle to RTC device

  • ptr_date_time – [out] - Structure pointer to date time

Returns:

0 on success or error code on failure

Returns:

0 on success or error code on failure

rs_ret_val_t rs_rtc_set_datetime(rs_handle_t handle, RS_DATE_TIME *ptr_time)
rs_ret_val_t rs_rtc_get_datetime(rs_handle_t handle, RS_DATE_TIME *ptr_date_time)
rs_ret_val_t rs_rtc_stop(rs_handle_t handle)

Stops the RTC timer.

This function requests the RTC logic to stop the time keeping

Parameters:

handle – [in] - Handle to RTC device

Returns:

0 on success or error code on failure

rs_ret_val_t rs_rtc_register_completion_callback(rs_handle_t handle, rs_rtc_callback_completion ptr_func)

Registers the given callback function for completion of RTC operation.

This function registers the given callback function for completion of transfer operation

Parameters:

  • handle – [in] - Handle to the RTC device

  • ptr_func – [in] - Callback function to call to

Returns:

0 on success or error code on failure

rs_ret_val_t rs_rtc_close(rs_handle_t handle)

uninitialized the RTC

This function un-initializes the RTC and releases the underlying resources

Parameters:

handle – [in] - Handle to RTC device

Returns:

0 on success or error code on failure

struct tag_rs_rtc_config
#include <rs_rtc.h>

Structure for setting up RTC configuration.

Public Members

uint8_t u8_interface_type

Type of interface to the RTC device.

uint8_t u8_alaram_type

Type of alarm to be configured.

uint8_t u8_alaram_value

Value for the alarm.

uint8_t u8_periodic_interrupt_type

Type of periodic interrupt to be triggered.

uint8_t u8_rtc_enable_gpio_interrupt

Enable or disable GPIO interrupt for RTC events.

rs_gpio_pin_config_t gpio_int_config

GPIO pin configuration for interrupt handling.

struct tag_rs_rtc_instance
#include <rs_rtc.h>

Structure for RTC instance.

Public Members

rs_rtc_config_t *ptr_rtc_config

Pointer to the RTC configuration structure.

RS_DATE_TIME date_time

Current date and time from the RTC.