首页 / knowledge/代码解析/midware/inverter/kelong
kelong_comm.h
本页目录1. 文件职责2. 关键数据结构与宏2.1 命令字宏（帧 ID 表）2.2 结构体与联合体2.3 对外全局变量与函数声明3. 函数清单4. 核心逻辑解析4.1 触发标志的"边沿"语义4.2 位域布局与字节序4.3 告警/故障的分散落点5. 对外接口6. 依赖关系7. 备注与风险点
源文件路径：
midware/inverter/kelong/kelong_comm.h所属模块：midware/inverter/kelong（科隆逆变器 CAN 通信协议） 代码行数：381
1. 文件职责
本头文件是科隆（Kelong）逆变器 CAN 通信协议的协议字典 + 触发标志容器。它把 EMS 与科隆逆变器之间所有 11 位标准帧 ID（0x181~0x28C，共 4 组：0x18x/0x19x 下发控制类、0x1Bx/0x1Dx 下发参数类、0x20x~0x28x 上传回读类）以宏的形式固化成一张"命令字表"，供 kelong_comm.c 组帧时直接引用。同时它定义了 EMS 侧的发送触发标志结构体 KELONG_TABLE_T，以及两套 64 位故障/告警位域联合体，用于把逆变器上报的两个 8 字节错误字按位解码成 EMS 统一的故障码位域。文件本身不含任何可执行逻辑，只被 kelong_comm.c 和 inverter.c 通过 inverter.h 间接引用。
2. 关键数据结构与宏
2.1 命令字宏（帧 ID 表）
| 名称 | 类型 | 说明 |
|---|---|---|
KELONG_INV_DEBUG | 宏 | 调试打印总开关，置 1 时打开 printf 调试输出，量产为 0 |
EMS_INV_IDCODE_PACK | 宏 0x181 | EMS→INV 握手/ID 码帧，数据域为 ASCII "AlphaESS" |
EMS_SET_INV_CTRL_COMMAND1 | 宏 0x184 | 开关机与运行控制命令帧（工作模式、复位、UPS、自检、清能、GFCI/N 线测试等） |
EMS_SET_INV_CTRL_COMMAND2 | 宏 0x185 | MPPT 扫描控制命令帧 |
EMS_SET_INV_POWER_CTRL_MODE1 | 宏 0x190 | 功率控制模式设置（0 = DC 控制） |
EMS_CTRL_INV_DC_POWER1 | 宏 0x191 | DC 侧充放电功率给定（周期帧，最小 15 ms） |
EMS_CTRL_INV_AC_POWER1 | 宏 0x192 | AC 侧有功功率给定（宏已定义，代码中未组帧） |
EMS_CTRL_INV_AC_POWER2 | 宏 0x193 | AC 侧有功功率给定（备选帧，代码中未组帧） |
EMS_SET_INV_BAT_LIMIT_POWER1 | 宏 0x194 | 电池最大充/放电功率限值下发 |
EMS_SET_INV_CTRL_ARG1 | 宏 0x195 | 控制参数下发（MPPT 百分比、备电输出频率偏置） |
EMS_SEND_BAT_RUN_DATA | 宏 0x1A0 | 电池运行数据下发（电压、继电器状态、SOC） |
EMS_SEND_BAT_PROTECT_ARG | 宏 0x1A1 | 电池保护参数下发（放电截止电压/最大电流、充电截止电压/最大电流） |
EMS_SET_INV_GRID_PROTECT_ARG1..9 | 宏 0x1B0~0x1B8 | 并网保护参数下发（共 9 帧） |
EMS_SET_INV_SAFETY_ARG1..F | 宏 0x1D0~0x1DE | 安规参数下发（共 15 帧，十六进制编号 a~f） |
INV_EMS_IDCODE_PACK | 宏 0x201 | INV→EMS 握手应答 |
INV_EMS_PARA_SET_RESULT_PACK | 宏 0x202 | INV→EMS 参数设置结果应答，d0/d1 为被应答的命令字 |
INV_EMS_RETURN_INFO_PACK1..4 | 宏 0x205~0x208 | INV→EMS 版本信息/序列号 |
INV_EMS_RETURN_RATED_PACK1..2 | 宏 0x220~0x221 | INV→EMS 额定参数回读 |
INV_EMS_RETURN_GRID_PROTECT_PACK1..9 | 宏 0x230~0x238 | INV→EMS 并网保护回读（9 帧） |
INV_EMS_RETURN_SAFETY_INFO_PACK1..F | 宏 0x240~0x24E | INV→EMS 安规信息回读（15 帧） |
INV_EMS_RETURN_RUN_INFO_PACK1..B | 宏 0x260~0x26A | INV→EMS 运行数据回读（PV、并网、备电、逆变、温度等） |
INV_EMS_RETURN_RUN_FLAG_PACK1 | 宏 0x26F | INV→EMS 安规测试状态 |
INV_EMS_RETURN_ERROR_DATA_PACK1..2 | 宏 0x270~0x271 | INV→EMS 故障字/告警字上报（各 8 字节） |
INV_EMS_RETURN_ENERGY_STATISTICS_PACK1..3 | 宏 0x275~0x277 | INV→EMS 累计发电量/充电量统计 |
INV_EMS_RETURN_SAFETY_TEST_INFO_PACK1..D | 宏 0x280~0x28C | INV→EMS 安规自检结果回读（13 帧） |
2.2 结构体与联合体
| 名称 | 类型 | 说明 |
|---|---|---|
KELONG_TABLE_T | 结构体 | 全局发送触发标志容器。成员分三类：u32_*_tick 时间戳（idcode、控制功率、电池运行数据共 3 个周期帧的节拍基准）；u8_ems_inv_idcode_flag 握手未完成标志；其余 u8_ems_set_inv_xxx_flag* 均为"待下发一次"的边沿标志，置 TRUE 后由 kelong_comm.c 发一帧并清 FALSE。字段 1~9/a~f 的命名对应 EMS_SET_INV_SAFETY_ARG* 宏，共 22 个安规相关标志 |
KELONG_ERROR_MAPPING_TABLE1_U | 联合体 | 64 位故障字位域解码表。共享 u64_all / word.word0..3（4 个 16 位字，供 CAN 大端拼装）/ bit（按 BYTE0~BYTE7 顺序的 64 个 1 位字段）。已命名位包括 bus_ovp1、apu_uvp、insulation_fault、gfci_fault、leakage_current_test_failure、grid_relay_fault、zero_ground_fault、over_temperature、pv_reverse、bat_reverse、display_com_fault、bat_relay_fault、chip1_upgrade_fault、mppt1/mppt2 四类保护、bat_ovp/bat_uvp/battery_lose/bat_otp、bat1/bat2_charge/discharge_ocp、bat1/bat2_hw_ocp；未定义位以 bitN 占位 |
KELONG_ERROR_MAPPING_TABLE2_U | 联合体 | 第二个 64 位字，混合了告警位与故障位（bat_over_voltage_alarm、bat_under_voltage_alarm、output_overload_alarm、abnormal_temperature_sensor、dc_power_alarm、fan_error、battery_stops_running_alarm、over_temperature_alarm、inv_otp/inv_ovp/inv_uvp/inv_ocp/inv_hw_ocp、output_dc_over_current、output_dc_over_voltage、output_short、grid_ovp/grid_uvp/grid_ofp/grid_ufp、phase_locked_fault、output_overload），解码后分别落到 u_fault_code、u_warning_code、u_fault_extend1_code 三个不同目标位域 |
2.3 对外全局变量与函数声明
| 名称 | 类型 | 说明 |
|---|---|---|
g_t_kelong_comm_info | 全局变量（extern） | KELONG_TABLE_T 类型，定义在 kelong_comm.c:31，是 EMS 侧与科隆协议之间唯一的发送状态存储 |
kelong_comm_init | 函数声明 | 初始化标志与逆变器配置 |
kelong_inverter_comm | 函数声明 | 科隆协议收发主循环 |
kelong_inverter_data_check | 函数声明 | 下发前的数据限幅与变化检测 |
3. 函数清单
本文件为纯头文件，不含函数定义。声明的 3 个外部接口函数如下：
| 函数名 | 作用域 | 说明 |
|---|---|---|
kelong_comm_init | 全局（声明） | 初始化 g_t_kelong_comm_info 各触发标志，设置逆变器子型号为 SUB_S6，并按需重配 CAN1 波特率分频 |
kelong_inverter_comm | 全局（声明） | 科隆逆变器 CAN 收发主循环，按标志与定时节拍组织下发帧并解析回读帧 |
kelong_inverter_data_check | 全局（声明） | 由 BMS/并机/安规数据计算并限幅后写入 g_t_inv_info.t_run_info，触发相应下发标志 |
4. 核心逻辑解析
本文件无执行逻辑，此节说明其数据结构设计对通信行为的影响。
4.1 触发标志的"边沿"语义
KELONG_TABLE_T 把下发行为分成两种驱动方式：
- 周期型：只有 3 个（
0x181握手 2 s、0x191功率给定 50 ms、0x1A0电池运行数据 500 ms），由u32_ems_*_tick做节拍基准，无条件周期发送。 - 边沿型：其余全部标志，由
kelong_inverter_data_check（数据变化检测）或外部模块（如system_config改配置、协议解析收到新回读）置 TRUE，主循环发一帧后立刻清 FALSE。因此每个参数帧在稳态下只发一次，避免总线占用。
4.2 位域布局与字节序
两个 KELONG_ERROR_MAPPING_TABLE_U 联合体使用 #pragma 之外的默认对齐（GCC/ARMCC 对 u8:1 位域按分配单元打包），顺序按 BYTE0 优先低位。回读帧在 kelong_comm.c:1970-1973 用 word.word0 = data[0]<<8 | data[1] 的方式填充，即将 CAN 的大端字节流映射为 word0 最高 16 位，这与位域 BYTE0 对应 word0 的低字节存在顺序耦合，是理解映射正确性的关键前提。
4.3 告警/故障的分散落点
KELONG_ERROR_MAPPING_TABLE2_U 的位散布到三个 EMS 目标位域（u_fault_code、u_warning_code、u_fault_extend1_code），说明科隆协议把"告警"与"故障"混在同一个 64 位字中，EMS 侧解码时必须按语义重新分流，不能整字搬迁。
5. 对外接口
本文件导出（供外部调用/引用）
- 宏：全部命令字宏、
KELONG_INV_DEBUG - 类型：
KELONG_TABLE_T、KELONG_ERROR_MAPPING_TABLE1_U、KELONG_ERROR_MAPPING_TABLE2_U - 全局变量：
extern KELONG_TABLE_T g_t_kelong_comm_info - 函数：
kelong_comm_init、kelong_inverter_comm、kelong_inverter_data_check
本文件依赖（include）
includes.h：工程统一聚合头（提供u8/u16/u32/s8/s16/TRUE/FALSE等基础类型与宏）kelong_upgrade.h：升级协议头，本文件在kelong_comm.h:14直接 include，使升级模块与常规通信共享同一编译单元
6. 依赖关系
- 依赖：
includes.h、kelong_upgrade.h - 被依赖：
midware/inverter/kelong/kelong_comm.c（kelong_comm.h:17include，使用全部命令字宏与g_t_kelong_comm_info）midware/inverter/kelong/kelong_upgrade.c通过kelong_upgrade.h间接相关- 工程中其它引用
g_t_kelong_comm_info的模块（如配置保存流程）会经inverter.h间接可见
7. 备注与风险点
- 命令字宏冗余：
EMS_CTRL_INV_AC_POWER1 (0x192)、EMS_CTRL_INV_AC_POWER2 (0x193)已定义但全工程无对应组帧函数（send_dc_ctrl_inv_power_1把 AC 有功放进了0x191的后 4 字节）。属于版本遗留定义，易误导后续维护者认为存在独立 AC 帧。 KELONG_TABLE_T标志位散乱：22 个安规标志没有数组化，导致kelong_comm.c中出现 20 多个手写的if (flag_x == TRUE)分支，增删参数帧必须同步改三处（头文件、data_check 触发点、comm 组帧点），是本模块最易漏改的地方。- 位域可移植性：
u8 xxx:1的分配顺序依赖编译器实现（ARMCC/AC5 与 GCC 在小端平台上一致，但标准未定义）。这些联合体直接与 CAN 字节流对齐，一旦换编译器需重新验证位序。 - 未命名占位位
bitN：两个错误字中大量位仅以编号占位，未文档化，协议演进后无法判断这些位是否已被逆变器使用。 KELONG_INV_DEBUG同时控制printf与函数编译：debug_inv_info()整个函数体被#if KELONG_INV_DEBUG包裹，而kelong_comm.c:2135处用的是#if (KELONG_INV_DEBUG == 1)，两种写法并存，需留意一致性。