首页 / knowledge/代码解析/net

bms_download.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 两个相近名字的语义边界 4.2 返回值约定 4.3 通信协议 / 定时 / uCOS-II 5. 对外接口 6. 依赖关系 7. 备注与风险点

源文件路径：net/bms_download.h 所属模块：net（网络应用层 / 设备固件升级下载）代码行数：21

1. 文件职责

本文件是 net/bms_download.c 的对外接口头文件，声明 BMS（电池管理系统）固件升级状态查询接口，供 HMI、云端上报、逆变器通信、Modbus 等模块读取“BMS 是否正在被云端强制下载”“BMS 固件是否已下载完成”“下载进度”以及 BMS 软件版本。

它在数据流中处于「BMS 升级状态标志的只读出口」位置：写侧全部在 net/server.c 与 net/upd_download.c，读侧通过本头文件拿到 3 个已实现的原型。

本文件不含逻辑与状态，只含 include guard、一个 include 和 5 个函数原型——其中 2 个在工程中没有对应实现（见第 3、7 节）。

2. 关键数据结构与宏

名称	类型	说明
`__BMS_DOWNLOAD_H__`	宏	include guard（第 9-10 行）
`Get_BMS_Ver_From_Server`	函数原型	`char Get_BMS_Ver_From_Server(void)`，工程内无定义*（见第 7 节备注 1）
`Set_Status_Is_Updated_BMS_From_Server`	函数原型	`void Set_Status_Is_Updated_BMS_From_Server(u8 bSet)`，工程内无定义
`IsDownloadBMS`	函数原型	`u8 IsDownloadBMS(void)`，定义于 `bms_download.c:36`
`GetPercentDownloadBMS`	函数原型	`u8 GetPercentDownloadBMS(void)`，定义于 `bms_download.c:58`
`IsUpgradeBMS`	函数原型	`u8 IsUpgradeBMS(void)`，定义于 `bms_download.c:47`

本文件不定义结构体、枚举、联合体、位域，也没有除 include guard 外的宏常量。u8 来自第 12 行 #include <includes.h>。

原型声明顺序（Get_BMS_Ver_From_Server → Set_Status_...BMS_From_Server → IsDownloadBMS → GetPercentDownloadBMS → IsUpgradeBMS）与 bms_download.c 中的定义顺序（IsDownloadBMS → IsUpgradeBMS → GetPercentDownloadBMS）不同，进一步佐证前两个是本文件保留的旧接口残留。

3. 函数清单

函数名	作用域	说明
`Get_BMS_Ver_From_Server`	全局（原型声明）	语义应为“取服务器下发的 BMS 版本”，全工程无定义、无调用点，属死声明
`Set_Status_Is_Updated_BMS_From_Server`	全局（原型声明）	语义应为“置位 BMS 已更新标志”，全工程无定义、无调用点，已被通用接口 `Set_Status_Is_Updated_From_Server(UPDT_BMS, ...)` 取代
`IsDownloadBMS`	全局（原型声明）	查询云端是否要求强制下载 BMS 固件，定义于 `bms_download.c:36`
`GetPercentDownloadBMS`	全局（原型声明）	查询 BMS 固件下载百分比（0~100），定义于 `bms_download.c:58`
`IsUpgradeBMS`	全局（原型声明）	查询 BMS 固件是否已完成从服务器的更新（MD5 已校验通过），定义于 `bms_download.c:47`

共 5 个原型声明：3 个有实现、2 个无实现。无 static 函数、无函数指针、无回调、无宏函数。

4. 核心逻辑解析

本文件是纯声明文件，不含可执行逻辑。接口契约要点：

4.1 两个相近名字的语义边界

IsDownloadBMS() 与 IsUpgradeBMS() 是使用方最容易混淆的一对，头文件中没有任何注释区分它们。依据 bms_download.c 的实现与 net/server.c 的写侧：

接口	读取字段	语义	置位时机
`IsDownloadBMS()`	`stUpt[UPDT_BMS].bIsUpdateForce`	云端要求下载，下载进行中	`net/server.c:2408`（仅强制升级）
`IsUpgradeBMS()`	`stUpt[UPDT_BMS].bIsUpdatedFromServer`	固件已下载并 MD5 校验通过	`net/upd_download.c:412`

关键细节：net/server.c:2410-2411 明确写明，对 UPDT_BMS / UPDT_EVC / UPDT_INV3 三种类型，非强制升级时会把 IsDownloadBMS() 对应的标志清零，因此这三个设备主要靠 IsUpgradeBMS() 驱动后续刷写。

4.2 返回值约定

两个布尔接口返回 u8，取值仅 0 / 1（底层 BOOLEAN 提升）。
GetPercentDownloadBMS() 返回 u8，语义 0~100；分母 u32LenFile 在文件信息到达前为 0，存在除零窗口（详见 bms_download.c.md 备注 1）。

4.3 通信协议 / 定时 / uCOS-II

均不涉及。本文件不定义帧格式、起始码、校验、超时与重试参数，不声明信号量、消息邮箱或任务，不引用 uCOS-II API。所声明的函数由调用方在自己的任务上下文同步调用。

5. 对外接口

导出（供外部使用）：

名称	使用方
`IsDownloadBMS`	`hmi/ui/ui_main.c:844`、`net/ems_download.c:254`
`GetPercentDownloadBMS`	`hmi/ui/ui_main.c:850`、`midware/bms/bms.c:3280`、`:3307`、`midware/inverter/parallel.c:261`、`midware/inverter/pvcharger.c:49`
`IsUpgradeBMS`	`hmi/ui/ui_main.c:853`、`midware/interface/modbus/modbus.c:9379`、`midware/inverter/ginlong/ginlong_comm_usart.c:4363/4370/4378/4397/4748/4759/4830/5156`、`midware/inverter/kelong/kelong_comm.c:2203`
`Get_BMS_Ver_From_Server`	无（无定义、无调用）
`Set_Status_Is_Updated_BMS_From_Server`	无（无定义、无调用）

被调用（本文件引用的外部符号）：

名称	来源
`includes.h`	第 12 行 `#include <includes.h>`，提供 `u8` 等基础类型，并间接引入 uCOS-II 与 GD32 头文件

本文件不导出全局变量，也不引用外部全局变量。

6. 依赖关系

依赖：

UCOSII/uCOS-CONFIG/includes.h（第 12 行，尖括号形式）——唯一依赖，只用于取得基础类型；
不依赖 ems.h / server.h / upd_download.h，引入成本极低。

被依赖（include 本头文件的文件，共 13 处）：

net/bms_download.c:14、net/ems.c:19、net/ems_download.c:18、net/server.c:21
hmi/ui/ui_main.c:23
midware/bms/bms.c:21、midware/bms/alpha/battery_upgrade.c:16
midware/interface/modbus/modbus.c:33
midware/inverter/parallel.c:21、midware/inverter/pvcharger.c:17
midware/inverter/alphaess/alphaess_comm_usart.c:27、midware/inverter/ginlong/ginlong_comm_usart.c:24、midware/inverter/inovance/inovance_comm_can.c:11、midware/inverter/kelong/kelong_comm.c:23

7. 备注与风险点

有 2 个原型没有实现：Get_BMS_Ver_From_Server() 与 Set_Status_Is_Updated_BMS_From_Server() 在 net/bms_download.c 及全工程任何 .c 中都找不到定义，也没有任何调用点（grep -rn 全项目仅命中本头文件的两行）。任何未来的调用方一旦使用它们，会在链接期报未解析符号。BMS 版本信息当前实际由 midware/bms/bms.h:1210 的 bms_read_hard_version() 提供（net/ems.c:2975 使用），因此这两个声明属于废弃接口，应当删除。
文件头 @file 与真实文件名不符：第 2 行写 BMSUpdate.h，实际文件名为 bms_download.h；@date 为 2017/05/18，是 bms / evc / inv / meter 四个 download 文件的共用历史日期。按文件名检索接口时会漏掉本文件。
@author 写成 Alpha g_stEMSInfo Team（第 3 行）：与 bms_download.c 的 Alpha EMS Team 不一致，推测是历史上把标识符 EMS 批量替换为 g_stEMSInfo 时误改了注释。
缺少接口注释：IsDownloadBMS() 与 IsUpgradeBMS() 语义差异大但头文件无任何说明，调用方极易写反（HMI 的“Download BMS FW”与“upgrade BMS”两种文案就分别依赖这两个接口，见 hmi/ui/ui_main.c:844、:853）。
u8 作为版本字符串类型不适用：Set_Status_Is_Updated_BMS_From_Server(u8 bSet) 的参数语义是布尔，却用 u8；而通用的 Set_Status_Is_Updated_From_Server（upd_download.h:39）与 set_flag_force_update（upd_download.h:25）用的是 BOOLEAN。类型风格混用是历史遗留。