Initial import

2026-09-01 17:31:15 +08:00
commit 3ab37b7845
958 changed files with 231015 additions and 0 deletions
@@ -0,0 +1,63 @@
+/******************************************************************************
+ * @file    usr_rtc.h
+ * @brief   板级 RTC：硬件对时 + 客户读本地日历
+ * @author  cyWu <1917507415@qq.com>
+ * @date    2026.08.19
+ * @version V1.1.0
+ * @history
+ * - V1.0.0, 2026.08.19, cyWu, 首次发布，实现板级硬件 RTC 对时与本地日历读取
+ * - V1.1.0, 2026.08.19, cyWu, 精简接口；usr_rtc_get_time 返回本地日历
+ ******************************************************************************/
+
+#ifndef __USR_RTC_H__
+#define __USR_RTC_H__
+
+#include <stdint.h>
+#include "system/sys_time.h"
+
+/*============================================================================*/
+/* 宏定义                                                                     */
+/*============================================================================*/
+
+#define USR_RTC_YEAR_MIN          (2026u)     /**< 合法年份下限 */
+#define USR_RTC_YEAR_MAX          (2098u)     /**< 合法年份上限 */
+#define USR_RTC_TZ_ABS_MAX_S      (57600)     /**< 时区偏移绝对值上限（±16h） */
+#define USR_RTC_SYNC_COMPENSATE_S (1u)        /**< 网关对时延迟补偿（秒） */
+
+/*============================================================================*/
+/* 错误码（init / set_from_unix）                                             */
+/*============================================================================*/
+
+typedef enum {
+    USR_RTC_OK = 0,
+    USR_RTC_ERR_PARAM,
+    USR_RTC_ERR_NOT_INIT,
+    USR_RTC_ERR_INVALID,   /**< 年份非法，等待 App 对时 */
+} UsrRtc_Ret_t;
+
+/*============================================================================*/
+/* 外部接口                                                                   */
+/*============================================================================*/
+
+/**
+ * @brief  打开 rtc 设备并加载时区
+ * @return USR_RTC_OK=成功，USR_RTC_ERR_NOT_INIT=设备打开失败或 RTC 未使能
+ */
+UsrRtc_Ret_t usr_rtc_init(void);
+
+/**
+ * @brief  获取当前本地时间（客户常用）
+ * @param  t 成功时写入年月日时分秒；失败时不改动
+ * @return 1=已对时且读成功，0=未初始化/未对时/参数非法
+ */
+uint8_t usr_rtc_get_time(struct sys_time *t);
+
+/**
+ * @brief  App/网关 DEVICEINFO：UTC 秒 + 时区写入 RTC
+ * @param  unix_utc UTC Unix 秒；0 无效
+ * @param  tz_s     时区偏移秒（东八区 28800）
+ * @return USR_RTC_OK=成功，USR_RTC_ERR_NOT_INIT=未初始化，USR_RTC_ERR_PARAM=参数非法，USR_RTC_ERR_INVALID=年份非法
+ */
+UsrRtc_Ret_t usr_rtc_set_from_unix(uint64_t unix_utc, int32_t tz_s);
+
+#endif /* __USR_RTC_H__ */