Contributed by 爱笑, organized by Ai-Thinker

[Ai-WB2 Intermediate] RTC Real-Time Clock

RTC (real-time clock) is the real-time clock device of an operating system, providing precise real-time time and scheduled alarm functions. When the device is powered off, the RTC continues to record the operating system time via an external battery; after the device is powered on, the RTC provides the real-time clock to the operating system, ensuring the continuity of system time across power loss. However, the BL602 chip has no built-in RTC module and provides no external battery supply, but the software RTC it provides can be used while the device is powered.

This article details how to use the RTC module in the bl_iot_sdk of Ai-WB2.

1. RTC Introduction

The BL602 chip has no built-in RTC module, but b1_iot_sdk provides a software RTC. The RTC supports two timing modes: DEC mode and BCDQ mode.

The HOSAL-layer APIs of the RTC module are defined in components/platform/hosal/include/hosal_rtc.h. Common APIs are listed below:

· int hosal_rtc_init(hosal_rtc_dev_t *rtc): initializes the RTC device. Parameter description:

· rtc: the RTC device instance. It is defined as follows:

Click to expand full code

typedef struct {
uint8_t       port;   /**< rtc port */
hosal_rtc_config_t  config; /**< rtc config */
void         *priv;   /**< priv data */
} hosal_rtc_dev_t;

where hosal_rtc_config_t is defined as follows:

Click to expand full code

#define HOSAL_RTC_FORMAT_DEC 1 /**< RTC DEC format */
#define HOSAL_RTC_FORMAT_BCD 2 /**< RTC BCD format */
typedef struct {
uint8_t format; /**< time formart DEC or BCD */
} hosal_rtc_config_t;

Click to expand full code

**·** 返回值：当调用成功时，返回0；否则返回非零值。
**·** int hosal_rtc_set_time(hosal_rtc_dev_t *rtc, const hosal_rtc_time_t *time):设置RTC日期时间。参数说明如下：
**·** rtc：RTC设备
**·** time：需要设置的时间。其定义如下：

Click to expand full c```c

/**

• @brief RTC time struct */ typedef struct { uint8_t sec;     /< DEC format:value range from 0 to 59, BCD format:value range from 0x00 to 0x59 */ uint8_t min;     /< DEC format:value range from 0 to 59, BCD format:value range from 0x00 to 0x59 */ uint8_t hr;      /< DEC format:value range from 0 to 23, BCD format:value range from 0x00 to 0x23 */ uint8_t date;    /< DEC format:value range from 1 to 31, BCD format:value range from 0x01 to 0x31 */ uint8_t month;   /< DEC format:value range from 1 to 12, BCD format:value range from 0x01 to 0x12 */ uint16_t year;   /< DEC format:value range from 0 to 9999, BCD format:value range from 0x0000 to 0x9999 */ } hosal_rtc_time_t;

/**
* @brief RTC time struct
*/
typedef struct {
uint8_t sec;     /**< DEC format:value range from 0 to 59, BCD format:value range from 0x00 to 0x59 */
uint8_t min;     /**< DEC format:value range from 0 to 59, BCD format:value range from 0x00 to 0x59 */
uint8_t hr;      /**< DEC format:value range from 0 to 23, BCD format:value range from 0x00 to 0x23 */
uint8_t date;    /**< DEC format:value range from 1 to 31, BCD format:value range from 0x01 to 0x31 */
uint8_t month;   /**< DEC format:value range from 1 to 12, BCD format:value range from 0x01 to 0x12 */
uint16_t year;   /**< DEC format:value range from 0 to 9999, BCD format:value range from 0x0000 to 0x9999 */
} hosal_rtc_time_t;

Click to expand full code

**·** 返回值：当调用成功时，返回0；否则返回非零值。
**·** int hosal_rtc_get_time(hosal_rtc_dev_t *rtc, hosal_rtc_time_t *time)：查询当前时间。参数说明如下：
**·** rtc：RTC设备
**·** time：需要设置的时间
**·** 返回值：当调用成功时，返回0；否则返回非零值。
**·** int hosal_rtc_set_count(hosal_rtc_dev_t *rtc,uint64_t *time_stamp)：设置RTC新的计数值。参数说明如下：
**·** rtc：RTC设备
**·** time stamp：需要设置的时间
**·** 返回值：当调用成功时，返回0；否则返回非零值。
**·** int hosal_rtc_get_count(hosal_rtc_dev_t *rtc,uint64_t*time_stamp)：获取当前RTC的时间计数值。参数说明如下：
**·** rtc：RTC设备
**·** time stamp：返回当前的时间计数值
**·** 返回值：当调用成功时，返回0；否则返回非零值。
**·** int hosal_rtc_finalize(hosal_rtc_dev_t *rtc)：销毁当前RTC设备实例，释放相关资源。参数说明如下：
**·** rtc：RTC设备
**·** 返回值：当调用成功时，返回0；否则返回非零值。
**二：RTC使用实例**

Click to expand full c```c

#include <stdio.h> #include <string.h> #include <FreeRTOS.h> #include <task.h> #include <stdio.h> #include <stdbool.h> #include <hosal_rtc.h> #include <blog.h> #define TAG "rtc_demo" static hosal_rtc_dev_t rtc; bool rtc_demo_init(void) { int ret1 = -1; /* init rtc DEC format*/ hosal_rtc_dev_t rtc; rtc.port = 0; rtc.config.format = HOSAL_RTC_FORMAT_DEC; hosal_rtc_init(&rtc); /* set rtc time / hosal_rtc_time_t time_buf; time_buf.sec = 10; time_buf.min = 56; time_buf.hr = 10; time_buf.date = 26; time_buf.month = 4; time_buf.year = 23; ret1 = hosal_rtc_set_time(&rtc, &time_buf); if (ret1 == 0) { printf("set time sec     = %d\r\n", time_buf.sec); printf("set time min     = %d\r\n", time_buf.min); printf("set time hr      = %d\r\n", time_buf.hr); printf("set time date    = %d\r\n", time_buf.date); printf("set time month   = %d\r\n", time_buf.month); printf("set time year    = %d\r\n", time_buf.year + 2000); } return (ret1 == 0); } void rtc_task(void params) { printf("rtc task started\r\n"); bool ret = rtc_demo_init(); hosal_rtc_time_t time_buf; if (!ret) { printf("rtc init failed\r\n"); while (true) { vTaskDelay(1); } } printf("rtc task started\r\n"); while (true) { memset(&time_buf, 0, sizeof(hosal_rtc_time_t)); ret = hosal_rtc_get_time(&rtc, &time_buf); if(ret == 0){ printf("set time sec     = %d\r\n", time_buf.sec); printf("set time min     = %d\r\n", time_buf.min); printf("set time hr      = %d\r\n", time_buf.hr); printf("set time date    = %d\r\n", time_buf.date); printf("set time month   = %d\r\n", time_buf.month); printf("set time year    = %d\r\n", time_buf.year + 2000); } vTaskDelay(1000 / portTICK_PERIOD_MS); } } void main(void) { printf("rtc demo inited\r\n"); xTaskCreate(rtc_task, "rtc_task", 1024, NULL, 15, NULL); }

#include <stdio.h>
#include <string.h>
#include <FreeRTOS.h>
#include <task.h>
#include <stdio.h>
#include <stdbool.h>
#include <hosal_rtc.h>
#include <blog.h>
#define TAG "rtc_demo"
static hosal_rtc_dev_t rtc;
bool rtc_demo_init(void) {
int ret1 = -1;
/* init rtc DEC format*/
hosal_rtc_dev_t rtc;
rtc.port = 0;
rtc.config.format = HOSAL_RTC_FORMAT_DEC;
hosal_rtc_init(&rtc);
/* set rtc time */
hosal_rtc_time_t time_buf;
time_buf.sec = 10;
time_buf.min = 56;
time_buf.hr = 10;
time_buf.date = 26;
time_buf.month = 4;
time_buf.year = 23;
ret1 = hosal_rtc_set_time(&rtc, &time_buf);
if (ret1 == 0) {
printf("set time sec     = %d\r\n", time_buf.sec);
printf("set time min     = %d\r\n", time_buf.min);
printf("set time hr      = %d\r\n", time_buf.hr);
printf("set time date    = %d\r\n", time_buf.date);
printf("set time month   = %d\r\n", time_buf.month);
printf("set time year    = %d\r\n", time_buf.year + 2000);
}
return (ret1 == 0);
}
void rtc_task(void* params) {
printf("rtc task started\r\n");
bool ret = rtc_demo_init();
hosal_rtc_time_t time_buf;
if (!ret) {
printf("rtc init failed\r\n");
while (true) {
vTaskDelay(1);
}
}
printf("rtc task started\r\n");
while (true) {
memset(&time_buf, 0, sizeof(hosal_rtc_time_t));
ret = hosal_rtc_get_time(&rtc, &time_buf);
if(ret == 0){
printf("set time sec     = %d\r\n", time_buf.sec);
printf("set time min     = %d\r\n", time_buf.min);
printf("set time hr      = %d\r\n", time_buf.hr);
printf("set time date    = %d\r\n", time_buf.date);
printf("set time month   = %d\r\n", time_buf.month);
printf("set time year    = %d\r\n", time_buf.year + 2000);
}
vTaskDelay(1000 / portTICK_PERIOD_MS);
}
}
void main(void) {
printf("rtc demo inited\r\n");
xTaskCreate(rtc_task, "rtc_task", 1024, NULL, 15, NULL);
}