battery_upgrade.h
源文件路径：
midware/bms/alpha/battery_upgrade.h所属模块：midware / bms / alpha（ALPHAESS 自有电池固件 CAN 升级头文件） 代码行数：21
1. 文件职责
本文件是 battery_upgrade.c 的对外契约，只做三件事：给出防止重复包含的宏、定义升级调试打印开关 BMS_UPGRADE_DEBUG、声明电池固件升级状态机的三个对外函数。
它把"电池固件升级"这一能力以极简接口暴露给上层：一个驱动入口（每个任务周期调用一次，推进状态机）、两个进度查询接口（分别给云平台上报和给 LCD/Modbus 显示）。
本文件不含任何数据结构、状态枚举或 CAN 协议宏——这些全部被封装在 battery_upgrade.c 内部（BATTER_UPGRADE_STATUS_E、BATTER_UPGRADE_TAB_T 均为 .c 私有的文件级定义），因此对调用方而言升级过程完全是黑盒。
2. 关键数据结构与宏
| 名称 | 类型(结构体/枚举/宏/联合体) | 说明 |
|---|---|---|
__BATTERY_UPGRADE_H__ | 宏 | 头文件卫士（battery_upgrade.h:9-10），防止重复包含 |
BMS_UPGRADE_DEBUG | 宏 | 升级调试打印总开关，值 0（battery_upgrade.h:14）。控制 battery_upgrade.c 中约 20 处 #if BMS_UPGRADE_DEBUG 调试块（"timeout"、"no data"、"address err"、"recv ok"、各阶段失败点等） |
includes.h | 头文件 | 由本文件包含（battery_upgrade.h:12），提供 u8/u32 等基本类型与工程全局声明 |
本文件不定义任何结构体、枚举、联合体或位域。升级状态枚举 BATTER_UPGRADE_STATUS_E 与升级上下文结构体 BATTER_UPGRADE_TAB_T 都定义在 battery_upgrade.c:25 / battery_upgrade.c:36，属于该编译单元的私有实现细节，外部不可见。
3. 函数清单
本文件（.h）只包含函数声明，不含函数定义。全部内容即 3 个原型：
| 函数名 | 作用域 | 说明 |
|---|---|---|
households_batter_upgrade_handle(u8 hardware_platform) | 全局声明（battery_upgrade.h:16），实现于 battery_upgrade.c:551 | 升级状态机主入口。入参是 BMS 硬件平台（BMS_48V/BMS_HV，由 get_bms_hardware_platform() 返回）；每次调用推进一步，无返回值（结果通过状态复位与 Set_Status_Is_Updated_From_Server(UPDT_BMS, FALSE) 对外体现） |
GetPercentUpgradeBMS(void) | 全局声明（battery_upgrade.h:17），实现于 battery_upgrade.c:782 | 返回升级百分比（u8，0~100），内部为 Get_Idx_Updt_BMS_Loacl() * 100 / get_length_file_updating(UPDT_BMS) |
Get_Idx_Updt_BMS_Loacl(void) | 全局声明（battery_upgrade.h:18），实现于 battery_upgrade.c:771 | 返回当前已解析的固件文件字节偏移（u32），用作断点/进度上报 |
注：头文件注释块（battery_upgrade.h:7-8）中函数名的书写与实现处的注释（battery_upgrade.c:761 写的是 void Get_Idx_Updt_BMS_Loacl(BOOLEAN set)）不一致——实现处带了一个并不存在的 BOOLEAN set 参数，实际原型是无参的 u32 Get_Idx_Updt_BMS_Loacl(void)。
4. 核心逻辑解析
本文件为纯声明文件，不含状态机、算法、协议帧格式或定时逻辑。以下说明它的"契约"层面要点：
4.1 接口面刻意收窄
升级流程涉及 6 个状态、4 类 CAN 帧、S19 解析、CRC 累加等大量内部细节，但对外只暴露 3 个函数，且：
- 没有"启动升级"接口。升级的触发权不在本模块，而在更新框架：由云平台/服务器置位
UPDT_BMS更新标志，再由task_bms通过Get_Status_Is_Updated_From_Server(UPDT_BMS)（net/upd_download.h:40）查询。households_batter_upgrade_handle()只是"被驱动的推进器"，不判断该不该升级。 - 没有"取消升级"接口。中止只能通过
households_batter_upgrade_handle()内部状态机走到UPGRADE_INFO_INIT时自行调用Set_Status_Is_Updated_From_Server(UPDT_BMS, FALSE)（battery_upgrade.c:751）完成。 - 没有"是否正在升级"的查询接口。其它模块只能通过
Get_Status_Is_Updated_From_Server(UPDT_BMS)间接判断（net/ems.c:6697就是这么做的）。
4.2 与 uCOS-II 的配合
头文件本身不涉及任务、信号量或消息邮箱。唯一的约定是调用频率：由于状态机每调用一次只推进一步（SEND_UPGRADE_DATA 每次只烧写一行 S19），调用方必须按任务周期高频调用。实际调用点 midware/bms/bms.c:2762 位于 task_bms 主循环的升级分支内，每轮循环调用一次，之后 OSTimeDlyHMSM(0,0,0,10) 让出 10ms。
4.3 调试开关的作用范围
BMS_UPGRADE_DEBUG 只在 battery_upgrade.c 中生效（.c:14 通过 #include "battery_upgrade.h" 获得）。开启后会打印 5 个内部发送函数的超时/无数据/地址错误/接收成功等信息，是排查升级失败的主要手段。默认值为 0，即量产固件中没有任何升级过程日志。
5. 对外接口
5.1 本文件导出（供外部调用）
| 导出类别 | 内容 | 使用方 |
|---|---|---|
| 宏 | BMS_UPGRADE_DEBUG | 仅 battery_upgrade.c |
| 函数原型 | households_batter_upgrade_handle、GetPercentUpgradeBMS、Get_Idx_Updt_BMS_Loacl | midware/bms/bms.c、net/ems.c、midware/interface/modbus/modbus.c、hmi/ui/ui_main.c |
| 类型 | 无 | — |
| 全局变量 | 无 | — |
5.2 本文件引用的外部内容
| 来源 | 内容 |
|---|---|
includes.h（battery_upgrade.h:12） | 基本类型 u8/u32，以及工程范围内的全部公共头文件 |
6. 依赖关系
依赖
#include <includes.h> // battery_upgrade.h:12被依赖
| 文件 | 行号 | 说明 |
|---|---|---|
midware/bms/alpha/battery_upgrade.c | :13 | 实现文件，#include "battery_upgrade.h" |
midware/bms/bms.c | :15 | #include "battery_upgrade.h"，task_bms 中调用 households_batter_upgrade_handle()（bms.c:2762） |
net/ems.c | :53 | #include "battery_upgrade.h"，读取 Get_Idx_Updt_BMS_Loacl()（ems.c:6697） |
midware/interface/modbus/modbus.c | :36 | #include "battery_upgrade.h"，读取 GetPercentUpgradeBMS()（modbus.c:9385,9429,9462） |
hmi/ui/ui_main.c | :26 | #include "battery_upgrade.h"，LCD 显示升级百分比（ui_main.c:859） |
7. 备注与风险点
- 头文件注释与实现签名不符（
battery_upgrade.h:7-8对比battery_upgrade.c:761）：.c的注释写void Get_Idx_Updt_BMS_Loacl(BOOLEAN set)，实际实现是u32 Get_Idx_Updt_BMS_Loacl(void)。BOOLEAN类型在工程其它位置（如data/resume_data/flash/flash_data_store.c:80）确有使用，但本函数实际并不接收参数、也不返回void，属从旧版本复制后未同步的注释。
GetPercentUpgradeBMS()的返回类型是u8且存在除零风险（.c:782-785）：分母get_length_file_updating(UPDT_BMS)若为 0 会触发运算异常；该接口被 LCD 与 Modbus 无条件周期调用，不限于升级期间。头文件未对此做任何约定或保护封装。
Get_Idx_Updt_BMS_Loacl()的命名含拼写错误：Loacl应为Local。由于是已发布的对外符号，改名会牵动 4 个调用文件，属于"错别字固化为接口"的典型版本遗留。
BMS_UPGRADE_DEBUG缺少括号包裹习惯上的不一致：.c中既有#if BMS_UPGRADE_DEBUG（如.c:140）也有#if (DEBUG_…) == 1风格；本文件定义的是0而非(0)，虽然#if下两者等价，但与同目录battery_comm.h:17的#define DEBUG_ALPHA_BAT (0)写法不统一。
#include <includes.h>使用尖括号（battery_upgrade.h:12）：与同目录battery_comm.h:13的#include <includes.h>一致，但与battery_upgrade.c中对本地头文件用双引号（.c:13-23）形成混用。工程能正常构建（Keil 的 include 搜索路径同时覆盖），属风格问题。
- 接口无版本/兼容性声明：三个函数都没有参数校验约定（例如
hardware_platform传入非法值时households_batter_upgrade_handle()会直接进入UPGRADE_INFO_INIT中止升级，.c:558-561），头文件对此行为零说明，调用方无法从接口看出"传错值会导致升级被放弃"。