跳转至
项目
版本
全文检索

rtc开发指南

概述

RTC（Real Time Clock）实时时钟模块基于外部32.768kHz晶振或内部32kHz时钟为系统提供定时器功能，主要实现ms级定时器功能。

定时器系统架构

**定时器系统架构**

快速跑通 RTC Demo

功能说明

RTC 定时回调示例 创建 RTC_0 定时器，启动 100 ms 单次回调，等待回调后停止并删除句柄。该流程不依赖外接硬件。

Demo 代码归档路径

samples/native_samples/rtc/
├── CMakeLists.txt    # 独立组件构建配置
├── README.md         # 项目级运行说明
├── rtc_demo.c        # RTC 创建、回调、等待、释放和 AT 指令
└── rtc_demo.h        # 对外运行接口和 AT 注册函数声明

编译与烧录

完成一站式 CLI 环境配置后执行：

fbb set-target pack_diting_community
fbb build

构建成功后，使用一站式 CLI 烧写固件并打开 UART2 串口监视器。以下为 Windows USB DFU 示例；将 COM3 替换为实际日志串口，其他平台和串口烧写参数参见一站式 CLI 开发环境使用指南。

fbb flash -f "$env:FBB_SDK_DIR\output\3322\fwpkg\diting-community.fwpkg" --chip 3322 -d --timeout 180
fbb monitor --port COM3 --baud 750000

烧录生成的 diting-community.fwpkg，重新上电后以 750000 波特率打开 UART2 串口。

使用方式

AT+RTCTEST

需要一次性检查多类板载驱动时，也可以执行 AT+DRIVERSELFTEST。

预期结果

[DRV][RTC] PASS
OK

文件结构与代码走读

文件职责

文件 职责 关键内容
rtc_demo.c 创建 RTC、启动单次定时、等待回调并释放句柄 diting_rtc_demo_run()、rtc_demo_callback()
rtc_demo.h 公开单项运行和 AT 注册接口 diting_rtc_demo_run()、at_diting_rtc_example_cmd_register()
CMakeLists.txt 定义独立组件和注册宏 diting_rtc_sample、AT_DITING_EXAMPLE_RTC_TEST
README.md 说明单项运行和预期结果 AT+RTCTEST

核心流程

回调函数只设置完成标志，耗时操作留在任务上下文处理：

static void rtc_demo_callback(uintptr_t data)
{
    (void)data;
    g_rtc_expired = true;
}

运行函数创建句柄并启动 100 ms 单次回调：

rtc_handle_t rtc = NULL;
errcode_t ret = uapi_rtc_create(RTC_0, &rtc);
g_rtc_expired = false;
ret = uapi_rtc_start(rtc, RTC_DEMO_PERIOD_MS, rtc_demo_callback, 0);

等待过程中每 1 ms 检查一次标志，最长等待 1000 ms。无论启动或等待是否成功，均停止定时器并删除句柄：

(void)uapi_rtc_stop(rtc);
if (uapi_rtc_delete(rtc) != ERRCODE_SUCC) {
    passed = false;
}

该释放逻辑保证 AT+RTCTEST 可以重复执行，也不会影响随后执行的聚合自测。

基于 RTC Demo 开发自己的应用

  1. 复制 samples/native_samples/rtc 并修改组件名和构建开关，保留 diting_rtc_demo_run() 这类可直接调用的运行函数。
  2. 从应用任务、系统服务或 app_run 启动入口调用运行函数。
  3. 根据业务修改 RTC_DEMO_PERIOD_MS；需要周期任务时，应在回调完成后明确决定是否重新启动定时器。
  4. 回调中只设置状态或发送消息，避免执行阻塞操作。
  5. 在上层 CMake 和目标配置中增加新组件入口；直接连续调用运行函数两次，确认停止和删除路径完整。

如需串口回归，再增加 AT 命令名、命令 ID 和 AT 适配层注册；AT 入口不参与 RTC 业务生命周期。

功能描述

RTC模块提供的接口：

接口名称 功能简述 API文档
uapi_rtc_adapter 适配指定底层RTC定时器，注册中断 rtc.md
uapi_rtc_init 初始化RTC定时器模块 rtc.md
uapi_rtc_create 创建RTC定时器，获取句柄 rtc.md
uapi_rtc_start 以毫秒为单位启动RTC定时器 rtc.md
uapi_rtc_stop 停止RTC定时器 rtc.md
uapi_rtc_delete 删除已创建的RTC定时器 rtc.md
uapi_rtc_deinit 去初始化RTC定时器模块 rtc.md

开发指引

操作流程

操作流程

适配定时器配置

errcode_t ret;
ret = uapi_rtc_adapter(rtc_index, rtc_irqn, irq_priority);
if (ret != ERRCODE_SUCC) {
    return ret;
}

参数说明：

  • rtc_index：定时器索引
  • rtc_irqn：定时器中断号
  • irq_priority：中断优先级

初始化RTC

errcode_t ret;
ret = uapi_rtc_init();
if (ret != ERRCODE_SUCC) {
    return ret;
}

创建定时器

rtc_handle_t timer_handle = NULL;
errcode_t ret;
ret = uapi_rtc_create(RTC_0, &timer_handle);
if (ret != ERRCODE_SUCC) {
    return ret;
}

返回值说明：

  • timer_handle：定时器句柄，作为后续操作的唯一标识

启动定时器

uint32_t timeout_ms = 1000;  // 超时时间1秒
void *callback_param = NULL;

errcode_t ret;
ret = uapi_rtc_start(timer_handle, timeout_ms, rtc_callback, callback_param);
if (ret != ERRCODE_SUCC) {
    return ret;
}

参数说明：

  • timer_handle：定时器句柄
  • timeout_ms：超时时间（单位ms）
  • rtc_callback：超时回调函数
  • callback_param：回调函数入参

停止定时器

errcode_t ret;
ret = uapi_rtc_stop(timer_handle);
if (ret != ERRCODE_SUCC) {
    return ret;
}

删除定时器

errcode_t ret;
ret = uapi_rtc_delete(timer_handle);
if (ret != ERRCODE_SUCC) {
    return ret;
}

去初始化RTC

errcode_t ret;
ret = uapi_rtc_deinit();
if (ret != ERRCODE_SUCC) {
    return ret;
}

注意事项

  1. 超时时间单位为ms，不同于其他定时器的us单位

  2. 软件定时器数量限制：默认最多可同时创建16个RTC软件定时器

  3. 低功耗唤醒：RTC定时器可以在低功耗睡眠后唤醒使用

  4. 资源释放：确定不需要使用当前定时器后，需要调用uapi_rtc_delete接口释放该定时器资源

  5. 禁止在回调函数中调用的接口：

    • uapi_rtc_stop
    • uapi_rtc_delete
    • 以及其他可能阻塞或删除定时器的接口

  6. 定时器精度：RTC基于32.768kHz时钟，定时精度受时钟源精度影响

**定时器精度**：RTC基于32.768kHz时钟，定时精度受时钟源精度影响