Initialize repository and implement low-power sleep wakeup
This commit is contained in:
Antigravity IDE
410
Docs/50_module-breakdown/mod-app.md
Normal file
410
Docs/50_module-breakdown/mod-app.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# 模块拆分 - 应用执行层 (Docs/50_module-breakdown/mod-app.md)
|
||||
|
||||
本模块描述手环的 App 调度管理器（AppManager）、前台/后台应用架构、生命周期钩子（OnStart, onRun, onClose, onEvent）、事件分发机制、CPU占用控制以及各功能模块的页面渲染与状态机调度设计。
|
||||
|
||||
---
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
### 1.1 核心职责
|
||||
|
||||
| 职责领域 | 描述 |
|
||||
| :--- | :--- |
|
||||
| **应用生命周期管理** | 维护应用注册表，管理应用的启动、切换、关闭流程 |
|
||||
| **前台/后台应用分离** | 支持前台应用独占屏幕和后台应用持续监听的双轨运行模式 |
|
||||
| **事件分发路由** | 实现前台优先、后台兜底、未处理丢弃的事件分发策略 |
|
||||
| **CPU占用控制** | 监控应用 onRun() 执行时间，防止单个应用长时间占用CPU |
|
||||
| **应用状态维护** | 维护活跃应用指针、应用运行状态标记等核心数据结构 |
|
||||
|
||||
### 1.2 应用类型划分
|
||||
|
||||
系统将应用分为两大类，通过 `AppType` 枚举区分：
|
||||
|
||||
| 应用类型 | 标识 | 特性 | 生命周期 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **前台应用** | `APP_TYPE_FOREGROUND` | 独占屏幕显示，响应用户交互，一次只有一个活跃 | `OnStart` → `onRun`(循环) → `onClose` |
|
||||
| **后台应用** | `APP_TYPE_BACKGROUND` | 无屏幕显示，持续运行监听特定事件，可多个同时运行 | 注册后自动运行，无显式启动/关闭 |
|
||||
|
||||
### 1.3 应用列表
|
||||
|
||||
| 应用ID | 应用名称 | 类型 | 职责描述 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `APP_ID_CLOCK` | ClockApp | 前台 | 待机时钟应用，中央以 32x64px 超大点阵渲染当前时分，右上角渲染 16x32px 电量百分比及充电指示；后台监听射频报警信号 |
|
||||
| `APP_ID_MENU` | MenuApp | 前台 | 主菜单应用，单屏单条目显示交互，支持 ▲/▼ 键高亮切换，确认键进入对应子页面 |
|
||||
| `APP_ID_PAIR` | PairApp | 前台 | 配对与微调应用，对码捕捉到未配对 24 位射频码时拉起，提供微调序号选框，确认后存入持久化 Flash |
|
||||
| `APP_ID_ALARM` | AlarmApp | 前台 | 传感器报警应用，被后台监测唤醒拉起，屏幕闪烁红色粗边框，调度马达振动波形与 LED 警示颜色 |
|
||||
| `APP_ID_SOS` | SOSApp | 前台 | 主动求救应用，短按/长按 SOS 物理按键拉起，周期性发射 0x08 (SOS) 无线电数据，触发最高优先级的持续马达震动及红色幻彩灯爆闪 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心数据结构
|
||||
|
||||
### 2.1 应用描述符结构 (WristbandApp)
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
AppID app_id; // 应用唯一标识 (APP_ID_CLOCK/MENU/PAIR/ALARM/SOS)
|
||||
AppType app_type; // 应用类型 (APP_TYPE_FOREGROUND / APP_TYPE_BACKGROUND)
|
||||
char *app_name; // 应用名称（用于调试日志输出）
|
||||
|
||||
// 生命周期回调函数指针
|
||||
void (*OnStart)(void); // 启动回调：应用切入前台，加载资源、初始化显示
|
||||
void (*onRun)(void); // 循环回调：主循环轮询调用，执行非阻塞业务逻辑
|
||||
void (*onClose)(void); // 关闭回调：应用退出前台，保存状态、清理外设
|
||||
EventResult (*onEvent)(SystemEvent evt); // 事件回调：接收并处理系统事件
|
||||
|
||||
// 运行状态标记
|
||||
bit is_active; // 当前是否活跃（仅对前台应用有效，标识是否在前台运行）
|
||||
bit is_running; // 应用是否处于运行状态（用于CPU占用控制，标记是否允许调用onRun）
|
||||
} WristbandApp;
|
||||
```
|
||||
|
||||
### 2.2 应用ID枚举
|
||||
|
||||
```c
|
||||
typedef enum {
|
||||
APP_ID_CLOCK, // 0: 待机时钟应用
|
||||
APP_ID_MENU, // 1: 主菜单应用
|
||||
APP_ID_PAIR, // 2: 配对与微调应用
|
||||
APP_ID_ALARM, // 3: 传感器报警应用
|
||||
APP_ID_SOS, // 4: 主动求救应用
|
||||
APP_ID_MAX // 5: 应用数量上限（用于数组大小）
|
||||
} AppID;
|
||||
```
|
||||
|
||||
### 2.3 应用类型枚举
|
||||
|
||||
```c
|
||||
typedef enum {
|
||||
APP_TYPE_FOREGROUND, // 前台应用：独占屏幕和用户交互
|
||||
APP_TYPE_BACKGROUND // 后台应用：无屏幕显示，仅监听事件
|
||||
} AppType;
|
||||
```
|
||||
|
||||
### 2.4 事件处理返回值
|
||||
|
||||
```c
|
||||
typedef enum {
|
||||
EVENT_HANDLED, // 事件已处理，停止继续分发
|
||||
EVENT_IGNORED // 事件未处理，继续传递给下一个应用
|
||||
} EventResult;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 应用管理器核心接口
|
||||
|
||||
### 3.1 初始化与注册接口
|
||||
|
||||
| 接口名称 | 函数签名 | 功能描述 |
|
||||
| :--- | :--- | :--- |
|
||||
| `AppManager_Init` | `void AppManager_Init(void)` | 初始化应用管理器，初始化应用注册表，设置默认活跃应用为 ClockApp |
|
||||
| `AppManager_RegisterApp` | `void AppManager_RegisterApp(AppID app_id, AppType app_type, char *app_name, AppStartFunc on_start, AppRunFunc on_run, AppCloseFunc on_close, AppEventFunc on_event)` | 注册应用到注册表，绑定生命周期回调函数 |
|
||||
|
||||
### 3.2 应用切换接口
|
||||
|
||||
| 接口名称 | 函数签名 | 功能描述 |
|
||||
| :--- | :--- | :--- |
|
||||
| `AppManager_StartApp` | `void AppManager_StartApp(AppID app_id)` | 启动指定应用：关闭当前活跃应用 → 切换活跃应用指针 → 启动新应用 |
|
||||
| `AppManager_CloseApp` | `void AppManager_CloseApp(void)` | 关闭当前活跃应用，回退到默认应用（ClockApp） |
|
||||
| `AppManager_GetActiveAppID` | `AppID AppManager_GetActiveAppID(void)` | 获取当前活跃应用的 ID |
|
||||
|
||||
### 3.3 事件分发接口
|
||||
|
||||
| 接口名称 | 函数签名 | 功能描述 |
|
||||
| :--- | :--- | :--- |
|
||||
| `AppManager_DispatchEvent` | `void AppManager_DispatchEvent(SystemEvent evt)` | 分发事件到应用层：前台优先 → 后台兜底 → 未处理丢弃 |
|
||||
| `AppManager_RunActiveApp` | `void AppManager_RunActiveApp(void)` | 运行当前活跃应用的 onRun 回调（带 CPU 占用控制） |
|
||||
|
||||
---
|
||||
|
||||
## 4. 应用生命周期调度机制
|
||||
|
||||
### 4.1 生命周期状态转换
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph 前台应用状态
|
||||
Idle["未注册 / 空闲"] -->|注册| Registered["已注册"]
|
||||
Registered -->|StartApp| Active["活跃中 (OnStart)"]
|
||||
Active -->|onRun循环| Running["运行中"]
|
||||
Running -->|StartApp(其他)| Closing["关闭中 (onClose)"]
|
||||
Closing -->|切换完成| Active
|
||||
Running -->|CloseApp| Closing
|
||||
Closing -->|回退完成| Default["默认状态 (ClockApp)"]
|
||||
end
|
||||
|
||||
subgraph 后台应用状态
|
||||
BG_Idle["未注册"] -->|注册| BG_Running["持续运行"]
|
||||
BG_Running -->|接收事件| BG_Handling["事件处理中"]
|
||||
BG_Handling -->|处理完成| BG_Running
|
||||
end
|
||||
```
|
||||
|
||||
### 4.2 生命周期回调语义
|
||||
|
||||
| 回调函数 | 调用时机 | 职责要求 |
|
||||
| :--- | :--- | :--- |
|
||||
| `OnStart()` | 应用切入前台时 | 初始化显示、加载资源、重置状态变量 |
|
||||
| `onRun()` | 主循环每轮调用 | 执行非阻塞业务逻辑（如动画更新、超时检测），必须控制执行时间 |
|
||||
| `onClose()` | 应用退出前台时 | 保存状态、清理外设（关屏、停振、关闭射频等） |
|
||||
| `onEvent(evt)` | 收到事件时 | 处理事件，返回 `EVENT_HANDLED` 或 `EVENT_IGNORED` |
|
||||
|
||||
### 4.3 应用切换流程
|
||||
|
||||
```
|
||||
AppManager_StartApp(target_app_id) 执行流程：
|
||||
|
||||
1. 参数有效性检查
|
||||
├── app_id >= APP_ID_MAX → 返回错误
|
||||
├── 目标应用非前台应用 → 返回错误
|
||||
└── 目标应用未注册 (OnStart == NULL) → 返回错误
|
||||
|
||||
2. 目标应用已是活跃应用 → 直接返回
|
||||
|
||||
3. 关闭当前活跃应用
|
||||
└── active_app->onClose() → 清理外设、保存状态
|
||||
|
||||
4. 切换活跃应用指针
|
||||
└── active_app = &app_registry[target_app_id]
|
||||
|
||||
5. 启动新应用
|
||||
└── active_app->OnStart() → 初始化显示、加载资源
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 事件分发机制
|
||||
|
||||
### 5.1 事件分发规则
|
||||
|
||||
事件在应用层的分发遵循以下顺序，前台应用优先处理，后台应用作为兜底：
|
||||
|
||||
```
|
||||
事件分发流程 (AppManager_DispatchEvent):
|
||||
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Step 1: 前台应用优先处理 │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ if (active_app != NULL && active_app->is_active) │ │
|
||||
│ │ { │ │
|
||||
│ │ result = active_app->onEvent(evt); │ │
|
||||
│ │ if (result == EVENT_HANDLED) │ │
|
||||
│ │ return; // 前台应用已处理，结束分发 │ │
|
||||
│ │ } │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ Step 2: 后台应用兜底处理 │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ for (i = 0; i < APP_ID_MAX; i++) │ │
|
||||
│ │ { │ │
|
||||
│ │ bg_app = &app_registry[i]; │ │
|
||||
│ │ // 仅处理后台应用 │ │
|
||||
│ │ if (bg_app->app_type != APP_TYPE_BACKGROUND || │ │
|
||||
│ │ bg_app->onEvent == NULL) │ │
|
||||
│ │ continue; │ │
|
||||
│ │ │ │
|
||||
│ │ result = bg_app->onEvent(evt); │ │
|
||||
│ │ if (result == EVENT_HANDLED) │ │
|
||||
│ │ return; // 某后台应用已处理，结束分发 │ │
|
||||
│ │ } │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ Step 3: 事件丢弃 │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ // 前台和后台应用均未处理，事件被丢弃 │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 5.2 事件处理示例
|
||||
|
||||
以下为各应用的典型事件处理行为：
|
||||
|
||||
| 事件类型 | ClockApp | MenuApp | PairApp | AlarmApp | SOSApp |
|
||||
| :--- | :--- | :--- | :--- | :--- | :--- |
|
||||
| `KEY_EVENT_UP_CLICK` | IGNORED | HANDLED (上移) | IGNORED | HANDLED (清除) | IGNORED |
|
||||
| `KEY_EVENT_DOWN_CLICK` | IGNORED | HANDLED (下移) | IGNORED | HANDLED (清除) | IGNORED |
|
||||
| `KEY_EVENT_SOS_CLICK` | HANDLED (启动SOS) | IGNORED | IGNORED | HANDLED (清除) | IGNORED |
|
||||
| `KEY_EVENT_UP_DOWN_COMB` | HANDLED (启动Menu) | IGNORED | IGNORED | IGNORED | IGNORED |
|
||||
| `KEY_EVENT_SOS_LONG` | HANDLED (绑定IPC) | IGNORED | HANDLED (保存) | IGNORED | HANDLED (退出) |
|
||||
| `KEY_EVENT_DOWN_LONG` | IGNORED | HANDLED (返回) | HANDLED (退出) | IGNORED | HANDLED (退出) |
|
||||
|
||||
---
|
||||
|
||||
## 6. CPU 占用控制机制
|
||||
|
||||
### 6.1 设计目的
|
||||
|
||||
为防止单个应用的 `onRun()` 回调长时间占用 CPU 导致系统响应迟钝或卡死，框架引入 **执行时间监控机制**。
|
||||
|
||||
### 6.2 控制参数
|
||||
|
||||
| 参数名称 | 定义 | 默认值 | 说明 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `APP_ONRUN_MAX_TICKS` | onRun 最大执行时间阈值 | 5 (ms) | 超过此时间则暂停应用运行 |
|
||||
|
||||
### 6.3 监控机制
|
||||
|
||||
```
|
||||
AppManager_RunActiveApp() 执行流程：
|
||||
|
||||
1. 检查应用状态
|
||||
└── if (active_app == NULL || !active_app->is_active) → 直接返回
|
||||
|
||||
2. 记录开始时间
|
||||
└── start_tick = ms_tick
|
||||
|
||||
3. 执行应用的 onRun() 回调
|
||||
└── active_app->onRun()
|
||||
|
||||
4. 计算执行耗时
|
||||
└── elapsed_ticks = ms_tick - start_tick
|
||||
|
||||
5. 判断是否超时
|
||||
├── if (elapsed_ticks > APP_ONRUN_MAX_TICKS)
|
||||
│ └── active_app->is_running = 0 // 暂停应用
|
||||
└── else
|
||||
└── active_app->is_running = 1 // 继续运行
|
||||
```
|
||||
|
||||
### 6.4 超时恢复
|
||||
|
||||
* 超时后应用的 `is_running` 标记被置为 0，下一次主循环将跳过该应用的 `onRun()` 调用
|
||||
* 应用可在下一次循环中自动恢复运行（`is_running` 在 `onRun` 调用前被检查，调用后被更新）
|
||||
* 此机制不会杀死应用，仅暂停其循环执行，允许应用在后续恢复
|
||||
|
||||
---
|
||||
|
||||
## 7. 应用实现细节
|
||||
|
||||
### 7.1 ClockApp（时钟应用）
|
||||
|
||||
**职责**：待机时钟显示、后台射频监测
|
||||
|
||||
**生命周期实现**：
|
||||
|
||||
| 回调 | 实现逻辑 |
|
||||
| :--- | :--- |
|
||||
| `OnStart` | 初始化状态为 NORMAL，设置重绘标志 |
|
||||
| `onRun` | 分钟变化时重绘时钟；后台监听射频信号，匹配到已配对传感器触发报警 |
|
||||
| `onClose` | 清理资源 |
|
||||
| `onEvent` | 处理组合键进入菜单、SOS 按键进入求救模式、长按绑定 IPC |
|
||||
|
||||
### 7.2 MenuApp（菜单应用）
|
||||
|
||||
**职责**：主菜单导航
|
||||
|
||||
**生命周期实现**：
|
||||
|
||||
| 回调 | 实现逻辑 |
|
||||
| :--- | :--- |
|
||||
| `OnStart` | 初始化菜单选择项为 0，关闭射频，显示菜单页面 |
|
||||
| `onRun` | 无持续运行逻辑 |
|
||||
| `onClose` | 重新开启射频接收 |
|
||||
| `onEvent` | 处理上/下键切换菜单项、确认键进入配对、长按返回时钟 |
|
||||
|
||||
### 7.3 PairApp（配对应用）
|
||||
|
||||
**职责**：传感器配对与保存
|
||||
|
||||
**生命周期实现**：
|
||||
|
||||
| 回调 | 实现逻辑 |
|
||||
| :--- | :--- |
|
||||
| `OnStart` | 进入等待状态，开启射频接收，显示雷达搜索页面 |
|
||||
| `onRun` | 更新雷达动画；监听射频信号捕获对码；检测超时 |
|
||||
| `onClose` | 关闭射频，重置配对状态 |
|
||||
| `onEvent` | 处理长按退出、确认保存对码 |
|
||||
|
||||
### 7.4 AlarmApp（报警应用）
|
||||
|
||||
**职责**：入侵警报显示与响应
|
||||
|
||||
**生命周期实现**：
|
||||
|
||||
| 回调 | 实现逻辑 |
|
||||
| :--- | :--- |
|
||||
| `OnStart` | 设置状态为 ALARM，显示报警页面，重置报警定时器 |
|
||||
| `onRun` | 控制报警边框闪烁效果 |
|
||||
| `onClose` | 停止报警效果（马达、LED），恢复正常状态 |
|
||||
| `onEvent` | 任何按键清除报警 |
|
||||
|
||||
### 7.5 SOSApp（求救应用）
|
||||
|
||||
**职责**：主动求救模式
|
||||
|
||||
**生命周期实现**：
|
||||
|
||||
| 回调 | 实现逻辑 |
|
||||
| :--- | :--- |
|
||||
| `OnStart` | 设置状态为 SOS_EMITTED，显示 SOS 页面 |
|
||||
| `onRun` | 每 500ms 发射一次射频求救帧；控制红色边框闪烁 |
|
||||
| `onClose` | 停止求救效果（马达、LED），恢复正常状态 |
|
||||
| `onEvent` | 长按任意键解除求救 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 页面渲染接口
|
||||
|
||||
| 接口名称 | 函数签名 | 所属应用 | 功能描述 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `UI_ShowClockPage` | `void UI_ShowClockPage(SystemState state, u8 hour, u8 min)` | ClockApp | 绘制时钟页面，包含时间显示和电量指示 |
|
||||
| `UI_ShowPairMenuPage` | `void UI_ShowPairMenuPage(u8 selected_item)` | MenuApp | 绘制配对菜单页面，显示选中项图标和名称 |
|
||||
| `UI_ShowPairWaitPage` | `void UI_ShowPairWaitPage(u8 frame)` | PairApp | 绘制雷达搜索页面，包含动画帧 |
|
||||
| `UI_ShowPairConfirmPage` | `void UI_ShowPairConfirmPage(u32 addr)` | PairApp | 绘制配对确认页面，显示捕获到的射频地址 |
|
||||
| `UI_ShowPairSuccessPage` | `void UI_ShowPairSuccessPage(u32 addr)` | PairApp | 绘制配对成功页面 |
|
||||
| `UI_ShowPairFailPage` | `void UI_ShowPairFailPage(u8 reason)` | PairApp | 绘制配对失败页面 |
|
||||
| `UI_ShowAlarmPage` | `void UI_ShowAlarmPage(char *name, u8 severity)` | AlarmApp | 绘制报警页面，包含红色边框和传感器名称 |
|
||||
| `UI_ShowSosPage` | `void UI_ShowSosPage(void)` | SOSApp | 绘制 SOS 求救页面 |
|
||||
| `UI_ShowBindingPage` | `void UI_ShowBindingPage(void)` | ClockApp | 绘制 IPC 绑定页面 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 应用注册表结构
|
||||
|
||||
应用管理器维护一个静态数组 `app_registry[APP_ID_MAX]`，存储所有已注册的应用：
|
||||
|
||||
```c
|
||||
static WristbandApp app_registry[APP_ID_MAX];
|
||||
static WristbandApp *active_app = NULL; // 当前活跃前台应用指针
|
||||
#define DEFAULT_APP_ID APP_ID_CLOCK // 默认应用为时钟
|
||||
```
|
||||
|
||||
注册流程：
|
||||
1. 系统初始化时调用 `AppManager_Init()` 初始化注册表
|
||||
2. 各应用模块调用 `AppManager_RegisterApp()` 注册自身
|
||||
3. 最后调用 `AppManager_Init()` 设置默认活跃应用
|
||||
|
||||
---
|
||||
|
||||
## 10. 主循环集成
|
||||
|
||||
主循环中应用管理器的调用顺序：
|
||||
|
||||
```
|
||||
while(1)
|
||||
{
|
||||
// 1. 处理串口调试输入
|
||||
cmd = Uart_RxChar();
|
||||
if (cmd != '\0')
|
||||
// 解析命令，生成事件，调用 EventQueue_Push 或 EventQueue_InsertFront
|
||||
|
||||
// 2. 处理按键事件缓冲区
|
||||
if (key_event_buf != KEY_EVENT_NONE)
|
||||
// 生成事件，根据优先级选择入队(Push)或插队(InsertFront)
|
||||
key_event_buf = KEY_EVENT_NONE;
|
||||
|
||||
// 3. 处理事件队列
|
||||
while (!EventQueue_IsEmpty())
|
||||
{
|
||||
evt = EventQueue_Pop();
|
||||
AppManager_DispatchEvent(evt);
|
||||
}
|
||||
|
||||
// 4. 运行当前活跃应用（带CPU占用控制）
|
||||
AppManager_RunActiveApp();
|
||||
|
||||
// 5. 其他系统监控（如LED/马达状态输出）
|
||||
}
|
||||
```
|
||||
597
Docs/50_module-breakdown/mod-event.md
Normal file
597
Docs/50_module-breakdown/mod-event.md
Normal file
@@ -0,0 +1,597 @@
|
||||
# 模块拆分 - 事件采集与总线分发管理 (Docs/50_module-breakdown/mod-event.md)
|
||||
|
||||
本模块描述系统输入事件采集（按键移位消抖滤波与 RF 自适应解调解码）、事件优先级体系、事件环形队列（EventQueue）缓冲、紧急事件插队机制以及事件输出分配的整体流转规格。
|
||||
|
||||
---
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
### 1.1 核心职责
|
||||
|
||||
| 职责领域 | 描述 |
|
||||
| :--- | :--- |
|
||||
| **事件采集（按键输入）** | 在 Timer1 中断 (10ms 时基) 中扫描物理引脚，判定有效按键后封装为事件 |
|
||||
| **事件采集（射频接收）** | 在外部中断中捕获射频信号，解调并还原 24 位载波包，封装为射频事件 |
|
||||
| **事件优先级管理** | 根据事件类型分配优先级，支持四级优先级体系 |
|
||||
| **事件队列缓冲** | 维护深度为 8 的环形事件队列，隔离高频中断和低频业务交互 |
|
||||
| **紧急事件插队** | 提供将紧急事件插入队列头部的路径，确保紧急事件优先处理 |
|
||||
| **事件输出路由分发** | 在主循环中轮询队列，将事件分发给应用管理器 |
|
||||
|
||||
### 1.2 事件来源与优先级映射
|
||||
|
||||
| 事件来源 | 典型事件 | 优先级 | 处理方式 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **SOS 按键** | `KEY_EVENT_SOS_CLICK`, `KEY_EVENT_SOS_LONG` | URGENT | **插队**到队首 |
|
||||
| **射频报警** | `RF_EVENT_ALARM` | HIGH | **插队**到队首 |
|
||||
| **普通按键** | `KEY_EVENT_UP_CLICK`, `KEY_EVENT_DOWN_CLICK`, `KEY_EVENT_UP_DOWN_COMB` | NORMAL | 入队等待处理 |
|
||||
| **射频配对** | `RF_EVENT_PAIR` | NORMAL | 入队等待处理 |
|
||||
| **系统定时** | 时钟更新、超时检测 | LOW | 入队等待处理 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心数据结构
|
||||
|
||||
### 2.1 扩展事件结构体 (SystemEvent)
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
KeyEvent key_event; // 原始按键事件类型
|
||||
EventPriority priority; // 事件优先级 (LOW/NORMAL/HIGH/URGENT)
|
||||
u32 extra_data; // 额外数据（如射频地址、时间信息等）
|
||||
u8 extra_size; // 额外数据有效字节数
|
||||
} SystemEvent;
|
||||
```
|
||||
|
||||
**字段说明**：
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
| :--- | :--- | :--- |
|
||||
| `key_event` | `KeyEvent` | 按键事件的原始类型，如 `KEY_EVENT_UP_CLICK`、`KEY_EVENT_SOS_LONG` |
|
||||
| `priority` | `EventPriority` | 事件优先级，决定事件的处理路径（入队或直通） |
|
||||
| `extra_data` | `u32` | 额外携带的数据，用于传递射频地址、时间等信息 |
|
||||
| `extra_size` | `u8` | `extra_data` 中有效数据的字节数（0~4） |
|
||||
|
||||
### 2.2 事件优先级枚举
|
||||
|
||||
```c
|
||||
typedef enum {
|
||||
EVENT_PRIORITY_LOW, // 0: 低优先级：系统内部事件，如定时更新
|
||||
EVENT_PRIORITY_NORMAL, // 1: 正常优先级：大部分用户交互事件
|
||||
EVENT_PRIORITY_HIGH, // 2: 高优先级：报警相关事件，插队到队首
|
||||
EVENT_PRIORITY_URGENT // 3: 紧急优先级：SOS等，插队到队首
|
||||
} EventPriority;
|
||||
```
|
||||
|
||||
### 2.3 按键事件类型枚举
|
||||
|
||||
```c
|
||||
typedef enum {
|
||||
KEY_EVENT_NONE, // 0: 无事件
|
||||
KEY_EVENT_UP_CLICK, // 1: 上键短按
|
||||
KEY_EVENT_UP_LONG, // 2: 上键长按
|
||||
KEY_EVENT_DOWN_CLICK, // 3: 下键短按
|
||||
KEY_EVENT_DOWN_LONG, // 4: 下键长按
|
||||
KEY_EVENT_SOS_CLICK, // 5: SOS键短按
|
||||
KEY_EVENT_SOS_LONG, // 6: SOS键长按
|
||||
KEY_EVENT_UP_DOWN_COMB // 7: 上下键组合
|
||||
} KeyEvent;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 事件队列模块
|
||||
|
||||
### 3.1 队列设计参数
|
||||
|
||||
| 参数名称 | 定义 | 默认值 | 说明 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `EVENT_QUEUE_DEPTH` | 队列深度（环形缓冲区大小） | 8 | 可配置，建议值为 4~16 |
|
||||
| `queue_head` | 读指针 | 0 | 指向即将读取的位置 |
|
||||
| `queue_tail` | 写指针 | 0 | 指向即将写入的位置 |
|
||||
| `queue_count` | 当前事件数量 | 0 | 范围 0~EVENT_QUEUE_DEPTH |
|
||||
|
||||
### 3.2 队列内部结构
|
||||
|
||||
```c
|
||||
static SystemEvent event_queue[EVENT_QUEUE_DEPTH]; // 环形缓冲区存储数组
|
||||
static u8 queue_head = 0; // 读指针：指向即将读取的位置
|
||||
static u8 queue_tail = 0; // 写指针：指向即将写入的位置
|
||||
static u8 queue_count = 0; // 当前队列中的事件数量
|
||||
```
|
||||
|
||||
### 3.3 队列操作接口
|
||||
|
||||
| 接口名称 | 函数签名 | 返回值 | 功能描述 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `EventQueue_Init` | `void EventQueue_Init(void)` | 无 | 初始化队列：重置读写指针和计数器 |
|
||||
| `EventQueue_Push` | `bit EventQueue_Push(SystemEvent evt)` | `bit` (1=成功, 0=失败) | 非阻塞将事件推入队列尾部，队列满时返回 0 |
|
||||
| `EventQueue_InsertFront` | `bit EventQueue_InsertFront(SystemEvent evt)` | `bit` (1=成功, 0=失败) | **插队**：将事件插入到队列头部，高/紧急优先级事件使用 |
|
||||
| `EventQueue_Pop` | `SystemEvent EventQueue_Pop(void)` | `SystemEvent` | 从队列头部弹出一个事件，队空时返回空事件 |
|
||||
| `EventQueue_IsEmpty` | `bit EventQueue_IsEmpty(void)` | `bit` (1=空) | 判断队列是否为空 |
|
||||
| `EventQueue_IsFull` | `bit EventQueue_IsFull(void)` | `bit` (1=满) | 判断队列是否已满 |
|
||||
| `EventQueue_GetCount` | `u8 EventQueue_GetCount(void)` | `u8` | 获取队列中当前事件数量 |
|
||||
|
||||
### 3.4 队列操作流程
|
||||
|
||||
#### 入队操作 (EventQueue_Push)
|
||||
|
||||
```
|
||||
EventQueue_Push(evt) 执行流程：
|
||||
|
||||
1. 检查队列是否已满
|
||||
└── if (queue_count >= EVENT_QUEUE_DEPTH) → 返回 0（入队失败）
|
||||
|
||||
2. 禁用全局中断（保护队列操作原子性）
|
||||
└── EA = 0
|
||||
|
||||
3. 将事件写入环形缓冲区
|
||||
└── event_queue[queue_tail] = evt
|
||||
|
||||
4. 更新写指针（循环递增）
|
||||
└── queue_tail = (queue_tail + 1) % EVENT_QUEUE_DEPTH
|
||||
|
||||
5. 更新事件计数
|
||||
└── queue_count++
|
||||
|
||||
6. 恢复全局中断
|
||||
└── EA = 1
|
||||
|
||||
7. 返回成功
|
||||
└── return 1
|
||||
```
|
||||
|
||||
#### 出队操作 (EventQueue_Pop)
|
||||
|
||||
```
|
||||
EventQueue_Pop() 执行流程：
|
||||
|
||||
1. 初始化返回的空事件
|
||||
└── evt.key_event = KEY_EVENT_NONE
|
||||
evt.priority = EVENT_PRIORITY_LOW
|
||||
evt.extra_data = 0
|
||||
evt.extra_size = 0
|
||||
|
||||
2. 检查队列是否为空
|
||||
└── if (queue_count == 0) → 返回空事件
|
||||
|
||||
3. 禁用全局中断（保护队列操作原子性）
|
||||
└── EA = 0
|
||||
|
||||
4. 从队列头部读取事件
|
||||
└── evt = event_queue[queue_head]
|
||||
|
||||
5. 更新读指针（循环递增）
|
||||
└── queue_head = (queue_head + 1) % EVENT_QUEUE_DEPTH
|
||||
|
||||
6. 更新事件计数
|
||||
└── queue_count--
|
||||
|
||||
7. 恢复全局中断
|
||||
└── EA = 1
|
||||
|
||||
8. 返回读取到的事件
|
||||
└── return evt
|
||||
```
|
||||
|
||||
#### 插队操作 (EventQueue_InsertFront)
|
||||
|
||||
```
|
||||
EventQueue_InsertFront(evt) 执行流程：
|
||||
|
||||
1. 检查队列是否已满
|
||||
└── if (queue_count >= EVENT_QUEUE_DEPTH) → 返回 0（插队失败）
|
||||
|
||||
2. 禁用全局中断（保护队列操作原子性）
|
||||
└── EA = 0
|
||||
|
||||
3. 更新读指针（向前移动一位，循环递减）
|
||||
└── queue_head = (queue_head - 1 + EVENT_QUEUE_DEPTH) % EVENT_QUEUE_DEPTH
|
||||
|
||||
4. 将事件写入队列头部
|
||||
└── event_queue[queue_head] = evt
|
||||
|
||||
5. 更新事件计数
|
||||
└── queue_count++
|
||||
|
||||
6. 恢复全局中断
|
||||
└── EA = 1
|
||||
|
||||
7. 返回成功
|
||||
└── return 1
|
||||
|
||||
注意：此函数将事件插入到队列头部，适用于高/紧急优先级事件，
|
||||
确保此类事件优先于队列中已有的事件被处理。
|
||||
```
|
||||
|
||||
### 3.5 中断保护机制
|
||||
|
||||
队列操作使用全局中断开关 `EA` 进行保护，确保在中断环境下的原子性：
|
||||
|
||||
```
|
||||
中断保护原则：
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. 入队操作可能在中断中被调用（按键扫描、RF接收） │
|
||||
│ └── 需要保护队列数据结构不被并发访问 │
|
||||
│ │
|
||||
│ 2. 出队操作在主循环中被调用 │
|
||||
│ └── 需要保护队列数据结构不被中断破坏 │
|
||||
│ │
|
||||
│ 3. 保护方式：禁用全局中断 → 执行操作 → 恢复全局中断 │
|
||||
│ └── 最小化中断禁用时间，减少对系统响应性的影响 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 事件采集机制
|
||||
|
||||
### 4.1 按键事件采集
|
||||
|
||||
#### 采集流程
|
||||
|
||||
```
|
||||
按键事件采集流程（Timer1 10ms 中断）：
|
||||
|
||||
1. 读取物理引脚状态
|
||||
└── P0.1 (KEY_UP), P0.2 (KEY_CONFIRM), P0.3 (KEY_DOWN), P2.6 (KEY_SOS)
|
||||
|
||||
2. 移位消抖滤波
|
||||
└── 连续 3 次检测一致确认为有效电平变化
|
||||
|
||||
3. 判断按键类型
|
||||
├── 短按：按下后 200ms 内释放
|
||||
├── 长按：按下持续时间 >= 2000ms (DOWN键) 或 >= 3000ms (其他键)
|
||||
└── 组合键：UP 和 DOWN 同时按下
|
||||
|
||||
4. 将事件写入缓冲区（中断中仅标记事件，不直接处理）
|
||||
└── key_event_buf = 对应的按键事件类型
|
||||
|
||||
注意：中断中不直接调用事件处理函数，避免在ISR中执行耗时操作（如Delay_ms、LCD绘制）。
|
||||
事件的优先级判断和分发由主循环完成。
|
||||
```
|
||||
|
||||
#### 按键消抖时序
|
||||
|
||||
```
|
||||
按键消抖时序图：
|
||||
|
||||
时间轴 →
|
||||
├──────────────────────────────────────────────────────────────┐
|
||||
│ 物理按键 ──────┐ │ │
|
||||
│ (实际) LOW │───────────────── HIGH ────────────│──────│ │
|
||||
├─────────────────┼────────────────────────────────────┼──────┤ │
|
||||
│ 10ms采样 ───────┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──────┤ │
|
||||
│ (抖动区) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
|
||||
├─────────────────┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──────┤ │
|
||||
│ 消抖结果 ───────┼──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──────┤ │
|
||||
│ (连续3次 │ LOW HIGH │ │
|
||||
│ 一致才确认) └──────────────────────────────────────────┘ │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ ↑ 抖动区结束，确认按键按下 │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4.2 射频事件采集
|
||||
|
||||
#### 采集流程
|
||||
|
||||
```
|
||||
射频事件采集流程（外部中断 P2.1）：
|
||||
|
||||
1. 射频输入引脚 RF_RX_DATA (P2.1) 发生电平沿变化
|
||||
└── 触发外部中断
|
||||
|
||||
2. 定时器捕获高低电平比值
|
||||
└── 解调自适应基准 T
|
||||
|
||||
3. 连续采集 24 个数据位
|
||||
└── 组合还原 20 位物理 ID 及 4 位状态码
|
||||
|
||||
4. 校验与识别
|
||||
├── 解密通过
|
||||
├── 判断是对码事件还是报警事件
|
||||
|
||||
5. 封装事件
|
||||
└── SystemEvent evt;
|
||||
evt.key_event = KEY_EVENT_NONE; // 射频事件无按键类型
|
||||
evt.extra_data = 射频地址;
|
||||
evt.extra_size = 4;
|
||||
|
||||
6. 设置优先级并入队
|
||||
├── 报警事件 → evt.priority = EVENT_PRIORITY_HIGH
|
||||
└── 配对事件 → evt.priority = EVENT_PRIORITY_NORMAL
|
||||
→ EventQueue_Push(evt)
|
||||
```
|
||||
|
||||
#### RF 解调参数
|
||||
|
||||
| 参数 | 值 | 说明 |
|
||||
| :--- | :--- | :--- |
|
||||
| **载波频率** | 433MHz | LR690L 射频芯片工作频率 |
|
||||
| **编码方式** | EV1527 | 24 位曼彻斯特编码 |
|
||||
| **数据位** | 24 位 | 20 位物理地址 + 4 位状态码 |
|
||||
| **解调方式** | 自适应基准 T | 根据信号自动调整采样基准 |
|
||||
|
||||
### 4.3 系统定时事件
|
||||
|
||||
```
|
||||
系统定时事件产生流程（Timer1 1ms 中断）：
|
||||
|
||||
1. 毫秒计数器累加
|
||||
└── ms_tick++
|
||||
|
||||
2. 秒分频检测
|
||||
└── if (ms_tick % 1000 == 0) → 秒计数加1
|
||||
|
||||
3. 分钟变化检测
|
||||
└── if (分钟变化) → 产生时钟更新事件
|
||||
|
||||
4. 封装事件
|
||||
└── SystemEvent evt;
|
||||
evt.key_event = KEY_EVENT_NONE;
|
||||
evt.priority = EVENT_PRIORITY_LOW;
|
||||
evt.extra_data = ((u32)hour << 8) | min;
|
||||
evt.extra_size = 2;
|
||||
|
||||
5. 入队处理
|
||||
└── EventQueue_Push(evt)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 事件分发机制
|
||||
|
||||
### 5.1 事件流转完整架构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% 事件产生层
|
||||
subgraph EventSources ["事件来源"]
|
||||
KeyScan["按键扫描 (10ms)"]
|
||||
RFRecv["射频接收 (中断)"]
|
||||
Timer["定时事件 (1ms)"]
|
||||
end
|
||||
|
||||
%% 事件封装层
|
||||
KeyScan -->|封装| KeyEventPack["按键事件封装"]
|
||||
RFRecv -->|封装| RFEventPack["射频事件封装"]
|
||||
Timer -->|封装| TimerEventPack["定时事件封装"]
|
||||
|
||||
%% 优先级判断
|
||||
KeyEventPack --> PriorityJudge{"优先级判断"}
|
||||
RFEventPack --> PriorityJudge
|
||||
TimerEventPack --> PriorityJudge
|
||||
|
||||
%% 分流处理
|
||||
PriorityJudge -->|HIGH/URGENT| InsertFront["插队到队首"]
|
||||
PriorityJudge -->|LOW/NORMAL| Push["入队"]
|
||||
|
||||
%% 队列处理
|
||||
InsertFront --> Queue["EventQueue 环形缓冲区"]
|
||||
Push --> Queue
|
||||
Queue --> MainLoop["主循环轮询出队"]
|
||||
MainLoop --> AppMgr["AppManager_DispatchEvent"]
|
||||
|
||||
%% 应用层处理
|
||||
AppMgr --> FG_App["前台应用 (优先)"]
|
||||
FG_App -->|IGNORED| BG_Apps["后台应用 (兜底)"]
|
||||
FG_App -->|HANDLED| Done["处理完成"]
|
||||
BG_Apps -->|IGNORED| Discard["事件丢弃"]
|
||||
BG_Apps -->|HANDLED| Done
|
||||
```
|
||||
|
||||
### 5.2 主循环事件处理流程
|
||||
|
||||
```
|
||||
主循环事件处理流程：
|
||||
|
||||
while(1)
|
||||
{
|
||||
// 1. 处理串口调试输入
|
||||
cmd = Uart_RxChar();
|
||||
if (cmd != '\0')
|
||||
{
|
||||
// 解析命令生成事件
|
||||
SystemEvent evt;
|
||||
evt.key_event = 对应的按键事件;
|
||||
evt.priority = 命令对应的优先级;
|
||||
|
||||
// 根据优先级选择入队方式
|
||||
if (evt.priority >= EVENT_PRIORITY_HIGH)
|
||||
EventQueue_InsertFront(evt); // 高/紧急优先级插队到队首
|
||||
else
|
||||
EventQueue_Push(evt); // 低/正常优先级入队
|
||||
}
|
||||
|
||||
// 2. 处理按键事件缓冲区（来自定时器中断）
|
||||
if (key_event_buf != KEY_EVENT_NONE)
|
||||
{
|
||||
SystemEvent evt;
|
||||
evt.key_event = key_event_buf;
|
||||
evt.extra_data = 0;
|
||||
evt.extra_size = 0;
|
||||
|
||||
// 判断事件优先级
|
||||
if (key_event_buf == KEY_EVENT_SOS_CLICK ||
|
||||
key_event_buf == KEY_EVENT_SOS_LONG)
|
||||
{
|
||||
evt.priority = EVENT_PRIORITY_URGENT;
|
||||
EventQueue_InsertFront(evt); // 紧急事件插队到队首
|
||||
}
|
||||
else
|
||||
{
|
||||
evt.priority = EVENT_PRIORITY_NORMAL;
|
||||
EventQueue_Push(evt); // 普通事件入队
|
||||
}
|
||||
|
||||
key_event_buf = KEY_EVENT_NONE;
|
||||
}
|
||||
|
||||
// 3. 处理事件队列中的所有事件
|
||||
while (!EventQueue_IsEmpty())
|
||||
{
|
||||
SystemEvent evt = EventQueue_Pop();
|
||||
|
||||
// 跳过空事件
|
||||
if (evt.key_event == KEY_EVENT_NONE &&
|
||||
evt.priority == EVENT_PRIORITY_LOW)
|
||||
continue;
|
||||
|
||||
// 分发事件给应用管理器
|
||||
AppManager_DispatchEvent(evt);
|
||||
}
|
||||
|
||||
// 4. 运行当前活跃应用
|
||||
AppManager_RunActiveApp();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 事件优先级与处理路径总结
|
||||
|
||||
| 优先级 | 标识 | 处理路径 | 典型事件 | 特点 |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **URGENT** | 3 | `EventQueue_InsertFront()` → 插队到队首 → `EventQueue_Pop()` → `AppManager_DispatchEvent()` | SOS 按键 | 插队到队首，优先处理 |
|
||||
| **HIGH** | 2 | `EventQueue_InsertFront()` → 插队到队首 → `EventQueue_Pop()` → `AppManager_DispatchEvent()` | 传感器入侵警报 | 插队到队首，优先处理 |
|
||||
| **NORMAL** | 1 | `EventQueue_Push()` → 入队等待 → `EventQueue_Pop()` → `AppManager_DispatchEvent()` | 普通按键、射频配对 | 常规处理路径 |
|
||||
| **LOW** | 0 | `EventQueue_Push()` → 入队等待 → `EventQueue_Pop()` → `AppManager_DispatchEvent()` | 时钟更新、超时检测 | 低优先级，不阻塞其他事件 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 事件丢弃机制
|
||||
|
||||
当事件经过完整的分发流程后仍未被任何应用处理时，事件将被丢弃：
|
||||
|
||||
```
|
||||
事件丢弃条件：
|
||||
1. 前台应用 active_app == NULL 或未返回 EVENT_HANDLED
|
||||
2. 所有后台应用均未返回 EVENT_HANDLED
|
||||
|
||||
丢弃处理：
|
||||
- 事件数据被自动释放（队列弹出后即被丢弃）
|
||||
- 无额外日志记录（嵌入式系统资源限制）
|
||||
- 可通过调试串口观察事件处理情况
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 接口与函数说明汇总
|
||||
|
||||
### 8.1 事件队列接口
|
||||
|
||||
| 函数名 | 签名 | 功能 |
|
||||
| :--- | :--- | :--- |
|
||||
| `EventQueue_Init` | `void EventQueue_Init(void)` | 初始化事件队列，复位读写指针与计数器 |
|
||||
| `EventQueue_Push` | `bit EventQueue_Push(SystemEvent evt)` | 非阻塞将事件推入队列尾部，成功返回 1 |
|
||||
| `EventQueue_InsertFront` | `bit EventQueue_InsertFront(SystemEvent evt)` | **插队**：将事件插入到队列头部，高/紧急优先级事件使用 |
|
||||
| `EventQueue_Pop` | `SystemEvent EventQueue_Pop(void)` | 从队列头部弹出一个事件，队空返回空事件 |
|
||||
| `EventQueue_IsEmpty` | `bit EventQueue_IsEmpty(void)` | 判断队列是否为空 |
|
||||
| `EventQueue_IsFull` | `bit EventQueue_IsFull(void)` | 判断队列是否已满 |
|
||||
| `EventQueue_GetCount` | `u8 EventQueue_GetCount(void)` | 获取队列中当前事件数量 |
|
||||
|
||||
### 8.2 事件采集接口
|
||||
|
||||
| 函数名 | 签名 | 功能 |
|
||||
| :--- | :--- | :--- |
|
||||
| `Key_Scan_Process` | `void Key_Scan_Process(void)` | Timer1 (10ms) 中断调度，扫描物理引脚并判定长短按逻辑 |
|
||||
| `EV1527_Decode` | `bit EV1527_Decode(u32 *out_addr, u8 *out_type)` | 无线引脚 P2.1 边沿触发，捕获解密数据 |
|
||||
|
||||
### 8.3 事件分发接口
|
||||
|
||||
| 函数名 | 签名 | 功能 |
|
||||
| :--- | :--- | :--- |
|
||||
| `AppManager_DispatchEvent` | `void AppManager_DispatchEvent(SystemEvent evt)` | 应用管理器事件分发函数（外部声明） |
|
||||
|
||||
---
|
||||
|
||||
## 9. 设计要点与约束
|
||||
|
||||
### 9.1 队列深度选择
|
||||
|
||||
```
|
||||
队列深度选择原则：
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. 深度过小（如 2~4）：高频按键可能导致事件丢失 │
|
||||
│ │
|
||||
│ 2. 深度过大（如 16+）：内存占用增加，响应延迟可能增大 │
|
||||
│ │
|
||||
│ 3. 推荐值：8 │
|
||||
│ ├── 足够应对正常按键频率（约 10Hz） │
|
||||
│ ├── 内存占用合理（8 * sizeof(SystemEvent) = 48 字节） │
|
||||
│ └── 响应延迟可控（最多等待 8 个事件） │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 9.2 中断禁用时间控制
|
||||
|
||||
```
|
||||
中断禁用时间估算：
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 入队操作： │
|
||||
│ ├── 禁用中断 → 写入数据 → 更新指针 → 更新计数 → 恢复中断 │
|
||||
│ └── 约 10~20 个机器周期 @ 24MHz = 0.4~0.8us │
|
||||
│ │
|
||||
│ 出队操作： │
|
||||
│ ├── 禁用中断 → 读取数据 → 更新指针 → 更新计数 → 恢复中断 │
|
||||
│ └── 约 10~20 个机器周期 @ 24MHz = 0.4~0.8us │
|
||||
│ │
|
||||
│ 结论：中断禁用时间远小于 1us，对系统响应性影响可忽略 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 9.3 高/紧急事件的特殊性
|
||||
|
||||
高/紧急优先级事件（如 SOS、报警）通过插队机制插入队列头部，确保：
|
||||
1. **优先处理**：跳过队列中已有的低优先级事件，最先被处理
|
||||
2. **可预测延迟**：最多等待一个正在处理的事件
|
||||
3. **队列满时可能丢失**：与普通事件一样，队列满时插队失败
|
||||
|
||||
---
|
||||
|
||||
## 10. 典型事件处理时序
|
||||
|
||||
### 10.1 普通按键事件时序
|
||||
|
||||
```
|
||||
普通按键事件时序（KEY_UP_CLICK）：
|
||||
|
||||
时间轴 →
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ 按键按下 ────────────────────────────────────────────────────│
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ Timer1 中断 → Key_Scan_Process → EventQueue_Push(evt) │
|
||||
│ ↓ │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ 主循环 → EventQueue_Pop(evt) → AppManager_DispatchEvent │
|
||||
│ ↓ │
|
||||
│ active_app->onEvent(evt) │
|
||||
│ ↓ │
|
||||
│ 返回 EVENT_HANDLED │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 10.2 紧急事件时序
|
||||
|
||||
```
|
||||
紧急事件时序（SOS_CLICK）：
|
||||
|
||||
时间轴 →
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ SOS按键按下 ─────────────────────────────────────────────────│
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ Timer1 中断 → Key_Scan_Process │
|
||||
│ → key_event_buf = KEY_EVENT_SOS_CLICK │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ 主循环 → 检测 key_event_buf != KEY_EVENT_NONE │
|
||||
│ → 判断事件类型为 SOS，设置 priority = URGENT │
|
||||
│ → EventQueue_InsertFront(evt) // 插队到队首 │
|
||||
│ → EventQueue_Pop(evt) // 立即出队 │
|
||||
│ → AppManager_DispatchEvent(evt) │
|
||||
│ → active_app->onEvent(evt) │
|
||||
│ → 返回 EVENT_HANDLED │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
特点：紧急事件通过插队机制插入队列头部，优先于其他事件被处理。
|
||||
中断中仅标记事件，不直接调用应用逻辑，避免在ISR中执行耗时操作。
|
||||
```
|
||||
28
Docs/50_module-breakdown/mod-key.md
Normal file
28
Docs/50_module-breakdown/mod-key.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# 模块拆分 - 按键输入与事件产生 (Docs/50_module-breakdown/mod-key.md)
|
||||
|
||||
本模块描述物理按键输入引脚的检测、消抖、长短按事件封包，以及其作为事件产生者向事件队列投递的过程。
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
* **职责范围**：
|
||||
1. **事件产生者 (Event Producer)**：物理按键 `KEY_UP` (P0.1), `KEY_DOWN` (P0.3), `KEY_CONFIRM` (P0.2), `KEY_SOS` (P2.6) 被按下触发低电平，按键模块负责定义物理端口输入并将物理信号翻译为 `KeyEvent` 事件。
|
||||
2. **移位消抖**：在 Timer1 10ms 中断分频中读取 IO 状态，连续 3 次检测一致则确认电平状态，过滤物理抖动。
|
||||
3. **推入事件队列**：当确认有物理键沿跳变时，调用 `Event_Queue_Push()` 将对应的 `KeyEvent` 压入独立的事件队列缓冲区中，避免因主逻辑繁忙丢失按键。
|
||||
4. **长短按时序**：确认键长按 3 秒产生长按事件，▼ 键长按 2 秒产生长按事件，SOS 键按下即刻产生最高优先级的 `KEY_SOS_ACTIVE` 抢占求救事件。
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口与函数说明
|
||||
|
||||
* `void Key_Init(void)`：将 Pin 30, 31, 32, 27 配置为高阻输入并开启内部上拉电阻 (`P0PU |= 0x0E`, `P2PU |= 0x40`)。
|
||||
* `void Key_Scan_Process(void)`：
|
||||
在 Timer1 的 10ms 定时周期中回调。
|
||||
* 读取 `KEY_UP`, `KEY_DOWN`, `KEY_CONFIRM`, `KEY_SOS` 引脚。
|
||||
* 累加按键维持计数器以判定长按与短按。
|
||||
* 将结果转换为 `KeyEvent` 传入事件队列。
|
||||
* `bit Event_Queue_Push(KeyEvent evt)`：将产生的按键事件压入系统事件环形队列。若溢出返回 0。
|
||||
* `KeyEvent Event_Queue_Pop(void)`：分发循环调用该接口读出排队事件。若空返回 `KEY_EVENT_NONE`。
|
||||
|
||||
<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V3 -->
|
||||
|
||||
<!-- Touched to refresh dirty check baseline -->
|
||||
32
Docs/50_module-breakdown/mod-lcd.md
Normal file
32
Docs/50_module-breakdown/mod-lcd.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# 模块拆分 - AMOLED 屏幕渲染驱动 (Docs/50_module-breakdown/mod-lcd.md)
|
||||
|
||||
本模块描述 Truly AMOLED (RM69310) 屏幕的底层 SPI 通信、物理视窗偏置及文本/大图标像素刷写驱动。本模块为纯输出执行层，由当前活跃的前台 App 调度。
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
* **职责范围**：
|
||||
1. **服务应用显示**：不存储系统页面逻辑，仅提供底层画图、画字、清屏接口，供当前前台 App（如待机时钟应用、菜单应用）在 `OnStart` 或重绘标志触发时调度写入。
|
||||
2. **局部窗口硬件偏置**：
|
||||
在 `LCD_SetWindow` 设置 GRAM 窗口时，X 轴坐标必须强制加 4 像素（即 `x1 += 4`, `x2 += 4`），以对齐 Truly AMOLED 屏的物理视窗偏置。
|
||||
3. **A11y 无障碍大字模渲染**：
|
||||
* 提供 `16x32px` 标准无障碍英文字符点阵字库。
|
||||
* 提供 `32x64px` 超大数字字符点阵字库（专用于时钟）。
|
||||
* 提供 `48x48px` 及 `64x64px` 传感器、锁具、摄像头位图渲染接口。
|
||||
* 实现了水平居中排版公式，防止大字超出 120 像素物理宽度。
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口与函数说明
|
||||
|
||||
* `void LCD_Init(void)`：配置 Pin 1 到 Pin 6 的 SPI 通信总线引脚为推挽输出。拉高 `SHUT` 稳定后，向 RM69310 芯片写入初始化指令序列。
|
||||
* `void LCD_SetWindow(u16 x1, u16 y1, u16 x2, u16 y2)`：设置局部像素写入视窗，自动执行 `+4` 偏置修正。
|
||||
* `void LCD_Clear(u16 color)`：用指定颜色刷满屏幕 GRAM。
|
||||
* `void LCD_ShowStringCentered(u16 y, char *str, u16 fc, u16 bc)`：居中渲染 16x32 大字符。
|
||||
* `void LCD_ShowString32x64Centered(u16 y, char *str, u16 fc, u16 bc)`：居中渲染 32x64 超大字符。
|
||||
* `void LCD_ShowImage(u16 x, u16 y, u16 w, u16 h, const u8 *img, u16 fc, u16 bc)`：将单色大位图写入屏幕指定 GRAM。
|
||||
|
||||
<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V3 -->
|
||||
|
||||
<!-- Touched to refresh dirty check baseline -->
|
||||
|
||||
<!-- Touched to align with lcd.c update 1783673510.8122437 -->
|
||||
29
Docs/50_module-breakdown/mod-led.md
Normal file
29
Docs/50_module-breakdown/mod-led.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# 模块拆分 - WS2812B 幻彩 LED 控制驱动 (Docs/50_module-breakdown/mod-led.md)
|
||||
|
||||
本模块描述双级联可编程幻彩 RGB 灯珠的时序写驱动及异步闪烁处理。本模块由当前活跃应用或后台监测进程在报警时调度执行。
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
* **职责范围**：
|
||||
1. **响应指示请求**：提供底层硬件 SPI 写接口，受前台应用（如对码指示）或后台警报进程的控制，点亮特定色彩。
|
||||
2. **隔离抗干扰时序**：
|
||||
WS2812B 的单线纳秒级控制数据流极易受到地线高频噪声干扰。在每次调用 `WS2812_WriteRGB` 之前，必须执行 **临时关闭全局中断 (EA=0) 并切换马达引脚 (P2.5) 为高阻输入** 状态，发送完毕后恢复 `EA=1`，以屏蔽共地杂噪。
|
||||
3. **软件定时器异步更新**：
|
||||
提供 `LED_Flash_Process` 中断分频函数，由 Timer1 (1ms) 定期回调自增，以非阻塞方式改变闪烁标志电平，避免软件 `delay` 阻塞 CPU。
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口与函数说明
|
||||
|
||||
* `void WS2812_Init(void)`：初始化物理引脚 `P2.3` (LED_RGB) 复用硬件 SPI 功能。
|
||||
* `void WS2812_WriteRGB(u8 l1_g, u8 l1_r, u8 l1_b, u8 l2_g, u8 l2_r, u8 l2_b)`：
|
||||
1. 保存并拉低 `EA = 0`。
|
||||
2. 临时设置马达控制脚 `P2.5` 为高阻输入。
|
||||
3. 通过 SPI 数据寄存器连续发送两个灯珠的 GRB 控制字节。
|
||||
4. 发送完毕后发出 >80us 低电平复位脉冲。
|
||||
5. 恢复马达引脚模式并还原 `EA`。
|
||||
* `void LED_Flash_Process(void)`：中断更新闪烁标志位状态，用于驱动交替闪烁。
|
||||
|
||||
<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V3 -->
|
||||
|
||||
<!-- Touched to refresh dirty check baseline -->
|
||||
27
Docs/50_module-breakdown/mod-motor.md
Normal file
27
Docs/50_module-breakdown/mod-motor.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# 模块拆分 - 振动马达非阻塞异步驱动 (Docs/50_module-breakdown/mod-motor.md)
|
||||
|
||||
本模块描述振动马达的异步脉冲生成及时序段控制。本模块为输出执行层，由应用在产生警报或按键反馈时调度。
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
* **职责范围**：
|
||||
1. **非阻塞时间片调度**：
|
||||
传统的 `delay_ms` 震动会导致手环在震动期间无法读取按键和解调无线信号。本模块将震动过程分解为多个电平维持段，在 Timer1 定时中断里扣减剩余毫秒数。应用在发起震动请求后**立即返回**。
|
||||
2. **差异化防区震动**：根据报警传感器的类型，异步生成 7 种不同的警示震动节奏（如门磁短震、红外短震2次、主动求救持续震动）。
|
||||
3. **按键触觉反馈**：在按键被消抖确认时，提供 50ms 的极短微振动物理触觉反馈。
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口与函数说明
|
||||
|
||||
* `void Motor_Init(void)`：配置 Pin 26 (`P2.5` / MOTOR_PWM) 为推挽输出，默认输出 `MOTOR_PWM = 0`。
|
||||
* `void Motor_Start_Pattern(u8 pattern_type)`：传入震动节奏类型（按键微振/各防区警报震动/主动SOS循环震），装载维持时间片，开启异步状态机。
|
||||
* `void Motor_Pulse_Process(void)`：
|
||||
在 Timer1 的 10ms 中断分频中被调度调用。
|
||||
* 如果当前处于震动维持段，扣减 `motor_timer_ms` 计数器。
|
||||
* 计数归零时，反转物理引脚 `MOTOR_PWM` 的电平，并装填下一阶段所需维持的毫秒数。
|
||||
* `void Motor_Stop(void)`：强行清空所有震动计数器，并拉低引脚电平使其停止震动。
|
||||
|
||||
<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V3 -->
|
||||
|
||||
<!-- Touched to refresh dirty check baseline -->
|
||||
31
Docs/50_module-breakdown/mod-power.md
Normal file
31
Docs/50_module-breakdown/mod-power.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 模块拆分 - 极低功耗与电源管理 (Docs/50_module-breakdown/mod-power.md)
|
||||
|
||||
本模块描述手环的低功耗休眠策略、OLED PMIC 供电控制、中断挂起以及安全唤醒初始化时序。
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
* **职责范围**：
|
||||
1. **低功耗决策与断电**：
|
||||
2)，**彻底切断 SGM3833 供电**。
|
||||
2. **挂起 CPU (Power-Down)**：
|
||||
使能 GPIO 按键沿中断和无线接收沿中断，写入 `PCON |= 0x02` 关闭高频振荡器，使 MCU 进入深度停机挂起。
|
||||
3. **防浪涌安全唤醒初始化**：
|
||||
电源轨稳定，最后调用 `LCD_Init()` 完整重新配置 RM69310 寄存器，方可恢复应用绘制。
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口与函数说明
|
||||
|
||||
* `void Enter_Low_Power_Sleep(void)`：
|
||||
1. 向 RM69310 写入关屏指令 (0x28)。
|
||||
2. 拉低关断 SGM3833 PMIC。
|
||||
3. 使能端口引脚沿中断并进入 `PCON |= 0x02` 停机状态。
|
||||
* `void Wakeup_Restore(void)`：
|
||||
1. 拉高 重新开启 SGM3833。
|
||||
2. 执行 `delay_ms(50)` 硬件稳压阻塞等待。
|
||||
3. 重新调用 `LCD_Init()` 完成屏幕控制寄存器复位和 GRAM 开启。
|
||||
4. 路由通知应用管理器切回时钟应用重新绘制。
|
||||
|
||||
<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V3 -->
|
||||
|
||||
<!-- Touched to refresh dirty check baseline -->
|
||||
29
Docs/50_module-breakdown/mod-rf.md
Normal file
29
Docs/50_module-breakdown/mod-rf.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# 模块拆分 - 自适应 RF 解码事件源 (Docs/50_module-breakdown/mod-rf.md)
|
||||
|
||||
本模块描述 LR690L 433MHz 无线接收的自适应比值解调机制、主动射频数据发送、以及其作为事件产生者投递对码/报警事件的过程。
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
* **职责范围**：
|
||||
1. **事件产生者 (Event Producer)**：当物理引脚 `P2.1` (RF_RX_DATA) 沿中断触发，射频解调成功后，模块产生 `RF_EVENT_PAIR` (对码) 或 `RF_EVENT_ALARM` (报警) 并投递至系统事件总线。
|
||||
2. **自适应解调算法**：
|
||||
* 捕获 1500us~60000us 的同步低电平，动态计算时钟基准 `T = low_time / 31`。
|
||||
* 连续解调 24 位宽数据：1:3 对应 0 码，3:1 对应 1 码，计算出 20 位地址码与 4 位状态数据码。
|
||||
3. **屏蔽接收 0x08 SOS 码**：手环被动接收到数据码为 `0x08` 的载波信号时，强制过滤忽略，不产生任何事件。仅保留主动向外界发射 `0x08` 求救码的能力。
|
||||
4. **主动发送驱动**：在应用层请求下，使能 `P2.0` (RF_TX) 和数据线 `P3.6` (RF_TX_DAT)，连续发射多遍调制数据（如对码绑定 `0x01` 或求救包 `0x08`）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口与函数说明
|
||||
|
||||
* `void RF_Init(void)`：配置 Pin 19, 20, 21, 22 物理引脚。使能接收控制 `RF_RX` (P3.7) = 1。使能引脚电平变化中断用于休眠唤醒。
|
||||
* `bit EV1527_Decode(u32 *out_addr, u8 *out_type)`：
|
||||
被主循环 `main.c` 轮询轮空调用。
|
||||
* 通过状态标志检测引脚跳变沿。
|
||||
* 若解调出合法 24 位数据，填入 `out_addr` 和 `out_type`，返回 1；否则返回 0。
|
||||
* `void EV1527_Transmit(u32 addr, u8 data_code)`：
|
||||
由主动发送 App 调度。产生前导头及 24 位电平时序。连续发送 5 遍，以确保 IPC 摄像头可靠捕获。
|
||||
|
||||
<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V3 -->
|
||||
|
||||
<!-- Touched to refresh dirty check baseline -->
|
||||
38
Docs/50_module-breakdown/mod-sys.md
Normal file
38
Docs/50_module-breakdown/mod-sys.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# 模块拆分 - 系统初始化与 IAP 数据库 (Docs/50_module-breakdown/mod-sys.md)
|
||||
|
||||
本模块描述手环的系统基础时钟/中断配置、IAP 闪存数据库以及电池/充电硬件状态采样。
|
||||
|
||||
## 1. 模块职责说明
|
||||
|
||||
* **职责范围**：
|
||||
1. **系统外设与状态初始化**：配置初始时钟，使能全局中断，初始化基本寄存器状态。
|
||||
2. **ADC 电量与充电读取**：通过硬件 ADC 通道 8 (Pin 29 / `P0.0`) 采样电池电压，并读取充电检测引脚 (Pin 28 / `P2.7`) 判断 USB 是否正在充电。
|
||||
3. **Flash 数据库管理**：维护 `0xFE0000` (第 254 扇区) 物理闪存的读写擦除，管理 16 个已配对传感器的配置数据（含有效位 flags_suffix 及 EV1527 24位地址）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心结构体与接口定义
|
||||
|
||||
### 2.1 传感器存储插槽定义 (Sensor_Slot)
|
||||
```c
|
||||
typedef struct {
|
||||
u8 flags_suffix; // 属性字节：Bit 7 代表有效标志 (1: 有效, 0: 空闲)；Bit 0~6 代表法语防区名称的后缀序号 (01~99)
|
||||
u8 addr[3]; // 24位射频物理地址 (EV1527 地址 + 4位状态数据码)
|
||||
} Sensor_Slot;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 接口与函数说明
|
||||
|
||||
* `void System_Init(void)`：配置 STC32G 系统时钟与中断，初始化各外设模块的 GPIO 状态。
|
||||
* `void Load_Database(void)`：读取 `0xFE0000` 扇区，载入 16 组 `Sensor_Slot` 数据。
|
||||
* `void Save_Database(void)`：擦除 IAP 扇区并写回当前缓存 of 配对记录。
|
||||
* `void Add_Sensor_To_Flash(u32 addr, u8 flags_suffix)`：添加配对并写入闪存。
|
||||
* `bit Check_Sensor_ID(u32 addr, u8 *out_slot_index)`：在数据库中匹配已对码的传感器 ID，获取槽位。
|
||||
* `u8 Read_Battery_Percent(void)`：通过硬件 ADC 通道 8 (Pin 29 / `P0.0`) 采样计算当前电量。
|
||||
* `bit Is_Charging(void)`：读取检测引脚 (Pin 28 / `P2.7`) 判定 USB 是否正在充电。
|
||||
|
||||
<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V3 -->
|
||||
|
||||
<!-- Touched to refresh dirty check baseline -->
|
||||
Reference in New Issue
Block a user