Rockchip (EASY EAI) RV1126B RTC Usage

RTC

1. Introduction to RTC

RTC is the abbreviation of Real-Time Clock. A real-time clock chip provides time read/write interfaces externally through pins and is usually powered by an independent battery to ensure the chip circuit operates normally and time runs correctly even when the external system is powered off.

Different clock chips have different internal mechanisms, but in the Linux system, the driver encapsulates the operation details of different clock chips and provides a unified time operation interface for applications.

1.1 RTC Resources on the Development Board

The EASY EAI Nano-TB does not come with an RTC circuit by default. To enable RTC functionality on the baseboard, you can expand it using our RTC module.

Specific operations to expand RTC: [First], power off the baseboard, then insert the module into the 40PIN interface of the baseboard with the front facing up, as shown in the figure below.

After inserting it firmly, perform the [power-on] operation.

Using the ls command, you can check whether the RTC chip has been recognized by the system.

ls /dev/rtc*

After confirming the driver is loaded successfully, you can access the driver to read all RTC chip information with the following command:

cat /proc/driver/rtc

1.2 Reading and Writing RTC Time

Two clocks are involved here: the RTC chip clock and the system clock. Manually managing the RTC clock essentially means synchronizing the two clocks (either syncing the system clock to the RTC chip clock or vice versa).

System Clock

The system clock is essentially a 64-bit integer representing the time difference (in seconds) from the Epoch Time, known as a timestamp. It is maintained by the CPU's main chip timer and will be lost when the CPU is powered off. The operating system command for the system clock is date:

date    #查询系统时间
date -s "2023-09-20 11:18:00"    #修改系统时间

Note:

Epoch Time refers to a specific time: 00:00:00 on January 1, 1970 (UTC). If N seconds have passed since this time, the time value in the Linux system is N.

RTC Chip Clock

The RTC chip clock is the time maintained internally by the RTC chip, powered by a battery when the system is off. Therefore, the RTC time continues to run normally even when the system power is off, and its role is to retain time information when Linux is not running.

The chip clock is synchronized to the system clock.

sudo hwclock --hctosys

Synchronize the system clock to the chip clock (or use sudo hwclock -w).

sudo hwclock --systohc

If you only want to query the RTC chip clock without synchronizing it to the system clock, you can use the following command.

sudo hwclock -r

1.3 Reading and Writing System Clock

This document focuses on the RTC clock. For detailed introductions and operations of the system clock, please refer to《EASY-EAI-Toolkit / General Components / System Operations - Time Parameters.》

1.4 Time Zones and Time Synchronization Services

• Time Zones: Both the RTC clock and system clock use UTC time. The time used in different regions also needs to account for time zone effects.
• Time Synchronization Services: In addition to manual operations, the RTC clock is also affected by time synchronization services.

For time zone settings and time synchronization services on the EASY-EAI-Nano-TB, refer to《Application Notes / Automatic Time Synchronization and Time Zone Settings》For more detailed interaction mechanisms, refer to《Introduction to System Time Management.》。

2. Quick Start

2.1 Development Environment Preparation

If you are reading this document for the first time, please refer to《Getting Started Guide / Development Environment Preparation / Easy-Eai Compilation Environment Preparation and Update》，and follow the relevant operations to deploy the compilation environment.

Execute the run script in the Ubuntu system on the PC to enter the EASY-EAI compilation environment, as follows:

cd ~/develop_environment
./run.sh

2.2 Source Code Download and Example Compilation

First, in the background terminal of the virtual machine, execute the following commands to create a directory for managing peripheral standalone source code:

cd /opt
mkdir -p EASY-EAI-Nano-TB/demo

Download the relevant standalone program from Baidu Netdisk:

• Link: https://pan.baidu.com/s/1Br608Hiff2Xs65PzWO_qWQ?pwd=1234
• Extraction code: 1234

For example, save the standalone program to: This PC\D:\BaiduNetdisk (no fixed path; users can choose freely), as shown in the figure below.

Copy the downloaded standalone program to the file system of the virtual machine (process shown in the figure below).

Finally, enter the corresponding example directory and execute the compilation command:

cd EASY-EAI-Nano-TB/demo/12_RTC
./build.sh

Note:

* Since the dependent libraries are deployed on the board, the /mnt mount must be maintained during the cross-compilation process.

After successful compilation, an executable program named test-rtc will be generated in the Release directory and will be automatically deployed to the /userdata/ directory of the development board.

2.3 Running the Example

Access the background of the board via serial port debuggingor SSH debugging，and navigate to the deployment directory of the example:

cd /userdata

Execute the example command as follows:

sudo ./test-rtc

The execution effect is shown below.

3. C Language Usage Example

The C language usage example for RTC is located at 12_RTC/test-rtc/main.c for users' coding reference. The following code demonstrates the read/write operation process of the RTC clock:

int main(int argc, char const *argv[])
{
    const char *strDateTime = "2023-09-21 15:22:37";
    // 将字符串转换为tm结构体类型的时间信息
    struct tm tm = {0};
    strptime(strDateTime, "%Y-%m-%d %H:%M:%S", &tm);
    // 打开RTC设备
    int rtc_fd = open("/dev/rtc0", O_RDWR);
    if (rtc_fd < 0) {
        perror("open RTC device /dev/rtc0 faild.");
        close(rtc_fd);
        return -1;
    }
    printf("---设置参数前日期时间---\n");
    system("date");
    
    /***  1.关闭网络校时服务 ***/
    system("systemctl stop ntp.service");
    
    /***  2.将预设好的时间写入【RTC时钟】 ***/
    struct rtc_time rtc_tm;
    rtc_tm.tm_sec  = tm.tm_sec;
    rtc_tm.tm_min  = tm.tm_min;
    rtc_tm.tm_hour = tm.tm_hour;
    rtc_tm.tm_mday = tm.tm_mday;
    rtc_tm.tm_mon  = tm.tm_mon;
    rtc_tm.tm_year = tm.tm_year;
    if (ioctl(rtc_fd, RTC_SET_TIME, &rtc_tm) < 0) {
        perror("set data time to rtc0");
        perror("RTC时间设置失败");
        close(rtc_fd);
        return -1;
    }
    
    /***  3.将【RTC时钟】同步回【系统时钟】 ***/
    // 读出刚才写入的RTC时钟参数
    if (ioctl(rtc_fd, RTC_RD_TIME, &rtc_tm) < 0) {
        perror("RTC时间读取失败");
        close(rtc_fd);
        return -1;
    }
    close(rtc_fd);
    tm.tm_sec  = rtc_tm.tm_sec;
    tm.tm_min  = rtc_tm.tm_min;
    tm.tm_hour = rtc_tm.tm_hour;
    tm.tm_mday = rtc_tm.tm_mday;
    tm.tm_mon  = rtc_tm.tm_mon;
    tm.tm_year = rtc_tm.tm_year;
    struct timeval tv;
    tv.tv_sec = mktime(&tm);
    tv.tv_usec = 0;
    // 同步时间到系统时钟
    if(0 != settimeofday(&tv, (struct timezone *)0)){
        perror("系统时间设置失败");
    }
    printf("---设置参数后日期时间---\n");
    system("date");
    
    return 0;
}