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

pvcharger.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 #pragma pack(1) 与寄存器映射 4.2 位域宽度的选择 4.3 PVCHARGR_MODE_E 与其它角色枚举的关系 5. 对外接口 5.1 本文件导出 5.2 本文件依赖 5.3 相关但不在本文件的宏 6. 依赖关系 7. 备注与风险点

源文件路径：midware/inverter/pvcharger.h 所属模块：midware/inverter（逆变器中间件 / PV 充电器模式）代码行数：109

1. 文件职责

本文件是 EMS"PV 充电器（PV Charger）"功能的数据契约头文件。PV 充电器指一类以光储一体机 + 外部 Modbus 主机为核心的系统形态：本机可能独立工作（单机）、作为外部主机的从机（PVCHARGR_FROM_E，数据经 Modbus 写入），或作为主机（PVCHARGR_HOST_E）。头文件定义了三种角色枚举、电池状态/电池型号两个位域联合体，以及一张完整的电池信息表 PVCHARGR_INFO_T（状态位、SOC/电压/电流/功率、充放电截止与限流、型号与额定参数）。业务实现在 pvcharger.c：模式为"从机"时该结构由外部 Modbus 主机写入，否则由本地 BMS 填充；无论哪种来源，最终都要转成 g_inverter_pvchargr_info 供 BMS 相关逻辑与 Modbus 从机寄存器读取。本文件只做类型与接口声明，不含代码。

2. 关键数据结构与宏

名称	类型	说明
`PVCHARGR_MODE_E`	枚举	PV 充电器角色：`PVCHARGR_SINGLE_E = 0`（单机 / 非从机模式）、`PVCHARGR_FROM_E`（本机为从机，电池数据来自外部 Modbus 主机）、`PVCHARGR_HOST_E`（本机为主机）。运行时取值为 `g_t_inv_info.t_config_data.u8_pv_charger_mode`
`BATTERY_STATE_U`	联合体（`u16`）	电池状态位域（共 16 bit）：`bit_bms_comm_flag:2`（BMS 通信状态）、`bit_bms_work_flag:4`（BMS 工作状态，4 bit 足够表达多档工况）、`bit_bms_relay_flag:2`（继电器状态）、`bit_bms_upgrade_flag:2`（BMS 是否正在升级/已被云端标记升级）、`bit_bat_ready_flag:2`（电池就绪/准备使能）、`bit_reserve_flag:4`（保留）。整体可按 `u16_bat_state` 一次读写，是 Modbus 寄存器 `REG_PV_CHARGER_BATTERY_STATE_E` 的映射
`BATTERY_TYPE_U`	联合体（`u16`）	电池型号：`byte.byte_battery_series`（串数/系列参数状态）、`byte.byte_battery_model`（电芯型号/储能类型）。整体可按 `u16_bat_type` 一次读写，对应 Modbus 寄存器"电池类型"
`PVCHARGR_INFO_T`	结构体（`#pragma pack(1)`）	PV 充电器电池信息表，字段顺序即 Modbus 寄存器顺序：`u_battery_state`（`BATTERY_STATE_U`）、`u16_battery_soc`、`s16_battery_volt`、`s16_battery_curr`、`s32_battery_power`、`s32_battery_max_charge_power`、`s32_battery_max_dischg_power`、`s16_battery_charge_cut_off_volt`、`s16_battery_max_charge_current`、`s16_battery_dischg_cut_off_volt`、`s16_battery_max_dischg_current`、`u_battery_type`（`BATTERY_TYPE_U`）、`u16_battery_rated_volt`、`u32_battery_rated_capacity`、`u8_battery_rated_dod`、`u16_battery_rated_volt_instant`、`u16_charge_pro_cur_step_1`、`u16_discharge_pro_cur_step_1`
`g_modbus_pvchargr_info`	全局变量（extern）	从机角色下由外部 Modbus 主机写入的原始数据，寄存器写回调逐字段填（`modbus.c:8073-8135`）
`g_inverter_pvchargr_info`	全局变量（extern）	对下游发布的最终数据，无论单机还是从机模式都收敛到此；被 `midware/interface/modbus/modbus.c:5260-5321` 作为 Modbus 从机寄存器源读取，也被 `pvcharger_read_*` 全系列（及通过它们调用者）读取
`pvcharger_send_host_machine_info`	函数声明	组帧并广播本机电池数据（`pvcharger.c:101`）
`pvcharger_from_machine_recv_sync`	函数声明	从机模式收到外部主机写帧时刷新通信心跳（`pvcharger.c:146`）
`inverter_pvcharger_info_handle`	函数声明	本模块主入口，按角色选取数据源并做限值收敛（`pvcharger.c:159`）
`pvcharger_read_machine_mode`	函数声明	读当前 PV 充电器角色
`pvcharger_read_bat_connect_state` / `_work_state` / `_relay_state`	函数声明	读电池通信/工作/继电器状态位
`pvcharger_read_bat_soc` / `_volt` / `_curr` / `_power`	函数声明	读电池 SOC / 电压 / 电流 / 功率
`pvcharger_read_bat_max_charge_power` / `_max_dischg_power`	函数声明	读电池最大充电 / 放电功率
`pvcharger_read_bat_charge_cut_off_volt` / `_max_charge_current`	函数声明	读充电截止电压 / 最大充电电流
`pvcharger_read_bat_dischg_cut_off_volt` / `_max_dischg_current`	函数声明	读放电截止电压 / 最大放电电流
`pvcharger_read_bat_series` / `_model`	函数声明	读电池串数 / 型号
`pvcharger_read_bat_rated_volt` / `_rated_volt_instant`	函数声明	读额定电压 / 瞬时额定电压
`pvcharger_read_bat_charge_pro_cur_step_1` / `_discharge_pro_cur_step_1`	函数声明	读充电 / 放电第一段限流点
`pvcharger_read_bat_rated_capacity` / `_rated_dod`	函数声明	读额定容量 / 额定 DOD（可用容量比例）

3. 函数清单

本文件为纯头文件，不含任何函数定义，仅有函数声明与全局变量 extern。

函数名	作用域	说明
`pvcharger_send_host_machine_info`	全局（声明）	主机侧：把本机电池数据用 Modbus 功能码 0x10 广播给从机
`pvcharger_from_machine_recv_sync`	全局（声明）	从机侧：收到外部主机写寄存器时刷新通信心跳标志与时间戳
`inverter_pvcharger_info_handle`	全局（声明）	本模块周期入口，由 `inverter.c` 的逆变器任务调用
`pvcharger_read_machine_mode`	全局（声明）	返回 `g_t_inv_info.t_config_data.u8_pv_charger_mode`
`pvcharger_read_bat_connect_state`	全局（声明）	返回 `bit_bms_comm_flag`
`pvcharger_read_bat_work_state`	全局（声明）	返回 `bit_bms_work_flag`
`pvcharger_read_bat_relay_state`	全局（声明）	返回 `bit_bms_relay_flag`
`pvcharger_read_bat_soc`	全局（声明）	返回 `u16_battery_soc`
`pvcharger_read_bat_volt`	全局（声明）	返回 `s16_battery_volt`
`pvcharger_read_bat_curr`	全局（声明）	返回 `s16_battery_curr`
`pvcharger_read_bat_power`	全局（声明）	返回 `s32_battery_power`
`pvcharger_read_bat_max_charge_power`	全局（声明）	返回 `s32_battery_max_charge_power`
`pvcharger_read_bat_max_dischg_power`	全局（声明）	返回 `s32_battery_max_dischg_power`
`pvcharger_read_bat_charge_cut_off_volt`	全局（声明）	返回 `s16_battery_charge_cut_off_volt`
`pvcharger_read_bat_max_charge_current`	全局（声明）	返回 `s16_battery_max_charge_current`
`pvcharger_read_bat_dischg_cut_off_volt`	全局（声明）	返回 `s16_battery_dischg_cut_off_volt`
`pvcharger_read_bat_max_dischg_current`	全局（声明）	返回 `s16_battery_max_dischg_current`
`pvcharger_read_bat_series`	全局（声明）	返回 `byte_battery_series`
`pvcharger_read_bat_model`	全局（声明）	返回 `byte_battery_model`
`pvcharger_read_bat_rated_volt`	全局（声明）	返回 `u16_battery_rated_volt`
`pvcharger_read_bat_rated_volt_instant`	全局（声明）	返回 `u16_battery_rated_volt_instant`
`pvcharger_read_bat_charge_pro_cur_step_1`	全局（声明）	返回 `u16_charge_pro_cur_step_1`
`pvcharger_read_bat_discharge_pro_cur_step_1`	全局（声明）	返回 `u16_discharge_pro_cur_step_1`
`pvcharger_read_bat_rated_capacity`	全局（声明）	返回 `u32_battery_rated_capacity`
`pvcharger_read_bat_rated_dod`	全局（声明）	返回 `u8_battery_rated_dod`

4. 核心逻辑解析

本文件无执行逻辑。其"逻辑"体现在三个层面：

4.1 `#pragma pack(1)` 与寄存器映射

第 24 行 #pragma pack(1) 覆盖到第 70 行 #pragma pack()。PVCHARGR_INFO_T 逐字节紧排，字段顺序即 Modbus 寄存器顺序，这一约定把三处代码绑在一起：

从机模式的寄存器写回调：midware/interface/modbus/modbus.c:8073-8135 按 REG_PV_CHARGER_BATTERY_STATE_E 起的寄存器号逐字段写入 g_modbus_pvchargr_info；其中 32 位字段分两次写入，用 (value << 16) | (原有低 16 位) 和 (原有高 16 位) | value 的低/高字拼接（s32_battery_power、s32_battery_max_charge_power、s32_battery_max_dischg_power 都是这个模式）。
单机/主机模式下的本地采集：pvcharger.c:44-92 按同一顺序填入 g_inverter_pvchargr_info。
主机模式的对外广播：pvcharger.c:115-136 用 for (i = 0; i < REG_PV_CHARGER_CONFIG_MAX_E - REG_PV_CHARGER_BATTERY_STATE_E; i++) 逐寄存器调 get_para_from_reg_addr()（实现在 modbus.c），即直接从"寄存器语义"取值，不直接访问结构体。

4.2 位域宽度的选择

bit_bms_work_flag:4 —— 4 bit 表达 BMS 工况（0-15 档），比 parallel.h 里同类字段的 2 bit 宽，说明 PV 充电器侧"工作状态"取值域更大。
bit_bms_upgrade_flag:2 / bit_bat_ready_flag:2 —— 实际只当布尔用（!= FALSE），2 bit 是浪费但无害。
bit_bat_ready_flag 的语义特殊：在 pvcharger.c:76-80 和 185-189 中，它为真时会强行清掉 bit_bms_comm_flag 和 bit_bms_work_flag，所以它是"电池已就绪、不需要看 BMS 通信状态"的短路标志，而不是"正常"标志。后续零限值判断（pvcharger.c:82-91）把它和"通信失败"并列，即 bit_bat_ready_flag == TRUE 也会把充放限值清零——这是"电池就绪时由 BMS 自己管"还是"就绪即禁止 EMS 干预"，需要结合 bms_get_ready_enable() 的实现理解。

4.3 `PVCHARGR_MODE_E` 与其它角色枚举的关系

PVCHARGR_SINGLE_E=0 / PVCHARGR_FROM_E=1 / PVCHARGR_HOST_E=2 与 parallel.h 的 PARALLEL_MODE_E（从机 0 / 主机 1）数值不同：并机是"从机=0"，PV 充电器是"单机=0、从机=1"。pvcharger.c 只判断 != PVCHARGR_FROM_E 与 == PVCHARGR_MODE_E 的从机分支，PVCHARGR_HOST_E 在 pvcharger.c 中没有被单独区分——主机模式与单机模式走同一段"本地采集"代码。这一点在阅读配置层（菜单/云端如何设置 u8_pv_charger_mode）时需要留意。

5. 对外接口

5.1 本文件导出

类型：PVCHARGR_MODE_E、BATTERY_STATE_U、BATTERY_TYPE_U、PVCHARGR_INFO_T。
全局变量：g_modbus_pvchargr_info、g_inverter_pvchargr_info（g_control_pvchargr_info 定义在 pvcharger.c:26 但未在此处 extern，属文件内全局）。
函数声明：第 3 节完整 24 项。
主要调用方：
- midware/inverter/inverter.c:1168 —— 调用 inverter_pvcharger_info_handle()；
- midware/interface/interface.c:328 —— 调用 pvcharger_send_host_machine_info()；
- midware/interface/modbus/modbus.c:5260-5321 —— 读 g_inverter_pvchargr_info（Modbus 从机寄存器源）；
- midware/interface/modbus/modbus.c:8073-8135 —— 写 g_modbus_pvchargr_info 并在第 8103 行调 pvcharger_from_machine_recv_sync()；
- midware/interface/modbus/modbus.c:8461,8491 —— 调 pvcharger_read_machine_mode() 判定是否处于 PVCHARGR_FROM_E。

5.2 本文件依赖

#include "chip.h" —— 提供 u8/u16/s16/s32 基础类型。

5.3 相关但不在本文件的宏

以下宏在本文件被广泛使用但定义在 midware/interface/modbus/modbus.h，说明 PV 充电器的寄存器语义归属 Modbus 模块：

PVCHARGR_BROADCAST_ADDR（modbus.h:21，值 0）
FUNC_WRITE_REGISTER（modbus.h:26，值 0x10）
REG_PV_CHARGER_BATTERY_STATE_E（modbus.h:1298，值 0x2340）
REG_PV_CHARGER_CONFIG_START_E、REG_PV_CHARGER_CONFIG_MAX_E（modbus.h:1314 附近）

6. 依赖关系

依赖：chip.h。
被依赖：
- midware/inverter/pvcharger.c（本头文件的唯一实现方）
- midware/inverter/inverter.c（调用 inverter_pvcharger_info_handle）
- midware/interface/interface.c（调用 pvcharger_send_host_machine_info）
- midware/interface/modbus/modbus.c（读写两个全局结构体、调用 pvcharger_from_machine_recv_sync 与 pvcharger_read_machine_mode）
- 间接：任何经 pvcharger_read_* 取电池限值的能量调度代码（当前工程内 pvcharger_read_* 除 pvcharger_read_machine_mode 外主要在 pvcharger.c 与 modbus.c 内自我消费）

7. 备注与风险点

g_control_pvchargr_info 未在头文件导出。它定义在 pvcharger.c:26，是"中间换算结果"（见 pvcharger.c 分析），但没有 extern 声明。若将来需要在别处读取"经过 /4 与限值收敛的中间值"，只能新增声明——目前它是隐藏的文件内全局，可读性差（应改为 static）。

同一结构体被赋予"寄存器镜像"与"业务数据"双重角色。g_modbus_pvchargr_info 是按 Modbus 寄存器顺序写入的原始镜像，PVCHARGR_INFO_T 的 #pragma pack(1) 与字段顺序同时被 3 处代码依赖（第 4.1 节）。在结构体中插入/调换字段会同时破坏 Modbus 写回调、本地采集、广播取寄存器三条路径，且没有任何版本号或校验保护。

u8_battery_rated_dod 命名与语义不符。字段名是 "rated DOD"（放电深度），而 pvcharger.c:74 用 bms_read_battery_available_capacity() 赋值，更接近"可用容量"。头文件里没有单位或量纲说明，读者必须跳到实现才知道它是从 BMS 的"可用容量"取的。

pvcharger_read_machine_mode 返回的是配置值而非运行态。它直接透传 g_t_inv_info.t_config_data.u8_pv_charger_mode，因此返回 PVCHARGR_FROM_E 只代表"配置为从机"，不代表通信正常。通信是否正常需要看 ems_set_fault_bit(22, ...) 的故障位（pvcharger.c:249），而该故障位没有对应的读取访问器导出，外部模块无法通过本头文件查询 PV 充电器通信健康度。

位域宽度与实际取值域不匹配（潜在隐患）：bit_bms_comm_flag:2 / bit_bms_relay_flag:2 / bit_bms_upgrade_flag:2 / bit_bat_ready_flag:2 都是 2 bit，可存 0-3。所有使用点一律用 == FALSE / != FALSE 判定，认为只有 0 和 1。若上游（BMS 或外部 Modbus 主机）写入 2 或 3，会被一律当成"真"，无法区分"未知/异常"与"正常"。头文件中没有为这些位定义枚举，取值语义完全缺失。

PVCHARGR_HOST_E 在实现中未被使用。枚举定义了主机角色，但 pvcharger.c 只区分"是/不是 PVCHARGR_FROM_E"，主机角色没有独立分支（顶多在 interface.c:328 处主动调用了 pvcharger_send_host_machine_info）。这属于枚举值与实现不完全对应，容易误导后续维护者。