示例17:DS1302 RTC时钟

实验概述

DS1302 是一款低功耗实时时钟芯片，通过纽扣电池可在断电后持续计时。FastBee 已内置 DS1302 专用外设类型（type: 50），支持时间读取/设置、涓流充电和31字节用户RAM。

硬件接线

开发板标识	GPIO引脚	连接设备
CLK	GPIO14	DS1302 时钟线
DAT	GPIO27	DS1302 数据线
RST	GPIO26	DS1302 复位/使能

DS1302 使用三线接口（CE/IO/SCLK），需要 3 个 GPIO 引脚。

Web 配置与 RTC 面板

1. 在“功能配置”确认 ds1302 已编译，按页面要求启用并重启；准入通过不代表硬件已连通。
2. 新建 DS1302 RTC（type 50） 外设，按 CE/IO/SCLK 顺序填入已核对的 GPIO；不要把三个普通 GPIO 外设当作 RTC 驱动配置。
3. 在外设操作面板读取时间；需要写入、启动或暂停时使用现有表单，并保留开发者模式及暂停确认。写入后重新读取，而不是只看成功提示。
4. RTC 读写和网络系统时间同步是不同链路。当前源码已有35“RTC 计时启停”、36“RTC 日历读取”和37“复制系统本地时间”；动作36以外设ID绑定平台文本属性，动作37须明确选择 system-local。没有专用“显示时间”动作，也不会自动把RTC日历变成显示模板或传感器数值字段。

2026-10-04源码校对：下方标为后续候选的段落保留历史增量；当前接口以本节和“日历读取与显式校时规则”为准。统一软件候选待门禁终态；RTC实物读取、写入、断电保持与走时精度仍为 NOT_RUN。

JSON 配置示例

以下仅说明持久化结构；示例默认停用，不能不核对板卡资源就启用。新用户优先使用 Web 表单。引脚顺序是 CE、IO、SCLK，示例不启用涓流充电。

{
  "peripherals": [
    {
      "id": "rtc_01",
      "name": "DS1302 RTC",
      "type": 50,
      "enabled": false,
      "pins": [26, 27, 14],
      "params": { "use24Hour": true, "trickleCharge": 0, "bootSeed": false }
    }
  ]
}

启动采用 RTC 时间（开发候选）

新候选提供默认关闭的“启动时用 RTC 初始化无效的系统时间”。先声明 RTC 日历使用的固定 UTC 偏移，分钟整数 -840～840；如 UTC+8 填 480，RTC 存 UTC 填 0。缺失偏移不是 UTC 0，开启时会拒绝保存。保存只影响下次启动，不立刻设时，也不自动启动/设置 RTC 或开启充电。

在外设初始化后、网络/后台启动前仅尝试一次。RTC 必须可用、运行中且日历有效，启用启动采用的 RTC 必须唯一；未知但已有效的系统时间同样保留。读取/配置/来源竞态或设时失败均停止本次启动尝试，不自动反复设时。普通电池保护、真实引脚和旧充电设置仍须独立核对。

成功显示“RTC启动时间（未校准）”，source=rtc、quality=rtc_unverified、synced=false。来源记录年龄只表示距本次启动采用的时间，不是校准年龄、断电保持时长或走时精度。RTC启动失败会显示原因；之后网络同步不会擦除本次启动结果。没有可信网络同步时，HTTPS仍走既有SNTP时间引导，动作37不会把RTC来源又写回RTC。

启用后，有效的RTC日历会影响已启用的每日定时规则。先核对日历、固定偏移和规则现场条件；不应在不清楚动作结果时开启。固定偏移不随系统时区/夏令时更新；以后配置 ntp_synced → 动作37 system-local 回写时，系统本地时区须与RTC约定一致，默认应保持该规则禁用。Web手动校时不发该事件；RTC启动采用也不发它。

本段软件路径已取得局部Host回归证据；完整固件候选、实际重启采用、断电保持、误差和每日规则物理效果仍待验证，现场维持NOT_RUN。

时间数据校验（后续候选）

2026-10-01 的 G04 增量补齐 2000～2099 年完整日期、闰日、星期与时分秒范围，以及非法 BCD 检查；无效读取沿用零结构哨兵，由现有 API 拒绝输出正常时间。无效对象格式化为空、时间戳返回 0；有效时间戳仍以 1970 为 epoch。修正默认格式把月份重复显示成分钟的问题，并兼容显式 nn 分钟格式。

12 小时制读取正确处理午夜和正午；12/24 小时制转换保持原有时刻，不再只翻转模式位。直接驱动写入无效日期时不操作 GPIO。隔离区完整生产驱动的 7 项 GPIO-mock 回归已通过，合入后的证据见项目实施记录；这是本地代码证据，不是 RTC 实物、断电保持、校准精度或长稳验收。本增量不自动开启充电、不访问设备、不设置现场时间。

RTC 计时启停规则（后续候选）

在“外设执行”选择“RTC 计时启停”、已配置的 DS1302 外设，再明确选择“启动计时（不校时）”或“暂停计时”；不需要手写 JSON。动作编号 35，命令仅 start/stop，不接受平台值替换。先核对已有有效日期和触发条件，首次保存建议保持规则禁用；启用/执行由现场人员决定。

暂停后 RTC 时间停止推进，不是释放 GPIO 或关闭驱动。该动作不改设备系统时间、充电模式或电池配置，不产生数值历史/属性，也不能作为面板控制动作。未启用/未初始化/功能受限/引脚不一致/忙锁会拒绝；无效时钟数据不写入，写后计时状态读回失败也会报告失败。Web 读写与规则使用同一访问锁。

新规则的目标下拉框只显示 DS1302，可先配置未启用目标；必须恢复实际实例后才能执行。触发方式切换保留命令，错误目标不改成 Modbus 操作。执行轨迹、API 状态和物理时钟推进分别确认；当前本地测试不是实物、断电保持或走时精度验收。

回退注意：旧固件不认识动作 35，不能直接导入包含该动作的新配置；仅禁用规则也不能绕过旧版本结构校验。应保全并使用添加动作 35 之前的配置恢复，具体候选证据见项目实施记录。后续已增加读取/复制动作和日历文本上报，见下一节；自动显示字段链路与实物验收不能由此推定完成。

日历读取与显式校时规则（2026-10-01 后续候选）

更新上节历史边界：新候选增加动作 36“RTC 日历读取”和 37“复制系统本地时间”。旧动作 35 保留，读取/复制都须显式选择 DS1302 目标，不接受接收值覆盖。

• 读取：同一次突发取得日历、暂停位和小时制。有效且运行时返回 YYYY-MM-DD HH:MM:SS，标记 rtc_calendar_unzoned；无时区/UTC 推断，不证明走时精度。无效、暂停或访问失败时返回失败，不沿用旧值，也不作为数值历史/面板控制。
• 复制：必须选择 system-local；不默认校时，不输入任意 JSON 或日期。复制系统当前本地日历，不请求 NTP、不设置系统时间、不改变充电；写前拒绝无效旧日历，保留原暂停状态并写入24小时制，写后检查时间、星期、小时制和暂停位。运行时只接受 0～1 秒向前差值，暂停时精确匹配。
• 写后失败：DS1302_WRITE_VERIFY_FAILED 可能表示写入已经发生；不宣称回滚，不自动重试。成功仅说明回读符合输入；来源未经认证时为 rtc_copied_system_local_unverified，认证HTTPS传输时为 rtc_copied_system_local_tls，两者均不证明RTC或服务器的走时精度。
• 首次使用：建议保留禁用规则，先核对系统本地时间及现场条件。实际读写、断电保持和走时精度分别验收；本地模拟测试和编译不能代替现场。

回退到不认识 35/36/37 的旧固件必须使用新增动作前的保全配置；只禁用规则也不能绕过旧版配置结构校验。读取 local-r4 51 项、复制 local-r2 44 项及离线读写表单 24 项通过；完整 r4 已出现 Native 旧断言失败，独立构建继续，新候选不能宣称全套通过或已部署。以项目实施记录为准。

注意事项

2026-10-03 22:08验证更新：局部Host已通过，完整候选/实物待验。 r16 Host中的系统时间/RTC149项局部通过，修正时间状态夹具后主仓6/6通过；r16 Host整组仍失败，没有设置设备或RTC时间，也未证明RTC走时/电池保持。

2026-10-03 20:33 开发增量：系统单调时钟不可用时不能建立新同步来源；写时前拒绝不执行设时，写时后发现不可用或回退则使来源失效并返回失败，此时墙钟可能已改变。恢复正常采样不能恢复旧来源，须新的有效同步记录。启动时间0仍合法；本边界已纳入33项来源质量Host回归，SDK实际调度及现场效果继续待验。

2026-10-03 开发候选，局部Host已验证：复制系统本地时间另要求有效且未失鲜的来源记录，写前后复核同一来源和1秒窗口。已观察到非法墙钟、超过5秒偏移或单调时间回退会使旧记录持续失效；即使时间返回旧轨迹，也须新接受的同步才能重新准入。写后复核失败可能已写入，不回滚或自动重试。此约束不能证明RTC或服务器精度，不会主动校时；完整候选与现场复制/电池保持仍待验收。

1. 电池：先核对模块的电池类型与充电电路；不可充电电池不得启用涓流充电，示例保持充电关闭。
2. NTP 优先：联网环境建议使用 NTP，DS1302 适合离线场景
3. 驱动支持：源码内置 DS1302 驱动；当前固件是否编译由 FASTBEE_ENABLE_DS1302 和所用构建配置决定，先核对功能页与设备版本。
4. 精度：本页不提供未经实物测量的 ppm 或月误差保证；校准和长时间误差验收另行记录。
5. 通信协议：DS1302 使用 3 线 SPI（非标准 SPI），时序需软件模拟