case3_pv_battery_load_pcc.py）本文档说明 case3_pv_battery_load_pcc.py 的系统组成、功率符号、控制公式、测试波形、运行流程、默认参数和结果判读方法。该脚本构造光伏（PV）、电池、负载与公共耦合点（Point of Common Coupling，PCC）四节点案例，以电池功率补偿其余功率分量，使内部命令值满足功率平衡关系。
本文档依据脚本静态代码编制，未将未执行的注释代码、设备实测效果或现场接口行为写成既定结果。
| 节点角色 | 脚本变量 | 默认节点编号 | 当前控制内容 |
|---|---|---|---|
| 光伏 | pv_node |
1 |
按 pv_wave_w() 生成内部功率命令并写入节点 p。 |
| 电池 | battery_node |
2 |
根据功率平衡差额生成内部功率命令并写入节点 p。 |
| 负载 | load_node |
3 |
按 load_wave_w() 生成负载请求，转换为内部负功率后写入节点 p。 |
| PCC | pcc_node |
4 |
每周期写入 v = 20.0；当前不向 PCC 节点写入有功功率命令。 |
节点角色来自脚本的变量命名。具体硬件拓扑、节点与设备的现场映射以及 v、p 属性的设备侧含义，应以实际接口配置为准。
脚本在功率控制模式下采用以下内部功率平衡目标：
当前电池命令直接按差额计算：
因此，由脚本内部命令的代数关系可得：
日志中的 sum_cmd 是上述内部命令之和。该等式描述计算设定值的代数平衡，不代表设备实测功率已达到平衡。
脚本明确采用以下内部符号：
| 对象 | 内部正值含义 | 内部负值含义 |
|---|---|---|
| 光伏 | 向母线注入功率 | 脚本未生成负光伏功率 |
| 电池 | 放电并向母线注入功率 | 充电并从母线吸收功率 |
| 负载 | 不适用；脚本将负载消耗表示为负值 | 从母线消耗功率 |
| PCC | 向母线注入功率 | 从母线吸收功率；当前目标固定为 0.0 W |
负载请求 load_request_w 先转换为内部负载命令：
脚本说明 CAN 设定点 node.p 的符号与内部功率相反：
实际下发关系为：
api.node[pv_node].p = -pv_cmd_w
api.node[load_node].p = -load_cmd_w
api.node[battery_node].p = -battery_cmd_w
因此，内部注入或放电功率对应负的 node.p，内部负载吸收或电池充电功率对应正的 node.p。PCC 节点当前只设置 v = 20.0，没有执行 api.node[pcc_node].p = ...。
5 s 后发送 CAN 控制且可从用户界面停止脚本；api.sleep(5.0) 等待；Sending...；t0，初始化电池最小能量、当前能量和循环计数。初始电池能量为：
这些量是脚本中的简化能量模型值，不是设备反馈值。
主循环使用 loop(period_s)，默认周期 period_s = 1.0 s。每次迭代依次执行：
读取 api.now() 并计算累计时间 elapsed_s；
计算能量积分步长：
当 run_duration_s > 0.0 且 elapsed_s > run_duration_s 时退出循环；
计算负载请求、光伏可用功率和 PCC 目标；
向 PCC 节点写入 v = 20.0；
将全部光伏可用功率作为 pv_cmd_w，将负载请求取负作为 load_cmd_w；
按功率平衡公式计算 battery_cmd_w；
计算内部命令和 bus_sum_set_w；
对光伏、负载和电池命令取反后分别写入节点 p；
根据电池命令更新虚拟能量和 SOC；
输出时间、SOC、PCC 目标、三类内部命令、命令和及状态标签。
脚本先计算并更新 dt_s，再检查运行时长。达到结束条件的最后一次循环不会生成波形或下发新命令。
电池能量按内部电池命令积分，并限制在最小能量与满电能量之间：
SOC 由该虚拟能量计算：
内部电池功率为正时，模型能量下降；为负时，模型能量上升。由于能量被限制在 0.8 Wh 至 4.0 Wh，日志中的虚拟 SOC 范围为 20% 至 100%。
需要特别说明：当前功率控制公式不会依据 SOC、能量上下限或 battery_max_discharge_w、battery_max_charge_w 限制电池命令。能量 clamp() 只限制模型记录值，不限制实际计算或下发的 battery_cmd_w。脚本中的 SOC 保护、功率限幅和负载削减策略均位于注释代码中，当前不执行。
当前每次循环输出以下字段：
t：相对启动时间；SOC：根据命令积分得到的虚拟 SOC；pcc_target：PCC 内部目标功率；cmd[P/L/B]：光伏、负载、电池的内部功率命令；sum_cmd：四类内部功率命令之和；state=POWER_CTRL：固定状态标签。脚本定义了 get_latest_power_w()，能够尝试从节点数据中的 p1 和 online 字段获取反馈，但调用该函数的代码以及 rx、sum_rx、online 日志均已被注释。因此，当前实际运行不读取或输出节点实测功率与在线状态。
主循环正常退出后，脚本依次对节点 1、2、3、4 调用 shutdown()，随后输出：
All node shutdown, EXPERIMENT finished
脚本没有使用 try/finally。若主循环或下发过程中发生未处理异常，末尾的四次 shutdown() 不一定能够执行；实际异常处置应以运行环境和现场操作规程为准。
| 参数名 | 默认值 | 作用 |
|---|---|---|
CASE_NAME |
"EXPERIMENT" |
启动和结束日志中的案例名称。 |
run_duration_s |
18000.0 s |
主循环运行时长判断阈值，约 5 h；大于 0 时启用。 |
send_hz |
1.0 Hz |
标称发送频率。 |
period_s |
1.0 s |
由 1.0 / send_hz 计算的循环周期。 |
pv_node |
1 |
光伏节点编号。 |
battery_node |
2 |
电池节点编号。 |
load_node |
3 |
负载节点编号。 |
pcc_node |
4 |
PCC 节点编号。 |
| 启动延时 | 5.0 s |
首次进入控制循环前的固定等待时间。 |
| PCC 电压设定 | 20.0 |
每个循环写入 api.node[pcc_node].v；脚本未标注单位，按变量语义通常理解为电压值，但应以接口定义为准。 |
dt_s 下限 |
0.2 s |
电池能量积分使用的最小时间步长。 |
| 参数名 | 默认值 | 作用 | 当前是否约束功率命令 |
|---|---|---|---|
battery_voltage_v |
20.0 V |
计算虚拟满电能量。 | 否 |
battery_capacity_ah |
0.2 Ah |
计算虚拟满电能量。 | 否 |
battery_full_wh |
4.0 Wh |
由电压与容量相乘得到的虚拟满电能量。 | 否 |
battery_init_soc_pct |
50.0% |
初始化虚拟能量。 | 否 |
battery_soc_min_pct |
20.0% |
计算虚拟能量下限。 | 否，仅限制能量记录值 |
battery_soc_max_pct |
100.0% |
保留参数；仅在已注释的旧策略中引用。 | 否 |
battery_max_discharge_w |
50.0 W |
保留的旧策略放电限值。 | 否 |
battery_max_charge_w |
50.0 W |
保留的旧策略充电限值。 | 否 |
上述参数是案例脚本的模型设定，不代表设备额定能力。当前启用的控制逻辑未根据电池功率限值或 SOC 调整命令。
pv_wave_w() 的可执行代码采用 T = 200 s。定义为：
其周期为 200 s，范围为 0 W 至 35 W：前 100 s 为半正弦形功率，后 100 s 为零。函数注释写有“over 60 s”，但与实际代码 T = 200 不一致；本文以可执行代码为准。
load_wave_w() 的可执行代码采用 T = 120 s：
其周期为 120 s，范围为 0 W 至 30 W。内部负载命令为：
函数注释写有“10 s period”，但与实际代码 T = 120 不一致；本文以可执行代码为准。
pcc_wave_w() 当前始终返回：
函数内部定义的 T = 1200 未参与当前返回值计算，返回 20.0 W 的分支已被注释。因此，当前案例不执行随时间变化的 PCC 有功功率轨迹。
在当前 PCC 目标为零的条件下：
电池内部命令由同一时刻的负载请求与光伏功率共同决定。脚本不对该命令应用 50 W 充放电限值，也不根据虚拟 SOC 执行削减或停机。
在运行接口与四个节点可用的条件下，本案例可通过日志直接展示：
sum_cmd 的代数关系；POWER_CTRL 运行状态标签；shutdown 日志。当前日志不能直接展示设备实测功率、节点在线状态、PCC 实测交换功率、CAN 实际执行值或控制误差。若需验证这些结果，应结合运行接口反馈或外部测量系统。
1 至 4 与光伏、电池、负载、PCC 的映射。node.p 的符号方向是否与脚本的取反规则一致。v = 20.0，并确认该属性的单位和控制模式。run_duration_s；默认运行时长约为 5 h，另有启动前 5 s 延时。cmd[P/L/B]、sum_cmd、虚拟 SOC 和状态标签。建议在隔离测试环境中先缩短 run_duration_s，完整覆盖以下阶段：
5 s 安全等待；120 s 正弦周期；shutdown()。演示期间可重点核对以下代数关系：
同时应明确，sum_cmd 是命令计算结果，不是闭环测量结果；SOC 是虚拟模型值，不是从电池管理系统读取的 SOC。
| 观察项 | 判读建议 |
|---|---|
cmd[P/L/B] |
按光伏波形、负载负号和电池平衡公式核对内部命令。 |
sum_cmd |
理论上由代数构造得到零；浮点运算可能显示极小的数值残差。 |
SOC |
仅反映命令积分后的虚拟能量，并被限制在 20% 至 100%。 |
pcc_target |
当前应保持 0.000 W；不等同于 PCC 实测功率。 |
state |
固定显示 POWER_CTRL，不表示设备反馈确认或状态机切换。 |
| 结束日志 | 表示脚本顺序执行了四次 shutdown() 并到达末尾；仍应按现场流程确认设备状态。 |
如需判断真实功率平衡，应读取各节点测量功率并计算实测和。脚本中相关读取与日志代码当前处于注释状态。
run_duration_s = 18000.0，约为 5 h，不含启动前 5 s 延时。elapsed_s > run_duration_s，而不是大于等于。200 s、120 s 运行。get_latest_power_w() 已定义但当前未调用，实际日志没有接收功率或在线状态。T = 1200 和 20.0 W 分支当前不生效，PCC 有功目标固定为零。repeat 每周期递增，但当前启用的日志逻辑不使用该变量降低日志频率。shutdown()；未处理异常可能绕过结束阶段。shutdown() 的具体设备行为以运行接口定义为准。本文档依据 case3_pv_battery_load_pcc.py 的静态代码生成，未执行实际硬件或仿真测试。脚本中的节点编号、电压、容量、功率、SOC 和时间参数均为案例设定，不代表设备额定能力或现场安全边界。实际部署前，应依据设备手册、CAN 接口定义、节点映射、保护策略和项目操作规程完成审核与验证。