EMS 知识库
首页 / knowledge/代码解析/midware/bms/alpha

battery_comm.h

源文件路径:midware/bms/alpha/battery_comm.h 所属模块:midware / bms / alpha(ALPHAESS 自有电池 CAN 通信协议头文件) 代码行数:424

1. 文件职责

本文件是 battery_comm.c 的对外契约,也是整份 ALPHAESS 电池 CAN 协议的寄存器/命令字映射表。它用宏的形式把协议里几十组 CAN 扩展帧 ID 全部命名化,供 battery_comm.c 的解析 switch 与组帧函数使用。

除了 ID 宏,文件还声明了 3 个枚举、2 个结构体(电池日志相关)以及 battery_comm.c 导出的全部下行指令与状态查询函数原型。midware/bms/bms.c、net/ems.c 通过包含本文件来调用电池命令接口。

本文件不包含任何可执行代码,只定义类型、宏和原型,是纯粹的数据流"接口描述层"。

2. 关键数据结构与宏

2.1 调试开关宏

名称类型说明
DEBUG_ALPHA_BAT宏电池协议调试打印总开关,值 0(battery_comm.h:17),控制 battery_comm.c 中约 40 处 #if 调试块
DEBUG_ALPHA_MAX_AH宏SOC 算法最大容量(需求 1)上报调试开关,值 0(:18)
DEBUG_ALPHA_BAT_CLUSTER宏串并联簇信息(需求 5)调试开关,值 0(:19)
DEBUG_ALPHA_BAT_ERR_ALARM宏电池告警/错误调试开关,值 0(:20),本文件与 .c 中均未被引用

2.2 各型号电池截止电压宏(.c 未直接使用,供 bms.c 的截止电压处理使用)

名称类型说明
ALPHA_M4850_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5760 / 4800(单位 0.01V)
ALPHA_M4860_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5760 / 4800
ALPHA_M48100_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5400 / 4500
ALPHA_M48112_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5400 / 4500
ALPHA_SMILE5_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5760 / 4800
ALPHA_M4856_P_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5760 / 4800
ALPHA_SMILE10_3_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5760 / 4800
ALPHA_SMILE10_1_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5400 / 4500
ALPHA_SMILE5_8_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5400 / 4500
ALPHA_SMILE5_JP_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5760 / 4800
ALPHA_SMILE13_3_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏5400 / 4500
ALPHA_M48XXX_BATTERY_CHG_CUT_VOLT / _DISCHG_CUT_VOLT宏通用兜底值 5400 / 4800

2.3 电池日志相关宏(对应代码已 #if 0)

名称类型说明
ALPHA_BMS_LOG_BUFF_LEN宏单条电池日志缓存长度 256(:58),Cloud 打包按最长 256 字节
ALPHA_BMS_LOG_SEND_BUFF_NUMBER宏一次给云平台打包的日志最大条数 19(:59)

2.4 下行指令 CAN ID 宏(EMS → BMS)

名称类型说明
ALPHA_BATTERY_GET_CONF_ID宏0x0CF200A0 握手/识别帧
ALPHA_BATTERY_BATTERY_SHUTDOWN_ID宏0x0CF200D0 电池关机
ALPHA_BATTERY_SEND_SET_CODE_1_ID宏0x18FFA2F1 周期配置 1
ALPHA_BATTERY_SEND_SET_CODE_2_ID宏0x18FFA2F3 周期配置 2
ALPHA_BATTERY_SET_ENERGY_CODE_1_ID宏0x18FFA2F2 写入 EMS 侧充放电电量
ALPHA_BATTERY_SET_SN_SPLICE_ID宏0x18FFA2F4 并机 SN 下发
ALPHA_BATTERY_SET_SELF_LOCK_ID宏0x18FFA2F5 自锁配置/清除
ALPHA_BATTERY_SET_ACTIVATE_TIME_ID宏0x18FFA2F6 激活时间下发
ALPHA_BATTERY_SET_REAL_TIME_ID宏0x18FFA2F7 BMS 校时
ALPHA_BATTERY_QUERY_LOG_TIME_ID宏0x18FE00F0 日志时间查询(代码已 #if 0)
ALPHA_BATTERY_QUERY_LOG_NUM_ID宏0x18FE00F1 单条日志索取(代码已 #if 0)

2.5 上行状态帧 CAN ID 宏(BMS → EMS)

名称类型说明
ALPHA_BATTERY_GET_OPERATION_STATE_1..17_ID宏17 组系统运行状态帧 ID,见下表明细
ALPHA_BATTERY_GET_SINGLE_CELL_VOLT_1..12_ID宏12 台电池单体电压极值帧,0x0CF1012~0x0CF10C2
ALPHA_BATTERY_GET_SINGLE_CELL_TEMPER_1..12_ID宏12 台电池单体温度极值帧,0x0CF1013~0x0CF10C3
ALPHA_BATTERY_GET_MIX_CODE_1..12_ID宏12 组混装电池单台参数帧,0x18F211F6~0x18F21CF6
ALPHA_BATTERY_GET_ALARM_CODE_1..12_ID宏12 台保护码帧,0x18F311F4~0x18F31CF4
ALPHA_BATTERY_GET_WARNING_CODE_1..12_ID宏12 台告警码帧,0x18F311F5~0x18F31CF5
ALPHA_TW_BATTERY_GET_PROTECT_CODE_1..12_ID宏台湾版扩展保护码帧,0x18F311F8~0x18F31CF8
ALPHA_BATTERY_GET_ERROR_CODE_1..3_ID宏0x18F214F3 / 0x18F215F4 / 0x18F216F4 主机级故障/保护位域帧
ALPHA_BATTERY_GET_ENERGY_CODE_1_ID宏0x18FFA1F1 能量读取(当前解析为空实现)
ALPHA_BATTERY_READ_SOCDISPLAY_CODE_1_ID宏0x18FFA1F2 SOC 显示范围与系统容量
ALPHA_BATTERY_GET_REQUEST_CODE_ID宏0x18FFA1F4 BMS 请求(加热/校时)
ALPHA_BATTERY_SET_STEP_PROTECT_CODE_ID宏0x18FFA1F5 阶梯保护电流
ALPHA_BATTERY_GET_SN_SPLICE_ID / ALPHA_BATTERY_GET_TYPE_SPLICE_ID宏0x18F410F3 / 0x18F510F3 并机 SN / 型号回读
ALPHA_BATTERY_GET_SELF_LOCK_STATUS_ID宏0x18F610F3 自锁状态回读
ALPHA_BATTERY_GET_ACTIVATE_TIME_1..12_ID宏0x18FF11F5~0x18FF1CF5 激活时间回读
ALPHA_BATTERY_LOG_INDEXES_ID / _LOG_DATA_ID宏0x18FE0000 / 0x18FE0001 日志索引与数据(代码已 #if 0)
ALPHA_BATTERY_GET_MAX_CAPACITY_1..12_ID宏0x18F23013~0x18F230C3 SOC 算法最大容量(Ah)
ALPHA_BATTERY_GET_CLUSTER_A_INFO / _B_INFO宏0x18F00AF3 / 0x18F00BF3 串并联 A/B 簇信息
ALPHA_BATTERY_1..12ID_TEMP_INFO_1/2_AFE宏24 个云 BMS 分钟级单体温度明细帧,0x18231101~0x18231c02
ALPHA_BATTERY_1..12ID_VOLT_1..4_INFO_1/2_AFE宏96 个云 BMS 分钟级单体电压明细帧,0x18241101~0x18271c02

ALPHA_BATTERY_GET_OPERATION_STATE_1..17_ID 明细:

序号宏值
1..._STATE_1_ID0x0CF100C0
2..._STATE_2_ID0x185717F3
3..._STATE_3_ID0x18F225F3
4..._STATE_4_ID0x18F212F3
5..._STATE_5_ID0x181E17F3
6..._STATE_6_ID0x181F17F3
7..._STATE_7_ID0x18F216F3
8..._STATE_8_ID0x18F30001
9..._STATE_9_ID0x18F30002
10..._STATE_10_ID0x0CF100D0
11..._STATE_11_ID0x18F30004
12..._STATE_12_ID0x18f30005
13..._STATE_13_ID0x18f30006
14..._STATE_14_ID0x18f217f3
15..._STATE_15_ID0x18f218f3
16..._STATE_16_ID0x18f219f3
17..._STATE_17_ID0x181F18F3

2.6 欧盟电池法自信息帧族宏

名称类型说明
BMS_INFO_GROUP_ID宏帧族基址 0x18FF1000(:350)
BMS_INFO_ID(id, func)宏函数`(0x18FF1000 \((id) << 8) \(func)),按电池号与功能码拼 ID(:352`)
BMS_ID_F1(x)宏函数func = 0xF1,"量相关":容量吞吐、能量吞吐(:355)
BMS_ID_F2(x)宏函数func = 0xF2,"效率、阻相关":剩余容量、往返效率、剩余功率、欧姆内阻(:356)
BMS_ID_F3(x)宏函数func = 0xF3,"电率、演化、循环相关":自放电率、等效循环、深放次数(:357)
BMS_ID_F4(x)宏函数func = 0xF4,"时间相关":超上限/超下限运行时间(:358)
BMS_ID_F5(x)宏函数func = 0xF5,"时间相关":超上限/超下限充电时间(:359)
BMS_ID_F6(x)宏函数func = 0xF6,"日期相关":生产日期、装机日期(:360)
BMS_ID_F7(x)宏函数func = 0xF7,"次数、UNIX 时间相关":深充次数、装机日期 unix 时间戳(:361)

2.7 本文件定义的枚举与结构体

名称类型说明
BAT_LOG_FSM_E枚举电池日志状态机的 4 个状态:BAT_LOG_QUERY_FSM、BAT_LOG_REV_DATA_FSM(接收并存放 BMS 传来的日志)、BAT_LOG_SEND_DATA_FSM(日志上传云平台,需等待)、BAT_LOG_END_FSM(:365-370)
BAT_LOG_REV_STA_E枚举日志接收结果:BAT_LOG_REV_SUCCESS、BAT_LOG_REV_ERROR、BAT_LOG_REV_REJECT(:372-376)
BAT_LOG_T结构体单条日志接收上下文:u8_bat_id(应接收的电池 ID)、u8_frame_number(一条日志的分包数)、u8_log_len(一条日志的字节数)、u8_frame_index(保序用帧序号)、u8_rev_flag(数据接收标志)、u8_rev_all_flag(一条日志接收完成标志)、u8_rev_err_flag(接收出错标志 0/1)、u8_log_buff[256]、u16_log_number(当前日志序号)(:378-388)
BAT_LOG_PACK_T结构体上传云平台的日志包:u8_bat_count(电池个数)、u8_bat_id、u16_log_all_count(时间段内日志总数)、u8_log_send_number(本帧日志数量)、u8_log_residue_number(剩余日志数)、log_rev_state(BAT_LOG_REV_STA_E)、u8_log_buff[19][256](日志内容)(:390-398)

对应的 BAT_LOG_T g_t_bms_log_buff / BAT_LOG_PACK_T g_t_bms_log_pack_buff 变量定义在 battery_comm.c:38-39,已被注释掉。

2.8 本文件引用但定义在别处的类型

名称定义位置说明
CAN_MSG_TYPEDEF_Thardware/can/can0.h:21-28CAN 帧结构 frame_id/frame_type/frame_len/frame_data[8]/reading_flag
BATTERY_SET_SN_TABLE_Tmidware/bms/bms.h:1113并机 SN 配置表,send_battery_set_code_c_cmd() 的入参类型
u8 / u16 / u32 / s8 / s16 / u64includes.h工程统一的基本类型别名

3. 函数清单

本文件(.h)只包含函数声明,不含函数定义。按声明分组如下:

函数名作用域说明
send_battery_restart_cmd(void)全局声明,实现于 battery_comm.c:127电池重启指令
send_battery_shutdown_cmd(void)全局声明,实现于 battery_comm.c:194电池关机指令
send_battery_cmd(u32 id, u8 flag, u8 action1, u8 action2)全局声明,实现于 battery_comm.c:241通用命令帧
send_battery_set_code_1_cmd(void)全局声明,实现于 battery_comm.c:298周期配置 1
send_battery_set_code_2_cmd(void)全局声明,实现于 battery_comm.c:421周期配置 2
send_battery_set_code_c_cmd(BATTERY_SET_SN_TABLE_T *data)全局声明,实现于 battery_comm.c:516并机 SN 分包下发
send_battery_set_code_d_cmd(u8 u8_type, u8 u8_value)全局声明,实现于 battery_comm.c:560自锁配置/清除
alpha_bms_package_parser(uint32_t id, uint8_t *data)全局声明,实现于 battery_comm.c:1088BMS 扩展帧总解析入口
get_master_battery_lost(void)全局声明,实现于 battery_comm.c:2263主机通信丢失查询
send_battery_activate_time_cmd(u8 type, u8 id)全局声明,实现于 battery_comm.c:359激活时间下发
send_battery_self_info_clear_cmd(u8 id)全局声明(:411),实现被注释(battery_comm.c:1043-1079)只有声明没有实现:清电池自信息
get_bat_log_cmd_id_code(void)声明被 #if 0 包裹(:413),实现同样 #if 0日志命令 ID 读取
set_bat_log_cmd_id_code(u8 *buff, u32 len)声明被 #if 0 包裹(:414)日志命令 ID 写入
bat_log_handle(void)声明被 #if 0 包裹(:415)电池日志状态机
send_battery_set_real_time_cmd(void)extern 声明(:417),实现于 battery_comm.c:660BMS 校时
get_battery_cell_low_vol_protection(void)extern 声明(:418),实现于 battery_comm.c:2479单体欠压保护汇总
get_battery_cell_low_vol_warning(void)extern 声明(:419),实现于 battery_comm.c:2499单体欠压告警汇总
get_battery_comm_lost(void)extern 声明(:420),实现于 battery_comm.c:2519主从通信丢失汇总
send_battery_set_brand_cmd(u8 bat_id, u8 brand, u8 origin)extern 声明(:421),实现于 battery_comm.c:466电池品牌/产地下发

注意:battery_comm.c 中另有若干非 static 但本头文件未声明的函数(can_send_standard_pack、can_send_exten_pack、Battery_Ack、get_single_cell_volt、get_single_cell_temper、get_battery_alarm_code、get_battery_protection_extend1_code、get_battery_warning_code、get_battery_activate_time、get_single_cell_temper_info、get_single_cell_volt_info、get_bms_self_info、send_battery_energy_cmd),其中前三个带 static 关键字、后十个为全局可见却无声明。

4. 核心逻辑解析

本文件为纯声明文件,无状态机与算法。以下仅说明它承载的"协议契约"层面的设计要点。

4.1 ID 编码规律(解析侧依赖的关键约定)

4.2 版本演进痕迹

头文件按"需求"分组注释,可以看到明确的增量演进:ALPHA_BATTERY_GET_MAX_CAPACITY_* 标注"需求1最大容量上报",ALPHA_BATTERY_GET_CLUSTER_A/B_INFO 标注"需求5 串并联信息显示",BMS_INFO_GROUP_ID 一族对应"欧盟电池法"。DEBUG_ALPHA_MAX_AH / DEBUG_ALPHA_BAT_CLUSTER 两个开关也是随这些需求新增的。

4.3 与 uCOS-II 的配合

头文件本身不涉及任务、信号量与消息邮箱。所有调度时序细节(task_bms 的调用节奏、超时看门狗)都在 battery_comm.c 中实现。

5. 对外接口

5.1 本文件导出(供外部调用)

导出类别内容使用方
函数原型19 个 send_battery_* / get_* 声明(见第 3 节)midware/bms/bms.c(#include "battery_comm.h",bms.c:14)、net/ems.c(#include,ems.c:54)
类型BAT_LOG_FSM_E、BAT_LOG_REV_STA_E、BAT_LOG_T、BAT_LOG_PACK_T目前无外部使用者(相关代码均 #if 0)
宏常量全部 CAN ID 宏、截止电压宏、日志长度宏、欧盟电池法 ID 构造宏battery_comm.c(主要使用者)、midware/bms/bms.c(截止电压宏)
全局变量无—

5.2 本文件引用的外部内容

来源内容
includes.h(battery_comm.h:13)基本类型 u8/u16/u32/s8/s16、TRUE/FALSE、标准库与全部中间件头文件
bms.h(battery_comm.h:14)BATTERY_SET_SN_TABLE_T、BATTERY_MAX_NUM、BMS_HARDWARE_PLATFORM 等

6. 依赖关系

依赖

#include <includes.h>   // battery_comm.h:13
#include "bms.h"        // battery_comm.h:14

被依赖

文件说明
midware/bms/alpha/battery_comm.c自身实现文件,#include "battery_comm.h"(battery_comm.c:13)
midware/bms/bms.c#include "battery_comm.h"(bms.c:14),使用下行指令与 alpha_bms_package_parser
net/ems.c#include "battery_comm.h"(ems.c:54)
net/server.c通过工程包含链使用 send_battery_set_brand_cmd(server.c:2581)

7. 备注与风险点

  1. send_battery_self_info_clear_cmd() 声明与实现不一致(:411 vs battery_comm.c:1043-1079 被注释)。函数原型在头文件中有效,任何外部文件调用它都会在链接阶段报未定义符号。该功能注释说明"此功能现在由 BMS 上位机完成"。
  1. 三个日志函数声明被 #if 0 包裹(:412-416),但紧随其后的 extern 声明组(:417-421)未包裹,风格不统一;#if 0 块内缩进也与周围代码不一致(s8* / void 顶格,缺少 4 空格),属于反复增删留下的痕迹。
  1. ALPHA_BATTERY_GET_SINGLE_CELL_VOLT_1..12_ID 的值疑似漏写一位十六进制:0x0CF1012、0x0CF1022…(:80-91)而同族温度帧 0x0CF1013、0x0CF1023…(:93-104)写法一致,两者都只有 7 个十六进制位。解析侧因为全部用"与基址做差"的相对算法所以当前自洽,但这个数值与协议文档中常见的 8 位扩展 ID 形式不符,存在被"纠正"后破坏兼容的风险,建议对照 BMS 协议原文确认。
  1. DEBUG_ALPHA_BAT_ERR_ALARM 是死宏(:20):全工程没有任何地方引用,属未清理的配置项。
  1. ALPHA_SMILE_BAT_* 等新型号没有对应的截止电压宏:battery_comm.h:22-56 只覆盖了 12 个型号,而 bms.h:20-53 的电池型号表已扩展到 30 余种(含 ALPHA_SMILE_G3_BAT_3_8S_ID、ALPHA_SMILE_BAT_8_2PH_ID 等)。新型号依赖 ALPHA_M48XXX_BATTERY_CHG_CUT_VOLT 兜底值,若某型号截止电压与兜底值不同即为配置遗漏。
  1. BMS_INFO_ID 宏无参数校验(:352):(id) << 8 若 id > 0xFF 会与 func 字节及基址重叠,宏展开后产生意料之外的 ID。当前所有调用点(BMS_ID_F1..F7(i+1),i < BATTERY_MAX_NUM = 12)都安全。
  1. #define ALPHA_BATTERY_GET_SINGLE_CELL_VOLT_x_ID (0X0CF1012) 使用了 0X 前缀(:80-104、:175-187 等):C 语言合法,但工程内注释与代码混用 0x/0X 两种写法,可读性不一致。
  1. ALPHA_BMS_LOG_BUFF_LEN 与 ALPHA_BMS_LOG_SEND_BUFF_NUMBER 仍在使用范围外:BAT_LOG_T/BAT_LOG_PACK_T 结构体用它们做数组维度(u8_log_buff[19][256],合计约 4.9 KB),而定义这两个结构体的变量(g_t_bms_log_buff/g_t_bms_log_pack_buff)已被注释。若将来恢复日志功能,BAT_LOG_PACK_T 约 4.9 KB 的实例若放在栈上会立即溢出,源码注释表明原本是放在 SDRAM(SDRAM_BAT_LOG_BUFF_ADDR / SDRAM_BAT_LOG_SEND_BUFF_ADDR)。