alphaess_comm_can.h
SEND_CALIBRATION_DATA_FLAG.bit）4.3 zero_glitch_filter_t 的状态语义4.4 打包与对齐约定5. 对外接口本文件导出本文件依赖的外部符号6. 依赖关系依赖被依赖7. 备注与风险点源文件路径：
midware/inverter/alphaess/alphaess_comm_can.h所属模块：midware/inverter/alphaess（AlphaESS 逆变器 CAN 通信 + VAVE 电表校准） 代码行数：219
1. 文件职责
本文件是 alphaess_comm_can.c 的对外契约头文件，集中定义 EMS 与 AlphaESS 逆变器之间 CAN 通信的全部报文 ID（命令字）、逆变器工作模式枚举、以及 VAVE 电表芯片校准参数的数据结构与发送标志位域。它把 CAN 报文的"语义字典"和"参数容器"暴露给上层（HMI、Modbus、逻辑层），使非 CAN 模块也能填写校准数据、读取工作模式。
数据流上，它处在"外部模块写 dsp_meter_calibration_data → alphaess_comm_can.c 组帧下发"的入口位置；同时通过 extern 声明把 DSP_METER_CALIBRATION_DATA dsp_meter_calibration_data 与八个函数原型释放给整个工程。本文件不含任何可执行代码，全部是宏、类型与声明。
2. 关键数据结构与宏
| 名称 | 类型 | 说明 |
|---|---|---|
__ALPHAESS_COMM_CAN_H__ | 宏 | 头文件包含守卫 |
ALPHAESS_INV_DEBUG | 宏 | 值 (0)，本文件（及其实现文件）的调试打印总开关 |
ALPHAESS_EMS_INV_IDCODE_PACK | 宏 | 0x181，EMS→INV 身份握手帧 ID |
ALPHAESS_EMS_CTRL_BACKUP | 宏 | 0x184，EMS→INV 备份/UPS 使能控制 |
ALPHAESS_EMS_INV_SET_CTRL_MODE | 宏 | 0x190，EMS→INV 控制模式设置（单相/三相不平衡） |
ALPHAESS_GINLONG_EMS_CTRL_INV_AC_POWER1 | 宏 | 0x192，EMS→INV AC 有功功率给定（命名残留 Ginlong 前缀） |
ALPHAESS_EMS_CTRL_INV_AC_POWER2 | 宏 | 0x193，EMS→INV 直流充放电限值等 |
ALPHAESS_EMS_READ_BAT_CHG_DISCHG | 宏 | 0x194，EMS→INV 电池最大充/放电功率 |
ALPHAESS_EMS_SET_INV_CTRL_ARG1 | 宏 | 0x195，EMS→INV MPPT 百分比 + 备电频率偏移 |
ALPHAESS_EMS_SEND_BAT_STATE | 宏 | 0x1A0，EMS→INV 电池运行状态 |
ALPHAESS_EMS_SEND_BAT_PROTECT | 宏 | 0x1A1，EMS→INV 电池保护参数 |
ALPHAESS_INV_EMS_IDCODE_PACK | 宏 | 0x201，INV→EMS 握手应答 |
ALPHAESS_INV_EMS_RETURN_RUN_INFO_PACK4~PACKA | 宏 | 0x263~0x269，INV→EMS 运行数据回传（7 帧） |
DSP_METER_RUN_INFO_PACK1~PACK10 | 宏 | 0x301~0x310，VAVE 电表芯片运行数据回传 |
DSP_METER_CALI_DATA_PACK0~PACKA | 宏 | 0x340~0x34A，电表校准数据下行帧 |
DSP_METER_CALI_DATA_PACKB | 宏 | 0x350，相位数据校准模式（双向，含回读） |
DSP_METER_CALI_DATA_PACKC | 宏 | 0x360，设置储能逆变发电量/买电量 |
DSP_METER_CALI_DATA_PACKD | 宏 | 0x361，设置并网机发电量 |
ZERO_CONFIRM_CNT | 宏 | 值 5，毛刺滤波判定真实 0 的连续次数阈值 |
zero_glitch_filter_t | 结构体 | int32_t s32_last_value + uint8_t zero_cnt，偶发 0 毛刺滤波器状态 |
ALPHAESS_OPERATION_MODE_E | 枚举 | 逆变器工作模式：ALPHAESS_POWER_ON_E(0)、WAIT_E(1)、BYPASS_E(2)、CHECK_E(3)、ON_GRID_E(4)、OFF_GRID_E(5)、SELF_TEST_E(6)、FAULT_E(7)、UPDATA_E(8)、SHUTDOWN_E(9)、DC_MODE_E(10)、POWER_ON_E_2(255) |
SEND_CALIBRATION_DATA_FLAG | 联合体 | u16 u16_all 与 16 位位域 bit 的联合；bit0~bit13 依次对应 0x340/341/342/343/344/345/346/347/348/349/34A/350/360/361 的"待发送"标志，bit14/bit15 保留 |
DSP_METER_CALIBRATION_DATA | 结构体 | 电表校准全量参数：R/S/T 三相电压校准点、电网电流校准点、PV 电流校准点、电网放电功率校准点 0/1、PV 放电功率校准点 0/1、电网充电功率校准点 0/1、校准模式与复位、清除电量指令（bit0 放电/bit1 发电/bit2 并网机发电）、CT 自检使能、相位校准数据与触发、储能逆变发电量/买电量高低字节、并网机发电量高低字节；#pragma pack(1) 紧凑布局 |
dsp_meter_calibration_data | 全局变量声明 | extern，实体定义在 alphaess_comm_can.c:27 |
3. 函数清单
本文件为纯声明头文件，不含函数定义；下表列出其声明的全部函数原型（均在 alphaess_comm_can.h:208~215）。
| 函数名 | 作用域 | 说明 |
|---|---|---|
alphaess_comm_init_can | 全局声明（原型） | 初始化 CAN1 与 CAN 侧发送标志，实体见 alphaess_comm_can.c:60 |
ems_ate_reset_dsp | 全局声明（原型） | ATE 模式复位 DSP：连发 AC 功率/DC 限值/电池功率/电池状态，实体见 alphaess_comm_can.c:83 |
alphaess_inverter_comm_can | 全局声明（原型） | CAN 通信主循环：握手、周期下发、接收解析、链路丢失检测，实体见 alphaess_comm_can.c:1057 |
alphaess_inverter_can_data_check | 全局声明（原型） | CAN 收到数据的后处理与重发标志置位，实体见 alphaess_comm_can.c:1330 |
parse_alphaess_work_mode | 全局声明（原型） | 将 ALPHAESS 工作模式码翻译为项目统一运行模式码，实体见 alphaess_comm_can.c:118 |
handle_alphaess_inv_set_battery_shutdown_flag | 全局声明（原型） | 声明为"根据电池侧空开状态处理逆变器关机标志"，全工程无任何定义，属死声明 |
zero_glitch_filter | 全局声明（原型） | 采样值偶发 0 毛刺滤波，实体见 alphaess_comm_can.c:1374 |
zero_glitch_filter_reset | 全局声明（原型） | 复位毛刺滤波器状态，实体见 alphaess_comm_can.c:1399 |
4. 核心逻辑解析
本文件无状态机与算法实现，核心逻辑体现在CAN 报文 ID 空间的划分与校准标志位域的位序约定上。
4.1 CAN ID 空间划分
文件用注释显式把 CAN ID 分成两组，形成一条不对称的双向约定：
EMS → INV（0x1xx / 0x3xx 下行）
| ID | 用途 |
|---|---|
| 0x181 | 身份握手，数据域 ASCII "AlphaESS" |
| 0x184 | 备份（UPS）使能 |
| 0x190 | 控制模式（单相 / 三相不平衡） |
| 0x192 | AC 有功功率给定（总有功 + A/B/C 相） |
| 0x193 | DC 充放电限值 + 软启动 + 电池连接状态 + 电池总电流 |
| 0x194 | 电池最大充放电功率（变化时发） |
| 0x195 | MPPT 百分比 + 备份频率偏移 |
| 0x1A0 | 电池运行状态 |
| 0x1A1 | 电池保护参数 |
| 0x340~0x34A, 0x350, 0x360, 0x361 | 电表校准与电量设置 |
INV → EMS（0x2xx / 0x3xx 上行）
| ID | 用途 |
|---|---|
| 0x201 | 握手应答 |
| 0x263~0x269 | 运行数据回传（电网/备份/逆变器三相电压电流功率、频率、电池功率、工作模式） |
| 0x301~0x310 | VAVE 电表芯片运行数据 |
| 0x350 | 相位校准数据回读 |
注意 0x350 同时出现在两个方向（DSP_METER_CALI_DATA_PACKB，:68 与 :1291 的处理），下行写校准数据、上行读回读值；0x340~0x34A、0x360、0x361 为纯下行。此外 0x181/0x201、0x192/0x263~0x269 等上下行 ID 之间没有固定的 +0x80 或镜像关系，只能查表匹配。
4.2 校准标志位域（SEND_CALIBRATION_DATA_FLAG.bit）
位域与帧 ID 的映射由实现文件 ems_send_dsp_meter_calibration_data()（alphaess_comm_can.c:980）按 switch(i) 消费，约定如下：
| bit | 字段名 | 对应帧 |
|---|---|---|
| 0 | u8_send_volt_calibration_flag | 0x340 电压校准 |
| 1 | u8_send_curr_calibration_flag | 0x341 电网电流校准 |
| 2 | u8_send_pvcurr_calibration_flag | 0x342 PV 电流校准 |
| 3 | u8_send_pdischg_calibration0_flag | 0x343 放电功率校准 0 |
| 4 | u8_send_pdischg_calibration1_flag | 0x344 放电功率校准 1 |
| 5 | u8_send_pvpdischg_calibration0_flag | 0x345 PV 放电功率校准 0 |
| 6 | u8_send_pvpdischg_calibration1_flag | 0x346 PV 放电功率校准 1 |
| 7 | u8_send_pchg_calibration0_flag | 0x347 充电功率校准 0 |
| 8 | u8_send_pchg_calibration1_flag | 0x348 充电功率校准 1 |
| 9 | u8_send_calibration_mode_flag | 0x349 校准模式 |
| 10 | u8_send_ct_self_check_mode_flag | 0x34A CT 自检 |
| 11 | u8_send_set_calibration_mode_flag | 0x350 相位数据校准 |
| 12 | u8_send_set_inverter_gen_flag | 0x360 储能逆变发电量 |
| 13 | u8_send_set_pgu_gen_falg | 0x361 并网机发电量 |
因为位域在 #pragma pack(1) 内按声明顺序自低到高分配，u16_all 的 bit 序与上表一致；使用方只需对 u16_all 按位或即可一次挂起多帧。
4.3 zero_glitch_filter_t 的状态语义
zero_glitch_filter_t 的设计意图写在结构体成员注释里（:78~:79）：s32_last_value 保存"上一个有效值"，zero_cnt 保存"连续 0 计数"。调用方（alphaess_comm_can.c 的接收解析分支）为每个物理量各自持有一份 static 状态，配合 ZERO_CONFIRM_CNT = 5 实现"偶发 0 沿用电网表上次值、连续 5 次 0 才认真实 0"的抗毛刺策略。
4.4 打包与对齐约定
#pragma pack(1) ... #pragma pack()（:99、:204）包住 SEND_CALIBRATION_DATA_FLAG 与 DSP_METER_CALIBRATION_DATA，保证结构体内无填充字节，便于按偏移整体读写或跨模块二进制对齐。需要注意 DSP_METER_CALIBRATION_DATA 前四个字段是 SEND_CALIBRATION_DATA_FLAG(2B) + u16 + u16，后续全为 s16/u16，因此结构体内所有校准点偏移都是偶数字节，不存在字节错位问题。
5. 对外接口
本文件导出
| 符号 | 类型 | 使用者 |
|---|---|---|
全部 ALPHAESS_* / DSP_METER_* 帧 ID 宏 | 宏 | alphaess_comm_can.c（组帧/解析）、alphaess_upgrade.c（alphaess_comm_init_can） |
ALPHAESS_OPERATION_MODE_E | 枚举 | alphaess_comm_can.c:parse_alphaess_work_mode |
SEND_CALIBRATION_DATA_FLAG | 联合体 | DSP_METER_CALIBRATION_DATA 内嵌 |
DSP_METER_CALIBRATION_DATA | 结构体 | alphaess_comm_can.c、以及任何需要填写校准参数的模块 |
dsp_meter_calibration_data | 全局变量（extern） | 由 alphaess_comm_can.c:27 定义；HMI/Modbus 可写入 |
zero_glitch_filter_t | 结构体 | alphaess_comm_can.c 内 static 滤波器实例 |
| 八个函数原型 | 声明 | 见第 3 节 |
本文件依赖的外部符号
| 来源 | 使用内容 |
|---|---|
includes.h（:13） | 聚合头，提供 u8/u16/s16/s32/int32_t/uint8_t 等基础类型与工程公共头 |
除 includes.h 外不 include 任何其他头文件，因此本头文件不能单独编译，必须放在 includes.h 之后。
6. 依赖关系
依赖
includes.h（唯一显式依赖）。
被依赖
midware/inverter/alphaess/alphaess_comm_can.c（:13）——主要实现方；midware/inverter/alphaess/alphaess_upgrade.c（:14）——为调用alphaess_comm_init_can()而包含本头文件；- 通过
alphaess_comm_can.c间接影响midware/inverter/inverter.c、alphaess_comm_usart.c。
7. 备注与风险点
handle_alphaess_inv_set_battery_shutdown_flag无定义（:213）：全工程仅有此一处声明，任何调用都会链接失败。属版本遗留的死声明，建议删除或补实现。zero_glitch_filter()/zero_glitch_filter_reset()被导出但无外部调用者（:214~:215）：全工程搜索仅在alphaess_comm_can.c内使用，zero_glitch_filter_reset甚至在本文件之外完全未被调用，属未被使用的接口。- 命名残留：
ALPHAESS_GINLONG_EMS_CTRL_INV_AC_POWER1（:21）带GINLONG（锦浪）前缀，实际是 AlphaESS 的 0x192 帧，应为跨厂商复制粘贴残留，易误导。 DSP_METER_CALIBRATION_DATA存在语义重复字段（:136~:137 与 :176~:177）：u16_calibration_enable/u16_reset_calibration_mode与后面的u16_calib_mode/u16_reset_calib_mode名称、含义高度重叠，后者才是ems_send_349pack实际使用的字段（alphaess_comm_can.c:841~844），前者疑似废弃。DSP_METER_CALI_DATA_PACKA与DSP_METER_CALI_DATA_PACKB的 ID 不连续（:67~:68）：PACKA = 0x34A、PACKB = 0x350，跳过了 0x34B~0x34F，而PACKC = 0x360、PACKD = 0x361又跳回 0x36x 段。这种"十六进制后缀命名 + 不连续数值"的组合极易被误读为连续地址。DSP_METER_RUN_INFO_PACK10的编号是十进制10（:54），而相邻宏用十六进制后缀A~F（:48~:53）。0x301~0x30F用 A~F，第十六个却写作PACK10，命名风格不一致（值0x310正确）。ALPHAESS_OPERATION_MODE_E与实现文件的switch不完全对齐（:82~:96 对比alphaess_comm_can.c:123~165）：枚举里定义了ALPHAESS_SHUTDOWN_E(9)，但parse_alphaess_work_mode的switch没有该 case，会落到default: 0xff；ALPHAESS_UPDATA_E(8) 虽有 case 但返回 0（l_u8_run_mode初值），语义不明显。- 位域 bit14/bit15 无实际用途（:125~:126），仅为补齐 16 位；若将来新增校准帧需注意帧 ID 与 bit 序号需要同步维护两处。
ZERO_CONFIRM_CNT为固定 5 且不可配置（:74）：不同物理量（电压/有功功率）的采样率与噪声特性不同，共用同一阈值是简化处理，注释也仅说明"连续 N 次为 0 判定为真实 0"。- 头文件不自包含：依赖
includes.h提供的定长类型，若在其他子系统中单独 include 会编译失败；建议在头内显式 includeincludes.h（当前已通过 :13 包含，但zero_glitch_filter_t使用了标准int32_t/uint8_t，混用工程自定义u8/s16与 C99 类型，风格不统一）。