首页 / knowledge/代码解析/midware/inverter/ginlong

ginlong_comm_can.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 报文 ID 分配契约 4.2 与 uCOS-II 的配合 5. 对外接口 6. 依赖关系 7. 备注与风险点

源文件路径：midware/inverter/ginlong/ginlong_comm_can.h 所属模块：midware / inverter / ginlong（锦浪逆变器通信）代码行数：51

1. 文件职责

本文件是锦浪（Ginlong/Solis）逆变器 CAN 通道通信模块的对外声明头。它集中定义了 EMS 与锦浪逆变器之间基于 CAN 标准帧的所有报文标识符（frame_id 常量）、CAN 通道的发送节拍状态结构体 GINLONG_COMM_CAN_T，以及两个对外接口 ginlong_comm_init_can() 与 ginlong_inverter_comm_can()。CAN 通道与同目录下的 ginlong_comm_usart.c（Modbus-RTU 串口主通道）并行工作，专门承担实时功率控制指令下发与关键运行数据回读。它本身不含任何逻辑，只被 inverter.c 的逆变器统一调度函数调用。

2. 关键数据结构与宏

名称	类型	说明
`GINLONG_INV_CAN_DEBUG`	宏	调试打印总开关，值为 `(0)`，置 1 后 `ginlong_comm_can.c` 中大量 `printf` 生效（`ginlong_comm_can.h:15`）
`GINLONG_EMS_INV_IDCODE_PACK`	宏	`0x181`，EMS 向逆变器查询身份/握手报文 ID，数据域为 ASCII `AlphaESS`（`ginlong_comm_can.h:18`）
`GINLONG_EMS_SET_INV_POWER_CTRL_MODE1`	宏	`0x190`，设置逆变器功率控制模式，本文件中仅定义未使用（`ginlong_comm_can.h:19`）
`GINLONG_EMS_CTRL_INV_DC_POWER1`	宏	`0x191`，DC 侧功率控制报文 ID，承载直流设定功率、有功设定、T 相电表有功、无功设定（`ginlong_comm_can.h:20`）
`GINLONG_GINLONG_EMS_CTRL_INV_AC_POWER1`	宏	`0x192`，AC 侧功率控制报文 ID，本文件中仅定义未使用（`ginlong_comm_can.h:21`）
`GINLONG_EMS_CTRL_INV_AC_POWER2`	宏	`0x193`，AC 侧功率控制报文 ID 备用，未使用（`ginlong_comm_can.h:22`）
`GINLONG_EMS_SET_INV_BAT_LIMIT_POWER1`	宏	`0x194`，电池限功率设置报文 ID，未使用（`ginlong_comm_can.h:23`）
`GINLONG_EMS_CTRL_THREE_UNBALANCE_POWER`	宏	`0x198`，三相不平衡功率控制报文 ID，含直流设定功率与 A/B/C 三相独立有功设定（`ginlong_comm_can.h:24`）
`GINLONG_EMS_SEND_BAT_RUN_DATA`	宏	`0x1A0`，EMS 向逆变器发送电池运行数据，未使用（`ginlong_comm_can.h:25`）
`GINLONG_INV_EMS_IDCODE_PACK`	宏	`0x201`，逆变器对 `0x181` 握手的应答报文 ID（`ginlong_comm_can.h:27`）
`GINLONG_INV_EMS_RETURN_RUN_INFO_PACK5`	宏	`0x269`，逆变器上报运行信息包 5，含 T 相有功、电网频率、电池功率（`ginlong_comm_can.h:28`）
`GINLONG_COMM_CAN_T`	结构体	CAN 通道节拍/状态表，见下

GINLONG_COMM_CAN_T（ginlong_comm_can.h:31-39）字段：

字段	类型	说明
`u8_ems_inv_idcode_flag`	`u8`	握手标志。`TRUE` 表示尚未收到 `0x201` 应答，此时只发 `0x181` 握手、不发控制帧
`u32_ems_inv_idcode_tick`	`u32`	最近一次发送 `0x181` 握手报文的系统节拍，用于 1 s 周期判定
`u32_ems_send_inv_ctrl_power_tick1`	`u32`	最近一次发送 `0x191` DC 功率控制报文的节拍，用于 600 ms 周期判定
`u32_ems_send_inv_three_unbalance_ctrl_power_tick`	`u32`	最近一次发送 `0x198` 三相不平衡控制报文的节拍，用于 2000 ms 周期判定

3. 函数清单

函数名	作用域	说明
`ginlong_comm_init_can`	全局（本文件仅声明）	初始化锦浪 CAN 通道，设置波特率分频并把握手标志置 `TRUE`
`ginlong_inverter_comm_can`	全局（本文件仅声明）	锦浪 CAN 周期通信主体：握手、按模式下发功率控制帧、解析逆变器回包

说明：本头文件不含任何函数定义，两个函数均在 ginlong_comm_can.c 中实现。

4. 核心逻辑解析

本文件不包含可执行逻辑，核心内容在 ginlong_comm_can.c。此处说明头文件层面的协议契约。

4.1 报文 ID 分配契约

CAN 采用 11 位标准帧 ID，靠高位区间区分方向：

0x181/0x190~0x194/0x198/0x1A0：EMS → 逆变器方向（0x18x、0x19x 段）。
0x201/0x269：逆变器 → EMS 方向（0x20x、0x26x 段）。

当前实现实际只用了 4 个报文：0x181（握手）、0x191（单相/DC 控制）、0x198（三相不平衡控制）、0x201 与 0x269（回读）。其余 6 个宏是预留位，说明该协议族原本规划了 AC 功率、电池限功率、电池运行数据等多条通道，但固件尚未启用。

4.2 与 uCOS-II 的配合

GINLONG_COMM_CAN_T 是纯粹的"软件定时器"载体：三个 tick 字段全部存放 OSTimeGet() 的返回值，由 ginlong_inverter_comm_can() 在每个任务周期内自行比较差值来实现分频（1 s / 600 ms / 2000 ms）。模块不使用任何信号量或消息邮箱，也无需独立任务——通信节奏由调用方（inverter.c 的逆变器轮询任务）决定，属于典型的"非阻塞节拍轮询"结构。

5. 对外接口

本文件导出：

函数：ginlong_comm_init_can(void)、ginlong_inverter_comm_can(void)（ginlong_comm_can.h:46-47）。
宏：全部 10 个报文 ID 常量与 GINLONG_INV_CAN_DEBUG。
类型：GINLONG_COMM_CAN_T。

注意：结构体 GINLONG_COMM_CAN_T 只在 .h 中定义，但对应的实例 g_t_ginlong_comm_can_info 是在 ginlong_comm_can.c:26 定义的全局变量，头文件中没有 extern 声明，因此其他文件无法直接访问该实例。

本文件（头）依赖：

includes.h：统一包含头，提供 u8/u16/u32/TRUE/FALSE 等基础类型宏。

6. 依赖关系

依赖：includes.h（唯一 include，ginlong_comm_can.h:13）。
被依赖：
- midware/inverter/ginlong/ginlong_comm_can.c（#include "ginlong_comm_can.h"，ginlong_comm_can.c:13）。
- midware/inverter/inverter.c：在 inverter_state_init() 中调用 ginlong_comm_init_can()（inverter.c:83），在逆变器轮询中调用 ginlong_inverter_comm_can()（inverter.c:1239）。

7. 备注与风险点

头文件缺少 extern 声明：g_t_ginlong_comm_can_info（ginlong_comm_can.c:26）未在头文件中导出，若 HMI 想显示 CAN 握手/发送状态将无接口可用。
大量未使用的宏：GINLONG_EMS_SET_INV_POWER_CTRL_MODE1、GINLONG_GINLONG_EMS_CTRL_INV_AC_POWER1、GINLONG_EMS_CTRL_INV_AC_POWER2、GINLONG_EMS_SET_INV_BAT_LIMIT_POWER1、GINLONG_EMS_SEND_BAT_RUN_DATA 共 5 个 ID 在 .c 中完全未引用，属于协议规划遗留。
注释模板残留：ginlong_comm_can.h 第 2-7 行的文件头注释 @brief 为空，且 ginlong_comm_can.c 中多处函数注释标题沿用自 kelong 模块（例如 ginlong_comm_can.c:53 写的是 kelong_inverter_comm），是从其他厂商模块复制后未清理的痕迹。