Victron 节点库
Node-RED 自带基础节点集。Venus OS Large 在此基础上添加了 Victron 节点库 node-red-contrib-victron，该节点库已预装。节点通过 D-Bus 工作，访问 Venus OS 提供的已连接到 GX 的设备数据。在节点中选择设备和参数；对于包含占位符的路径，例如 {tracker}，编辑器会自动将其展开为已连接设备提供的可选项。
- 更新节点库——只能随新版 Venus OS Large 一起更新。无法通过编辑器或命令行更新该节点库。即使网上已有新版节点库，也必须等待下一版 Venus OS Large；通常会在节点库更新后不久发布。
- 节点说明——GitHub 项目 wiki 中的 Input nodes、Output nodes 和 Virtual devices 页面介绍了各节点及其路径。本页的路径和值均来自该 wiki。
- 其他节点库——dashboard 等附加节点通过互联网安装到 GX 数据分区，因此在 Venus OS 更新后仍会保留。所需预留空间见首次运行。
节点类型
wiki 将 Victron 节点分为输入节点、控制节点和虚拟设备，另列出两个自定义（custom）节点。
| 类型 | 功能 | 数量 |
|---|---|---|
| 输入节点（input） | 订阅 D-Bus 上的值，并在值发生变化时发送消息。 | 33 |
| 控制节点（Control） | 将 msg.payload 中传入的值写入设备。 | 18 |
| 自定义节点（custom） | 读取和写入 D-Bus 上找到的任意服务和路径，用于其他节点未覆盖的功能。例如，内置的通过流程重启 GX 的示例使用了 Custom Control 节点。 | 2 |
| 虚拟设备 | Virtual Device 和 Virtual Switch 在 D-Bus 上创建设备；Inject Notification 和 Inject Event 分别向 GX 发送通知或向 VRM 发送事件。 | 4 |
设备节点完整列表
全部 33 个输入节点；其中 18 个也有控制版本（在 wiki 中标注“Control”）。说明依据 wiki。
| 节点 | 读取来源 | Control |
|---|---|---|
| Accharger | 交流电池充电器 | 是 |
| Acload | 由角色设为“AC load”的电能表测量的交流负载 | — |
| Acsystem | 管理 Multi RS 及未来逆变充电器的服务 | 是 |
| Alternator | 处于监控模式且类型设为“Alternator”的 BMV，或连接到 Venus OS 的车辆发电机控制器 | 是 |
| Battery | 电池状态：荷电状态（SoC）、电压、电流、报警、历史记录 | 是 |
| Dcdc | Orion XS | 是 |
| Dcload | 处于监控模式且类型设为“DC load”（直流负载）的 BMV | — |
| Dcsource | 处于监控模式且类型设为“DC source”（直流电源）的 BMV | — |
| Dcsystem | 系统中直流负载的测量值 | — |
| Dess | Dynamic ESS | 是 |
| Digitalinput | GX 数字输入——仅限在 Settings → I/O → Digital inputs 菜单中启用的输入 | — |
| Ess | ESS 储能系统 | 是 |
| Ev | 电动汽车——通过 VRM 集成的车辆，以及 Node-RED 创建的虚拟车辆 | — |
| Evcharger | 电动汽车充电桩 | 是 |
| Fuelcell | 燃料电池 | — |
| Generator | 通过继电器启动的发电机和 Fischer Panda 发电机 | 是 |
| Gps | GPS 位置 | — |
| Gridmeter | 电网电表 | — |
| Inverter | 逆变器 | 是 |
| Meteo | 太阳辐照度、温度和风传感器 | — |
| E-drive | 电力驱动装置（motordrive 服务） | — |
| Multi | Multi RS | 是 |
| Pulsemeter | 脉冲计数器——设为“Pulse meter”的数字输入 | — |
| Pump | 泵 | 是 |
| Pvinverter | 光伏并网逆变器 | 是 |
| Relay | GX 继电器，以及电池充电器和 Multi RS 的继电器 | 是 |
| Settings | 设置——目前主要用于 Carlo Gavazzi 电表 | 是 |
| Solarcharger | MPPT 太阳能充电控制器 | 是 |
| Switch | 通过 USB 连接的 I/O 扩展器 | 是 |
| 系统汇总数据（com.victronenergy.system 服务）：电池、光伏（PV）、交流用电、电网、发电机 | 系统汇总数据（服务 com.victronenergy.system）：电池、光伏（PV）、AC 用电量、电网、发电机 | — |
| Tank | 储罐液位传感器 | — |
| Temperature | 温度传感器——例如有线探头或通过蓝牙连接的 Ruuvi；也包括储罐传感器提供的温度 | — |
| Vebus | VE.Bus 设备，例如 MultiPlus 和 Quattro | 是 |
节点何时发送消息
- 每次值发生变化时——这是输入节点的基本行为。
- 勾选“only changes”时——仅在值发生变化时发送。
- 未勾选“only changes”时——节点还会每隔 5 s 发送当前值，即使值没有变化。
- 按固定时间间隔发送值——使用 change 节点将
msg.payload保存到上下文（flow.或global.），再使用 inject 节点按选定的时间间隔读取。内置示例“Only Messages at Regular Intervals”就是这样工作的。 - 重启后的上下文——默认情况下，上下文仅保存在 RAM 中，GX 重启或断电后会丢失。在文件
/data/home/nodered/.node-red/settings-user.js中可启用磁盘存储（使用localfilesystem存储；手册示例每隔 300 s 写入一次）。不要过于频繁地写入，以免损耗闪存。
控制节点的工作原理
Control 节点将 msg.payload 中的值写入设备。枚举参数（enum）使用数字设置——例如，在 Victron 示例中，inject 节点向 Vebus Control 节点发送数字 3，以开启逆变充电器。各路径对应的值见下表及 wiki。
- 定时调度——inject 节点可以在固定时间、指定日期，或在指定时间段内每隔几分钟发送一个值。Node-RED 使用 Remote Console 中设置的时区；更改时区后需要重启 Node-RED。
- 保持状态——“Event Based Scheduling”示例将 Vebus 输入节点（
/Mode）连接到控制节点，以便在计划时段内保持所选模式，即使有人意外更改了模式。 - 特殊调度——对于节假日、随机时间偏移或日落与日出调度，Victron 建议使用附加节点 node-red-big-timer（菜单 Manage palette → Install）。
常用路径
每个参数都有对应的 D-Bus 路径。编辑器会将路径中的占位符展开为已连接设备中可用的值：
| 占位符 | 含义 |
|---|---|
{type} | 开关输出类型：output_1、output_2、pwm_1、relay_1 等。 |
{tracker} | 光伏跟踪器编号：0、1、2、3 |
{phase} | AC 相位：1、2、3（L1、L2、L3） |
{day} | 历史记录日期：0 = 今天，1 = 昨天 |
{input} | AC 输入：1、2 |
{channel} | DC 通道：0、1 |
{index} | 序号：0、1、2、3 等。 |
以下是 wiki 中的部分路径，可用于根据电池状态、光伏发电量和逆变器模式实现自动化：
| 节点 | 参数与路径 | 值 |
|---|---|---|
| Battery | 荷电状态（%）——/Soc | 数值 |
| Battery | 电池电压（V）——/Dc/0/Voltage；电流（A）——/Dc/0/Current | 数值 |
| Battery | 启动电池电压（V）——/Dc/1/Voltage | 数值 |
| 系统汇总数据（com.victronenergy.system 服务）：电池、光伏（PV）、交流用电、电网、发电机 | 电池 SoC（%）——/Dc/Battery/Soc；MPPT 控制器功率（W）——/Dc/Pv/Power | 数值 |
| Solarcharger | 光伏功率（W）——/Yield/Power；光伏电压（V）——/Pv/V | 数值 |
| Solarcharger、Accharger（Control） | 电池充电器开启/关闭——/Mode | 1 On，4 Off |
| Vebus（输入与 Control） | 开关位置——/Mode | 1 Charger Only，2 Inverter Only，3 On，4 Off |
| Vebus（Control） | AC 输入电流限制（A）——/Ac/In/{index}/CurrentLimit | 数值 |
| Ess（Control） | 放电最低 SoC（%）——/Settings/CGwacs/BatteryLife/MinimumSocLimit；电网功率设定值 grid set-point（W）——/Settings/CGwacs/AcPowerSetPoint | 整数 |
| Generator（Control） | 启动发电机——/Start | 0 Stop，1 Start |
| Relay（输入与 Control） | GX 继电器——/Relay/{relay}/State；电池充电器继电器（wiki 中称为“Relay on the charger”）或 Multi RS 继电器——/Relay/0/State | 0 Open，1 Closed |
| Digitalinput | 输入状态——/State | 从 0 low 到 11 stopped，取决于输入类型 |
| Tank、Temperature | 液位（%）——/Level；温度（°C）——/Temperature | 数值 |
继电器：首先需要设置什么
要让 Node-RED 切换继电器，必须先将继电器设为手动控制，通常在 VictronConnect 中设置。随后由 Relay Control 节点控制继电器：1 闭合触点（Closed），0 断开触点（Open）。
| 继电器 | 所需设置 | Node-RED |
|---|---|---|
| GX 设备 | 在 GX 菜单中将继电器功能设为“Manually controlled”；Cerbo GX 继电器详见 Cerbo GX 页面 | 是 |
| BMV | 在 VictronConnect 中选择继电器选项 REM（Remote Controlled） | 是 |
| Lynx Shunt VE.Can | 在 GX 菜单中将继电器功能设为“Manual control” | 是 |
| MPPT 控制器 | 在 VictronConnect 中将继电器工作模式设为“manual control”；仅较大型号配有继电器 | 是 |
| RS 系列（逆变器、Multi RS） | 在 VictronConnect 中将继电器设为手动控制 | 是 |
| Smart IP43 Charger | 在 VictronConnect 中设置远程控制模式。继电器仅在电池充电器开启时供电；连接 AC 但充电器关闭时，继电器不工作（230 V 和 120/240 V 型号）。这是唯一配有可控继电器的电池充电器。 | 支持，但有限制 |
| Lynx Smart BMS | — | 否 |
| Multi、Quattro（VE.Bus） | 报警继电器和 AC-out-2 接触器——Victron 暂无计划开放其远程控制功能 | 否 |
- 发电机继电器——在 GX 控制台中将其功能设为“Generator”，然后通过 Generator Control 节点发送启动和停止指令（
/Start：1 Start，0 Stop）。对于 Fischer Panda 发电机，Generator 节点通过 D-Bus 直接启动。 - 仪表板开关——“Relay Switching”示例通过仪表板控制继电器。要让开关同时显示其他位置（例如 GX 菜单）所做的更改，还需将 Relay 输入节点连接到开关的输入端。需要安装 node-red-dashboard 节点包——参见仪表板与远程访问。
- 现成的流程——根据电池状态开启和关闭继电器：分步示例。
虚拟设备
虚拟设备可将 Victron 不支持的硬件或数据源接入 GX。在 Node-RED 中创建后，它会出现在 GX 中，并像真实的 Victron 设备一样运行，在 VRM 门户中也是如此。手册中的示例包括：将 API 天气数据作为虚拟气象站，将计算出的电网取电和馈电数据作为虚拟电网电表，将 GPSd 的位置数据作为虚拟 GPS，以及将 LoRa 或 MQTT 传感器作为虚拟储罐或温度传感器。
- 最新 Venus OS。请将 GX 更新到最新版本。
- Virtual Device 节点。将其添加到流程中，并选择设备类型。
- 数据。连接数据源或控制逻辑。向节点发送的
msg.payload应为对象：键为不带起始斜杠的 D-Bus 路径，值为读数，例如{"Dc/0/Voltage": 48.2, "Dc/0/Current": 12.5, "Soc": 85}。
- D-Bus 上的名称：
com.victronenergy.<类型>.virtual_<节点 id>. - 断开与恢复：
msg.connected = false断开设备并释放 D-Bus 上的服务名称，msg.connected = true恢复设备连接。 - 输出：一个端口——转发原始消息，其中
msg.connected被设为当前的 D-Bus 连接状态。
| 类型（wiki） | D-Bus 服务与示例路径 |
|---|---|
| AC Load | com.victronenergy.acload——/Ac/L1/Current、/Ac/Energy/Forward |
| Battery | com.victronenergy.battery——/Dc/0/Voltage、/Dc/0/Current、/Dc/0/Power、/Dc/0/Temperature |
| DC Load（直流负载） | com.victronenergy.dcload — /Dc/0/Voltage，/Dc/0/Current，/Dc/0/Power |
| E-drive | com.victronenergy.motordrive — /Dc/0/Power，/Controller/Temperature，/Coolant/Temperature |
| Electric Vehicle（电动汽车） | com.victronenergy.ev — /Soc，/TargetSoc，/ChargingState，/Ac/Power |
| Energy meter（电能表） | com.victronenergy.energymeter — /Ac/Power，/Ac/Energy/Forward，/Ac/Energy/Reverse |
| Generator | com.victronenergy.genset 或 com.victronenergy.dcgenset — /Start，/EnableRemoteStartMode，/Engine/CoolantTemperature |
| GPS | com.victronenergy.gps — /Position/Latitude，/Position/Longitude，/Fix |
| Grid meter（电网电表） | com.victronenergy.grid — /Ac/Power，/Ac/Energy/Forward，/Ac/Energy/Reverse |
| Meteo | com.victronenergy.meteo — /Irradiance，/ExternalTemperature，/WindSpeed |
| Pulse meter（脉冲计量表） | com.victronenergy.pulsemeter — /Count，/Aggregate |
| PV inverter（光伏并网逆变器） | com.victronenergy.pvinverter — /Ac/Power，/Ac/Energy/Forward，/Ac/PowerLimit |
| Tank sensor（液位传感器） | com.victronenergy.tank — /Level，/Capacity，/FluidType |
| Temperature sensor（温度传感器） | com.victronenergy.temperature — /Temperature |
虚拟开关（Virtual Switch）
创建不带实体继电器的开关，例如用于运行 Tasmota 固件的 IoT 开关，由流程根据电池状态控制。按照说明书，该开关会显示在 Venus OS 新界面的 Switch 开关面板中，可像实体开关一样开启和关闭。其状态保存在 GX 中，重启后也可保留。
- 控制：
{"SwitchableOutput/output_1/State": 1}用于开启，{"SwitchableOutput/output_1/Dimming": 75}将调光值设为 75%。msg.connected = false断开开关连接。 - 11 种类型：On/Off（0 关闭，1 开启）、Dimmable（开关及 0–100% 调光）、Temperature setpoint（以 °C 为单位的恒温器滑块）、Stepped、Basic slider、Dropdown、Numeric input、Three state（0 Off，1 On，2 Auto）、RGB color wheel、CCT wheel 和 RGB+White dimmer。
- 输出：端口 1 传递带有
msg.connected的消息；端口 2 在状态变化时发送新状态；端口 3 发送新的调光值或设定值（适用于调光、步进、数值和 RGB 类型）。
通知与事件
| 特性 | Inject Notification | Inject Event |
|---|---|---|
| 显示位置 | GX 界面中的 Venus OS 通知中心 | VRM 门户：Diagnostics → Event logs |
| D-Bus 目标 | com.victronenergy.platform，/Notifications/Inject | com.victronenergy.logger，/EventLogging/Inject |
| 严重级别 | 0 Warning（警告），1 Alarm（报警），2 Information（信息） | 0 Warning（警告），1 Critical（严重），2 Info（信息） |
| 内容 | msg.payload；标题取自配置或 msg.title，类型取自配置或 msg.type（数字或“warning”、“alarm”、“info”） | msg.payload；来源名称（App）取自配置或 msg.app，严重级别取自配置或 msg.severity（数字或“warning”、“critical”、“info”，不区分大小写） |
| 限制 | 标题最多 100 个字符，正文最多 500 个字符，超出部分会被截断 | — |
| 输出 | 添加了 msg.notification 的原始消息 | 添加了 msg.event 的原始消息 |
内置示例
在编辑器中：右上角菜单 → Import（或 Ctrl+I）→ Examples → node-red-contrib-victron。Wiki 的 Example Flows 页面也提供相同示例。部分示例需要额外的节点包，最常用的是 node-red-dashboard。
| 示例 | 演示内容 |
|---|---|
| Trigger Based Scheduling | 在固定时间开启和关闭逆变充电器（inject + Vebus Control） |
| Event Based Scheduling | 在计划时段内保持选定的逆变器模式 |
| Combining Inputs / Night Time Rate Battery Charging | 根据 Battery 节点的 SoC 选择 Quattro 模式：低于 25% 时随时充电；25–50% 时夜间充电，白天由电池供电（Inverter Only）；高于 50% 时由电池供电 |
| Brightness-Based Lamp Control | 通过继电器控制灯：SmartSolar 控制器的 PV 电压低于 5 V 持续 60 s 时开灯；天色不再昏暗后，延迟 30 min 关灯 |
| Temperature Dashboard | 在仪表板上显示传感器温度，四舍五入至小数点后 1 位 |
| Location Based Scheduling | 根据 USB GPS 提供的位置，在黄昏和黎明控制继电器（BigTimer 节点） |
| Monitor Disk Usage, MQTT Disk Space Monitoring | 通过 df 命令或 MQTT 监测 GX 存储空间占用 |
| Relay Switching | 通过仪表板切换继电器 |
| Solar Forecasting | 使用 forecast.solar 服务预测光伏发电量 |
| Threshold Control | 超过 ON 阈值时开启输出，低于 OFF 阈值时关闭输出，并设置延时；示例来自 Victron 网络研讨会 |
| Load Shedding and MinSOC | 根据电网停电预告设置 ESS 的最低 SoC（南非 EskomSePush API） |
| Only Messages at Regular Intervals | 通过上下文按固定时间间隔发送数值 |
| Run Generator at Certain Time | 每天 18:00：若 SoC 低于 50%，发电机运行 45 min |
| Venus Reboot | 在流程中使用 Custom Control 节点重启 GX |
资料之间的差异
- 虚拟设备类型。Venus OS Large 说明书（第 5.8 节）列出 9 种：Battery、Generator、GPS、Grid meter、Meteo、Motor drive、PV inverter、Tank sensor 和 Temperature sensor。Wiki（Virtual devices）列出 14 种：增加了 AC Load、DC Load、Electric Vehicle、Energy meter 和 Pulse meter，且“Motor drive”称为 E-drive（服务为 com.victronenergy.motordrive）。您可在 Virtual Device 节点的类型列表中查看当前可用类型。
- 虚拟开关的显示位置。说明书：Venus OS 新界面的开关面板。Wiki：Venus OS 将其识别为已连接的 Cerbo GX I/O 扩展器，可通过 GX 界面操作。
- 消息接收频率。FAQ Q9 和“Only Messages at Regular Intervals”示例：每次变化时发送，未启用“only changes”时还会每隔 5 s 发送一次。“Event Based Scheduling”示例：默认每隔 5 s 发送一次，发生变化时立即发送，即“约每秒一次”。
- “Trigger Based Scheduling”中的时间。说明文字：6:00 开启，22:00 关闭。但流程中的“Trigger 'ON' at 22:00”节点在 22:00 发送 3（On），而“Trigger 'OFF' at 6:00”在 6:00 发送 4（Off）。导入后，请检查 inject 节点中的时间和值。
- 节点包更新。第 5.3 节和 FAQ Q2：Victron 节点包无法通过编辑器或命令行更新，只能通过新版 Venus OS Large 更新。第 5.6 节泛指安装比预装版本更新的节点包后，Node-RED 会使用较新版本。对于 Victron 节点包，说明书在 Q2 中明确指出：只能通过新版 Venus OS Large 更新。
- 占位符。wiki 图例列出了 {type}、{tracker}、{phase}、{day}、{input}、{channel} 和 {index}，但路径说明中还使用了 {relay}（
/Relay/{relay}/State）、{line}（System 节点中的/Ac/Consumption/{line}/Power）和 {historyDay}（Solarcharger 节点中的/History/Daily/{historyDay}/Yield）。
控制会立即生效
一旦部署流程（Deploy），Control 节点就会更改逆变器模式、电流限制、ESS 设置和继电器状态。对于使用 Node-RED 实现高级功能的系统，Victron 不提供技术支持；请您在有人监护的情况下，在系统上测试新流程。导致 GX 过载的流程可在安全模式下停用：安全模式与重启。
适用设备
资料来源
- node-red-contrib-victron wiki — 可用节点github.com · EN
- node-red-contrib-victron wiki — 输入节点github.com · EN
- node-red-contrib-victron wiki — 输出节点github.com · EN
- node-red-contrib-victron wiki — 虚拟设备github.com · EN
- node-red-contrib-victron wiki — 示例流程github.com · EN
- Venus OS Large 镜像：Signal K 与 Node-RED — 第 2、5.3–5.8 章，FAQ Q2、Q9、Q11victronenergy.com · EN