ginlong_comm_usart.h

源文件路径：midware/inverter/ginlong/ginlong_comm_usart.h 所属模块：midware / inverter / ginlong（锦浪（Solis）逆变器 Modbus-RTU 通信） 代码行数：935

1. 文件职责

本文件是 EMS 与锦浪（Ginlong/Solis）储能逆变器 Modbus-RTU 串口主通道 的对外契约与数据定义中心。它把逆变器侧全部需要用到的 Modbus 寄存器地址、功能码、型号子码、国家安规码、故障位域、运行/配置参数结构体集中定义，并通过 extern GINLONG_TABLE_T g_t_ginlong_info 向整个工程暴露唯一的一份"锦浪通道状态表"。

实现体全部在 ginlong_comm_usart.c 中；本文件只提供类型、宏和 4 个函数原型。数据流位置：inverter.c 的逆变器轮询任务调用 ginlong_inverter_comm() → 该实现按寄存器表收发 → 结果写入 g_t_inv_info（对外统一运行数据）与 g_t_ginlong_info（锦浪私有缓存/标志位）→ 上层调度与显示读取。

g_t_ginlong_info 中的 t_ginlong_comm_info 是一张巨大的"待办标志位表"（约 50 个 u8/u16 命令与查询请求标志），实现了上层（HMI、服务器、并机、BMS）与本文件的异步解耦：上层只置标志，本文件在轮询里消费标志并发帧。

2. 关键数据结构与宏

2.1 宏常量

输入寄存器地址宏（3xxxx，只读取）

保持寄存器地址宏（4xxxx，可读可写）

2.2 枚举

2.3 位域联合体（逆变器故障/状态字）

均为 union { u16 u16_all; struct { u8 b0..b15 : 1; } bit; } 形式，可用 u16_all 整体判零、也可逐位读：

2.4 结构体

2.5 导出的全局变量

3. 函数清单

本文件为头文件，不含函数实现，仅声明 4 个函数原型（ginlong_comm_usart.h:930-933）：

说明：.c 中还有约 60 个非 static 函数（如 set_safety、set_inv_ac_actpower、query_inv_product_model 等）未在本头文件中声明，它们由 ginlong_comm_usart.c 自身调用或经 inverter.h 间接暴露，属于头文件声明不完整的遗留问题（详见第 7 节）。

4. 核心逻辑解析

本文件是纯声明文件，不含控制流，但其中的常量取值与结构体布局本身就是协议契约，解析如下：

4.1 Modbus-RTU 帧格式约定

本文件定义的功能码与寄存器地址直接决定 .c 的组帧方式：

• 读请求（0x03/0x04）8 字节：[从机地址][功能码][起始地址高][起始地址低][数量高][数量低][CRC低][CRC高]
• 写单寄存器（0x06）8 字节：[从机地址][0x06][地址高][地址低][数据高][数据低][CRC低][CRC高]
• 写多寄存器（0x10）7+2N+2 字节：[从机地址][0x10][地址高][地址低][数量高][数量低][字节数=2N][数据…][CRC低][CRC高]
• CRC 为 Modbus 标准 CRC16，低字节在前（构造见 ginlong_comm_usart.c:327-328）
• GINLONG_MAX_REGISTER_NUM = 100 是单次写多寄存器的硬上界，ems_send_ctrl_data_to_ginlong() 会用它做参数校验，因此本文件中所有 NUM_* 宏都不允许超过 100。

4.2 两类机型与两套安规码表

GINLONG_H_NATIONAL_STANDARD_E 与 GINLONG_L_NATIONAL_STANDARD_E 是同一批安规在不同硬件代次上的两套编码：H 表用于 T10（高压三相机型，SUB_T10），L 表用于 S5/B5/S3.6/S4.6/S6（低压机型）。两表的编码值并不一一对应（例如 H 表 GL_H_AS4777_A = 0x64，L 表 GL_L_AS4777_A = 0x55），因此 .c 中必须有 exchange_safety() / exchange_safetysub() 两张转换表，用 SAFETY_E 枚举的 GINLONG_SAFETY（逆变器→EMS）与 STANDARD_SAFETY（EMS→逆变器）区分方向。

4.3 命令标志位表（GINLONG_COMM_INFO_T）的设计

该结构体是本文件最重要的接口设计，其约定为：

"置位—消费—复位"是唯一同步机制，没有信号量或邮箱保护；因此所有置位方必须与 .c 运行在同一任务上下文（实际都在 inverter.c 的逆变器任务里），否则存在竞态。

4.4 单位与精度约定

本文件注释给出了逆变器侧与 EMS 侧的单位换算关系，.c 的乘除系数全部来源于此：

4.5 与 uCOS-II 的配合

本文件不涉及任务、信号量或邮箱，但结构体中的 u32_*_tick 字段全部以 OSTimeGet() 的系统节拍（ms）为基准，并依赖 .c 中的回绕兜底逻辑（if (tick > OSTimeGet()) tick = OSTimeGet();）。

5. 对外接口

本文件导出（供外部调用）：

本文件调用的外部接口：

6. 依赖关系

依赖（include）： includes.h（ginlong_comm_usart.h:13）、ginlong_upgrade.h（:14）。依赖极少，是设计良好的地方——头文件不引入其他业务头。

被依赖：

• midware/inverter/ginlong/ginlong_comm_usart.c —— 唯一实现体。
• midware/inverter/ginlong/ginlong_comm_can.c —— 使用 g_t_ginlong_info.t_ginlong_comm_info.u8_ems_inv_comm_flag 判断串口通道是否已建立（ginlong_comm_can.c:302）。
• midware/inverter/ginlong/ginlong_comm_can.h —— 间接经由 ginlong_comm_usart.h。
• midware/inverter/inverter.c —— 大量置位 g_t_ginlong_info 中的请求标志（约 60 处），并调用 4 个导出函数。
• user/EMS_3_0.uvprojx —— 编译单元注册。

7. 备注与风险点

1. 文件头注释与实际文件名不符：ginlong_comm_usart.h:2 写的是 @file :ginlong_comm.h，实际文件名已改为 ginlong_comm_usart.h（推测是串口/CAN 双通道拆分时的遗留），版本仍标 V1.0.0 / 2017/06/28，与实际内容（含 2023 年后新增的意大利自检、FRT、阴影扫描等）严重脱节。
2. 头文件声明严重不完整：.c 中约 60 个非 static 函数（set_safety、set_inv_ac_actpower、query_inv_rundata_1/2、inv_on_off_command 等）未在此声明。它们能被 inverter.c 调用，是因为 inverter.h 另有声明；但这导致本头文件不能独立反映模块接口，且漏掉了编译期原型检查（C89 下隐式声明会静默通过，一旦实参类型写错不会报错）。
3. ITALY_SAFTY_TEST_RESULT_U 位域数目异常：ginlong_comm_usart.h:664-687 的匿名结构体里，u8_test_ufp2_time_result 出现了两次（:686 与前面的 :684 重名，且总位数 17 位 > u16 的 16 位）。重复成员名在 C 中是非法/未定义的，多出的第 17 位会被丢弃。该联合体在 .c 中只用 u16_all（ginlong_comm_usart.c:3812-3814、:4006-4008），未访问 bit 域，所以目前不产生功能问题，但属于明显的复制粘贴缺陷。
4. GINLONG_DEBUG_TABLE_T 已是死代码：唯一成员 s32_ginlong_debug_1 的赋值代码在 .c 中已被注释（ginlong_comm_usart.c:1597-1604），结构体本身保留。
5. NUM_FREQ_DERATING_PROTECT_VALUE 被从 2 改成 1（:160-161 保留了旧值注释），对应 43227/43228 只能单寄存器写（.c:3195 注释"多寄存器写入写不进去"），说明逆变器固件行为变化后只在 EMS 侧打补丁，未更新协议文档。
6. ADDR_REGISTER_RUNDATA_1 与 ADDR_PV_ENERGY_STATISTICS 同为 33029、ADDR_SET_WORK_MODE 与 ADDR_SAFETY_REGULATIONS_INFO 同为 43050、ADDR_REGISTER_BMS_PROTECT_PARAMETER 与 ADDR_CONTROL_BACKUP_BAT_ENABLE 同为 43111。这是同一寄存器区被不同功能复用的正常现象，但宏名容易误导，阅读 .c 时需按 NUM_* 长度判断实际读写范围。
7. u8_inv_backup_status（GINLONG_RUNDATA_TABLE_T）语义反直觉：.c 中存的是 寄存器原值 + 1（ginlong_comm_usart.c:1583），因此 0 表示未读到、1/2 才是 BACKUP_* 枚举值，与 t_control_cmd.u8_backup_set 的比较必须做 -1 处理，极易出错。
8. GINLONG_COMM_INFO_T 无任何并发保护：所有请求标志由上层（inverter.c）置位、由本模块消费，若将来有第二个任务写入（例如 HMI 任务直接改变配置并置标志），会出现"标志被同一轮消费两次"或"写请求丢失"。当前设计假设单任务，缺少注释说明这一约束。
9. exchange_safety() 对未知子机型返回 0：函数体只有 SUB_T10 与 SUB_S5/B5/S3.6/S4.6/S6 两个分支（ginlong_comm_usart.c:345、:545），其余 sub 值直接返回 l_u16_safety = 0，即"未知安规码"。若新增机型而忘记在此处扩展，安规读取会静默变成 0 而不是报错。