docs: 按照开发规范重构项目，完成七个环节文档整理与.xagent流程搭建

2026-07-09 10:31:36 +08:00
parent 61b6ecb55d
commit 17a90ff7dc
21 changed files with 1546 additions and 0 deletions
--- a/Docs/60_coding/mod-key.md
+++ b/Docs/60_coding/mod-key.md
@@ -0,0 +1,72 @@
+# 编码实现 - 按键扫描与事件判定 (docs/60_coding/mod-key.md)
+
+本文件对应按键状态消抖、长按计时判定以及组合按键识别的具体编码实现细节。
+
+## 1. 对应代码源文件
+
+*   [App/main.c](file:///c:/workfile/105/stc32g12k128/App/main.c) (定时中断内的按键扫描、按键状态累加、主循环事件处理)
+
+## 2. 关键代码片段与逻辑实现
+
+### 2.1 按键中断定时器扫描 (每 10ms 调度一次)
+在 `Timer1_Isr` (1ms 滴答) 内，通过 `key_scan_timer` 进行 10ms 分频并调用 `Key_Scan_Process()`：
+```c
+void Key_Scan_Process(void) {
+    // 1. 读取引脚状态并消抖
+    static u8 key_up_state = 0xFF;
+    static u8 key_down_state = 0xFF;
+    static u8 key_sos_state = 0xFF;
+    
+    key_up_state = (key_up_state << 1) | KEY_UP;
+    key_down_state = (key_down_state << 1) | KEY_DOWN;
+    key_sos_state = (key_sos_state << 1) | KEY_SOS;
+    
+    // 2. 长按与组合按键计时器累加
+    if ((key_up_state & 0x07) == 0 && (key_down_state & 0x07) == 0) {
+        // ▲ + ▼ 组合键按住
+        comb_hold++;
+        if (comb_hold == 300) { // 3秒
+            key_event_buf = KEY_COMB_LONG;
+        }
+    } else {
+        comb_hold = 0;
+        
+        // 单个按键：▲ 键
+        if ((key_up_state & 0x07) == 0) {
+            key_up_hold++;
+        } else {
+            if (key_up_hold > 2 && key_up_hold < 200) {
+                key_event_buf = KEY_UP_SHORT;
+            }
+            key_up_hold = 0;
+        }
+        
+        // 单个按键：SOS 键
+        if ((key_sos_state & 0x07) == 0) {
+            key_sos_hold++;
+            if (key_sos_hold == 500) { // 5秒
+                key_event_buf = KEY_SOS_LONG;
+            }
+        } else {
+            if (key_sos_hold > 2 && key_sos_hold < 500) {
+                key_event_buf = KEY_SOS_SHORT;
+            }
+            key_sos_hold = 0;
+        }
+        // ▼ 键处理同上...
+    }
+}
+```
+
+### 2.2 事件异步读取与清除
+主循环在其周期内轮询 `key_event_buf`。一旦发现其非 `KEY_EVENT_NONE`，拷贝并立即重置该缓冲区为 `KEY_EVENT_NONE` 以防止重复触发：
+```c
+if (key_event_buf != KEY_EVENT_NONE) {
+    KeyEvent evt = key_event_buf;
+    key_event_buf = KEY_EVENT_NONE; // 清空事件缓冲区
+    
+    // 执行具体事件动作，如在常态下短按 SOS 进入 SOS 警报发射状态等
+    // ...
+}
+```
+通过该缓冲区实现了按键中断采集与主循环处理的解耦。
--- a/Docs/60_coding/mod-lcd.md
+++ b/Docs/60_coding/mod-lcd.md
@@ -0,0 +1,44 @@
+# 编码实现 - LCD 显示与字模驱动 (docs/60_coding/mod-lcd.md)
+
+本文件对应 LCD 驱动与字模渲染的具体编码实现细节。
+
+## 1. 对应代码源文件
+
+*   [Drivers/lcd.c](file:///c:/workfile/105/stc32g12k128/Drivers/lcd.c) (LCD 初始化、SPI 数据写、画图画字函数)
+*   [Drivers/lcd.h](file:///c:/workfile/105/stc32g12k128/Drivers/lcd.h) (管脚接口与画图画字声明)
+*   [Drivers/lcd_font.h](file:///c:/workfile/105/stc32g12k128/Drivers/lcd_font.h) (ASCII 8x16 点阵字模与图标数据)
+
+## 2. 关键代码片段与逻辑实现
+
+### 2.1 局部窗口设置 (X轴偏移量修正)
+在 `lcd.c` 中配置窗口时，需要向 X 轴坐标加上 4 像素偏差：
+```c
+void LCD_SetWindow(u16 x1, u16 y1, u16 x2, u16 y2) {
+    x1 += 4;
+    x2 += 4;
+    LCD_WriteCmd(0x2A); // Column Address Set
+    LCD_WriteData(x1 >> 8);
+    LCD_WriteData(x1 & 0xFF);
+    LCD_WriteData(x2 >> 8);
+    LCD_WriteData(x2 & 0xFF);
+    
+    LCD_WriteCmd(0x2B); // Row Address Set
+    LCD_WriteData(y1 >> 8);
+    LCD_WriteData(y1 & 0xFF);
+    LCD_WriteData(y2 >> 8);
+    LCD_WriteData(y2 & 0xFF);
+}
+```
+
+### 2.2 电池图标与百分比坐标对齐
+在 `main.c` 的时钟重绘函数中，通过以下坐标绘制电量：
+```c
+// 绘制百分比字符
+LCD_ShowString(62, 24, "85%", WHITE, BLACK);
+// 绘制电池位图
+LCD_ShowImage(92, 27, 24, 12, BATTERY_ICON, RED, BLACK);
+```
+两者 Y 轴保持 24 与 27 对齐，X 轴保持 30 像素的安全边距（62 + 3 * 8 = 86，与 92 之间有 6 像素的安全间距），防止文字错乱或重合。
+
+### 2.3 字模百分号偏置
+在 `lcd_font.h` 的 ASCII 字符数组中，百分号 `%`（十进制 37，十六进制 0x25）的字模通过在字模绘制时向上平移 2 像素对齐普通数字的下基准线。
--- a/Docs/60_coding/mod-power.md
+++ b/Docs/60_coding/mod-power.md
@@ -0,0 +1,56 @@
+# 编码实现 - 低功耗电源管理 (docs/60_coding/mod-power.md)
+
+本文件对应低功耗待机与外部中断唤醒的具体编码实现细节。
+
+## 1. 对应代码源文件
+
+*   [App/main.c](file:///c:/workfile/105/stc32g12k128/App/main.c) (休眠控制、外部中断初始化与服务函数)
+
+## 2. 关键代码片段与逻辑实现
+
+### 2.1 屏幕休眠命令与供电切断
+在待机检测到达 10 秒超时后，调用进入睡眠流程：
+```c
+void Enter_Deep_Sleep(void) {
+    // 1. 发送屏幕休眠指令 (Sleep In)
+    LCD_WriteCmd(0x10); 
+    Delay_ms(120); // 必须等待 120ms 供屏幕电容放电
+    
+    // 2. 切断 SGM3833 正负高压供电，阻断 VELVDD 的泄露电流
+    SGM_CTRL = 0; 
+    
+    // 3. 配置 KEY 端口的中断触发（配置为下降沿触发）
+    P0IM0 = 0x00; // 下降沿
+    P0IM1 = 0x00;
+    P0INTE = 0x0E; // 开启 P0.1, P0.2, P0.3 的端口中断
+    
+    // 4. 调用单片机 PD 指令挂起主时钟
+    PCON |= 0x02; // PD = 1
+    _nop_();
+    _nop_();
+}
+```
+
+### 2.2 端口中断唤醒与显示重建
+当按键被按下（P0.1~P0.3 电平跳变），触发外部端口中断，CPU 被唤醒并从停机处继续执行：
+```c
+void Port0_Isr(void) interrupt 37 {
+    u8 int_src = P0INTF;
+    P0INTF = 0x00; // 清除中断标志位
+    
+    if (int_src & 0x0E) {
+        // 1. 恢复 SGM3833 供电
+        SGM_CTRL = 1;
+        Delay_ms(20); // 等待供电稳定
+        
+        // 2. 发送唤醒屏幕指令 (Sleep Out)
+        LCD_WriteCmd(0x11);
+        Delay_ms(120);
+        
+        // 3. 恢复工作状态与屏幕刷新
+        current_state = STATE_NORMAL;
+        clock_updated = 1;
+    }
+}
+```
+通过中断直接退出 `PD` 模式，恢复手环的常规时钟显示。
--- a/Docs/60_coding/mod-rf.md
+++ b/Docs/60_coding/mod-rf.md
@@ -0,0 +1,36 @@
+# 编码实现 - 自适应 RF 解码与发射 (docs/60_coding/mod-rf.md)
+
+本文件对应自适应射频解码与主动发射的具体编码实现细节。
+
+## 1. 对应代码源文件
+
+*   [Drivers/rf.c](file:///c:/workfile/105/stc32g12k128/Drivers/rf.c) (RF 初始化、EV1527 时序比值软解码、主动发射)
+*   [Drivers/rf.h](file:///c:/workfile/105/stc32g12k128/Drivers/rf.h) (芯片控制管脚与编解码函数声明)
+
+## 2. 关键代码片段与逻辑实现
+
+### 2.1 自适应比值解码 (EV1527_Decode)
+解码时，软件轮询检测接收管脚状态。
+1. **抓取同步头**：检测到一个大于 `1500us` 且小于 `60000us` 的低电平。
+2. **计算基准 T**：`T = low_time / 31`。
+3. **采集 24 个数据位**：对于每一位，检测它的高电平持续时间 `h_val` 和低电平持续时间 `l_val`：
+   ```c
+   // 解码一位数据
+   if (h_val > l_val) {
+       res = (res << 1) | 1;
+   } else {
+       res = (res << 1) | 0;
+   }
+   ```
+4. **极速解析与 CPU 效率**：去除了之前在主循环中阻塞多帧解析的详细日志串口打印，仅在解析整帧成功后发送一行 Summary。单帧处理耗时控制在 **2ms** 以内，彻底避免了连续波形导致的丢包现象。
+
+### 2.2 主动对码广播发射
+手环通过 LT4455 发送对码广播，在 `rf.c` 中实现：
+```c
+void EV1527_Transmit(u32 addr, u8 data_code) {
+    // 产生多帧 EV1527 时序
+    // 包含同步头 (高 1T + 低 31T) 与 24 位数据码
+    // ...
+}
+```
+通过控制发射引脚的电平跳转产生标准的 433MHz EV1527 载波信号。
--- a/Docs/60_coding/mod-sys.md
+++ b/Docs/60_coding/mod-sys.md
@@ -0,0 +1,29 @@
+# 编码实现 - 系统核心控制与存储 (docs/60_coding/mod-sys.md)
+
+本文件对应系统控制与存储的具体编码实现细节。
+
+## 1. 对应代码源文件
+
+*   [App/main.c](file:///c:/workfile/105/stc32g12k128/App/main.c) (系统主循环、定时器中断、IAP 存取)
+*   [App/config.h](file:///c:/workfile/105/stc32g12k128/App/config.h) (系统状态及数据结构定义)
+
+## 2. 关键代码片段与逻辑实现
+
+### 2.1 定时器 1 中断服务 (Timer1_Isr)
+定时器初始化配置为 1ms，在 `main.c` 中第 190~250 行左右实现。
+在 `Timer1_Isr` 里，我们累加 `ms_tick`。当累加到 1000 时，重置 `ms_tick = 0`，自增 `current_sec`。若秒达 60，则自增 `current_min` 并置位 `clock_updated = 1` 通知主循环在下一个周期重绘时钟画面。
+
+### 2.2 IAP 读写细节
+在 `main.c` 中通过 IAP 寄存器控制读写。
+```c
+void IAP_EraseSector(u16 addr) {
+    IAP_CMD = 3; // 扇区擦除
+    IAP_ADDRL = addr & 0xFF;
+    IAP_ADDRH = addr >> 8;
+    IAP_TRIG = 0x5A; // 触发
+    IAP_TRIG = 0xA5;
+    _nop_();
+}
+```
+- 主动擦除与写字节前必须先调用使能，写完后调用 `IAP_Disable()` 避免误写入损坏配置。
+- 数据库保存在末尾扇区 `0xFE0000`（大小为 512 字节）。