本文档用于case1_pv_battery_load_balance.py
。本文档介绍如何构建一个最小微电网控制案例，以及如何将函数生成的预设功率轨迹转换为逐个下发的功率指令，并传递至硬件设备，实现真实运行数据的反馈。
该案例对应一个最小微网结构： - 光伏节点：node1 -
电池节点：node2（CV=20V，仅电压控制；不直接下发功率指令） -
负载节点：node3
该案例用于展示脚本对光伏、电池及负载三类节点的协同控制能力，并在每个控制周期按照既定控制规则计算光伏和负载设定值。
本案例的控制目标是在每个控制周期内尽可能满足以下功率平衡关系：
其中： - 光伏输出功率优先用于供负载。 - 电池保持
CV-only，脚本内部只计算一个"虚拟电池功率"用于平衡判断。 -
虚拟电池功率直接等于负载需求与光伏可用功率的差额。 - 脚本不再根据 SOC
或电池功率上限调整策略，也不再因虚拟电池能力不足而限载或限光伏。
脚本内部采用以下功率符号约定： - 光伏 P_PV > 0：向母线注入功率。 -
电池 P_BAT > 0：放电到母线；P_BAT < 0：充电吸收功率。 - 负载
P_LOAD < 0：从母线取电。
因此，平衡关系写成：
脚本向设备下发控制命令时采用以下方式： -
api.node[pv_node].p = -pv_send_w -
api.node[load_node].p = -load_send_w -
api.node[battery_node].v = battery_voltage_v（CV-only）
说明： - 该案例不下发电池功率命令，避免电池同时处于 CV 与 CP。 -
电池功率只作为脚本内部虚拟量，用于平衡计算和日志展示。 -
光伏/负载功率命令仍按符号约定做负号变换。
输出启动日志及安全提示信息。
执行启动延时（默认 5
秒），为现场操作人员预留设备检查与安全确认时间。
在 for _ in loop(period_s)
主循环中，脚本在每个控制周期内执行以下流程：
pv_wave_w(t) 给出。load_wave_w(t) 给出。api.node[battery_node].v = battery_voltage_v（默认target_battery_w = load_request_w - pv_available_w。battery_virtual_w = target_battery_w。pv_available_w 下发。load_request_w 下发。sum_emulated(P+B+L) 体现平衡关系。BATT_CV_ONLY 状态标签。脚本结束后默认执行两步清理： 1. 将光伏与负载功率命令复位到 0。 2.
下发节点 shutdown 命令。
说明：这两个行为由参数控制，可按现场策略开启/关闭。
参数名 默认值 作用
run_duration_s 1800.0 案例运行时长（秒），到时自动退出；<=0
表示持续运行到手动停止。
send_hz 3.0 控制下发频率（Hz）。
start_delay_s 5.0 启动安全延时。
log_every_n 1 每多少个循环打一次日志。
pv_node 1 光伏节点号。
battery_node 2 电池节点号。
load_node 3 负载节点号。
battery_voltage_v 20.0 电池 CV 目标电压。
reset_setpoint_on_finish True 结束时是否把光伏/负载功率清零。
shutdown_on_finish True 结束时是否对三节点发送 shutdown。光伏可用功率：
特点： - 周期 120 秒。 - 区间约为 0 到 40W。
负载需求：
特点： - 周期 20 秒。 - 区间约为 10 到 30W。
这组波形让系统持续处于"有时富余、有时短缺"的切换状态，便于演示虚拟电池功率如何随光伏与负载差额变化。
sum_emulated(P+B+L)。case1_pv_battery_load_balance.py。预期看到： - sum_emulated(P+B+L) 总体接近 0。 - batt_virtual
为正时表示虚拟放电补缺口，为负时表示虚拟充电吸收富余功率。 -
状态标签保持为 BATT_CV_ONLY。
建议从以下几个方面对案例运行效果进行评估：
sum_emulated(P+B+L) 是否总体接近 0。batt_virtual 的符号和大小是否与光伏、负载差额一致。cmd 与 rx 是否趋势一致，在线状态是否稳定。shutdown_on_finish 改为False。send_hz，避免总线或设备处理压力过大。本平台仅提供脚本运行接口、样例与开发支持说明。用户基于本平台进行的脚本编写、参数配置、控制策略设计、第三方库安装与运行操作，均由用户自行评估风险并承担后果。对于因用户操作不当、参数设置错误、脚本逻辑缺陷、环境变更或第三方依赖引发的直接或间接问题，本平台不承担责任。