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/马达状态输出）
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user