Initial commit: CCU621_M firmware project with BLE debug link support.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,161 @@
|
||||
# UI 模块说明（CCU621_M）
|
||||
|
||||
> 路径：`app/ui/`
|
||||
> 返回主说明：[README](../../README.md)
|
||||
|
||||
## 1. 模块定位
|
||||
|
||||
`app/ui` 是整机的人机交互中枢，负责把“系统状态”转换为“屏幕可视化结果”，并把“屏幕触控/输入”转换为“系统控制动作”。
|
||||
|
||||
核心职责分为四类：
|
||||
|
||||
- 通信层：与迪文屏进行串口协议收发；
|
||||
- 交互层：触控事件解析、输入字符串解析；
|
||||
- 状态机层：页面跳转、页面生命周期、超时返回；
|
||||
- 数据适配层：把业务数据统一封装给 UI（`ui_interface.c`）。
|
||||
|
||||
## 2. 代码结构与职责划分
|
||||
|
||||
- `ui_task.c/.h`
|
||||
- UI 主任务入口；
|
||||
- 页面状态机（当前页面判断、页面切换触发）；
|
||||
- 页面显示刷新调度（按 1s/首次进入/事件触发刷新）；
|
||||
- 看门狗喂狗和通信超时检测。
|
||||
|
||||
- `ui_comm_impl.c/.h`
|
||||
- 迪文协议封包/解包；
|
||||
- 控制寄存器与数据寄存器读写；
|
||||
- 字符串显示下发、动画图标下发；
|
||||
- 参数区块镜像管理与屏幕写回。
|
||||
|
||||
- `ui_interface.c/.h`
|
||||
- 提供统一的“取数/控数”接口；
|
||||
- 屏蔽底层模块差异（流程、BMS、计量、平台）；
|
||||
- 当前版本承担 `CCU621_M` 兼容层职能（部分数据默认值策略）。
|
||||
|
||||
- `ui_info.c/.h`
|
||||
- 页面文案资源（中文/英文）；
|
||||
- 故障文本辅助转换；
|
||||
- UI 显示固定字符串资源。
|
||||
|
||||
## 3. UI 主流程（任务周期）
|
||||
|
||||
`v_ui_task()` 一个周期内的关键步骤：
|
||||
|
||||
调度信息（来自 `app/app_init/app_init.c`）：
|
||||
|
||||
- `UiComm`：`100ms` 周期（任务入口：`v_ui_task(void *argument)`）
|
||||
|
||||
1. 看门狗喂狗；
|
||||
2. 读取并解包屏幕报文（触控、字符串、变量写入）；
|
||||
3. 执行页面切换控制（当前页校验 + 目标页下发）；
|
||||
4. 执行当前页面刷新逻辑（按页面类型调用对应显示函数）；
|
||||
5. 更新通信超时计数并上报状态；
|
||||
6. 睡眠等待下个周期。
|
||||
|
||||
设计目标是将“通信、状态机、显示逻辑”解耦，便于后续替换业务数据源而不影响页面框架。
|
||||
|
||||
## 4. 多语言界面实现逻辑
|
||||
|
||||
多语言由两个层次实现：
|
||||
|
||||
- 页面资源映射层（页面ID -> 屏幕图片ID）
|
||||
- 每个逻辑页面 `E_UI_ID_TYPE` 在映射表里有多套语言图片索引；
|
||||
- 通过 `u8_lalanguage_type` 选择对应语言图片并下发；
|
||||
- 切语言时不改页面状态机，只改映射结果。
|
||||
|
||||
- 动态文本层（实时字符串）
|
||||
- 实时流程文案、状态文本通过 `ui_info.c` 的字符串表输出；
|
||||
- 同一个寄存器地址可按语言写入不同字符串；
|
||||
- 对于长度变化文本，先清空再写入，防止残留字符。
|
||||
|
||||
当前默认使用中/英两套资源，后续可按同一模式扩展第三语言。
|
||||
|
||||
## 5. 页面跳转状态机设计
|
||||
|
||||
页面切换由“被动跳转 + 主动跳转”共同驱动：
|
||||
|
||||
- 被动跳转（用户输入）
|
||||
- 触控按钮（开始、停止、返回、上一页、下一页等）；
|
||||
- 字符串输入（维护密码、管理员密码、确认动作密码等）。
|
||||
|
||||
- 主动跳转（系统状态变化）
|
||||
- 空闲 -> 启动中 -> 充电中 -> 停止中 -> 结算；
|
||||
- 故障触发 -> 故障页面；
|
||||
- 升级标志触发 -> 升级页面；
|
||||
- 空闲超时 -> 屏保/首页。
|
||||
|
||||
状态机关键变量：
|
||||
|
||||
- `e_set_pic_id`：目标逻辑页面；
|
||||
- `u8_ret_pic_id`：屏幕当前页面ID回读值；
|
||||
- `e_previous_id`：上一页面（用于返回）；
|
||||
- `u8_first_jump`：首次进入页面标志（用于首次刷新）。
|
||||
|
||||
## 6. 主要页面显示内容（摘要）
|
||||
|
||||
- 待机页
|
||||
- 二维码、联网图标、枪状态、桩号；
|
||||
- 双枪/单枪根据配置和工作状态动态切换页面。
|
||||
|
||||
- 启动中页
|
||||
- 当前流程阶段文本；
|
||||
- 倒计时；
|
||||
- 达到充电状态后自动转实时页。
|
||||
|
||||
- 充电实时页
|
||||
- 电压、电流、电量/功率、金额、时长、SOC；
|
||||
- 支持切换到电池信息页和停止操作。
|
||||
|
||||
- 电池信息页
|
||||
- 电池类型/容量、需求电压电流、额定上限等；
|
||||
- 不同语言模式可展示不同字段重点。
|
||||
|
||||
- 停止中/结算页
|
||||
- 停止倒计时、订单结算信息、停止原因；
|
||||
- 支持返回待机。
|
||||
|
||||
- 维护相关页
|
||||
- 参数分类配置（系统/保护/网络/模块/预留/其他）；
|
||||
- 历史告警分页、历史充电记录分页；
|
||||
- 操作确认页（保存参数/参数初始化/系统重启）。
|
||||
|
||||
## 7. 参数配置区块设计
|
||||
|
||||
参数按寄存器区块管理：
|
||||
|
||||
- `0x0200` 系统参数；
|
||||
- `0x0220` 保护参数；
|
||||
- `0x0240` 网络参数；
|
||||
- `0x0260` 模块参数；
|
||||
- `0x0280` 预留参数。
|
||||
|
||||
读写策略：
|
||||
|
||||
- “进入页面”时：从共享配置初始化 UI 参数镜像并下发到屏；
|
||||
- “屏幕修改”时：回写参数镜像；
|
||||
- “确认保存”时：镜像写回系统配置并持久化。
|
||||
|
||||
字符串参数（桩号、域名、二维码、APN）单独按地址映射回写，避免和数值参数混用。
|
||||
|
||||
## 8. 当前兼容策略（CCU621_M 过渡期）
|
||||
|
||||
由于 `CCU621_M` 业务模块未完全对齐旧项目，`ui_interface.c` 使用了默认策略：
|
||||
|
||||
- 部分运行时数据（流程/BMS/计量/平台状态）临时返回默认值；
|
||||
- 控制接口先占位（记录启动方式，不直接驱动底层流程）；
|
||||
- 历史记录接口返回空结果并给固定提示文案；
|
||||
- 可直接映射的固定参数与字符串（桩号、域名、密码、二维码、APN）已接入共享配置。
|
||||
|
||||
该策略目标是“先保障界面框架稳定可联调”，后续逐项替换默认值。
|
||||
|
||||
## 9. 后续对接建议（优先级）
|
||||
|
||||
建议按以下顺序接入真实业务能力：
|
||||
|
||||
1. 流程状态与启停控制；
|
||||
2. 电表/计量实时数据与订单结算数据；
|
||||
3. BMS 数据；
|
||||
4. 平台在线/升级/禁用状态；
|
||||
5. 历史故障与历史订单分页读取；
|
||||
6. 通信超时与故障上报闭环。
|
||||
Reference in New Issue
Block a user