实时 MQTT 控制
实时 MQTT 控制用于实时控制。如需提前发送计划，请参阅 计划 MQTT 控制。
本指南将帮助您在您的 Sofar EMS 上配置 MQTT 以远程控制和监控电池和太阳能电池板的安装。
您需要的内容
- 具有互联网连接的 Sofar EMS。
- MQTT 凭据：可以通过发送电子邮件至 support@eniris.be 来申请。
- Python 开发环境（或其他任何 MQTT 客户端）。本指南使用用 Python 编写的基本示例帮助您入门 MQTT 和发送命令。我们推荐使用 Python，因为它易于使用，但也支持其他 MQTT 客户端。
额外信息
MQTT 是一种快速的互联网通信协议。它是一个发布/订阅消息系统，允许您的机器与 Sofar EMS 之间建立直接连接。您的资产划分为太阳能、电池、电动车和 HVAC 组。
初次配置（新用户的起点）
我有一个希望设置为 MQTT 远程控制的 Sofar EMS。
1. 检查您的网络
确保您的网络允许通过 1883 端口进行 MQTT 网络流量。您可以使用以下命令进行检查：
nc -zv mqtt.eniris.be 1883
如果此命令不可用，您可以选择下载并执行 此 python 代码。
如有疑问，请咨询您的网络工程师，或在出现连接错误时暂时使用手机的 4G/5G 热点。
当从您的网络无法访问 1883 端口时，我们提供备用的方法在 80 端口。这可以在本手册的后续步骤中在您的 MQTT 客户端中进行配置。
2. 添加您的设备
3. 添加 MQTT 外部信号
4. 启用 MQTT 远程信号
字段 'VPP ID' 必须留空。
备份机制超时告诉 Sofar EMS 它应该等待多长时间以获取新命令。当 Sofar EMS 停止接收命令时，它在超时后会自动采用默认策略。
完成后，选择您希望包括在 MQTT 远程控制中的所有设备。
5. 远程信号已添加
现在，Sofar EMS 上已激活 MQTT 远程控制接口。
我们现在准备使用一个简单的示例发送一些基本的命令。状态列告诉您是否有命令正在活动。
Python 演示脚本
一个好的起点是通过一个简单的示例测试您新设置的集成。
此测试代码简单地工作，不断发送以下命令：
- 电池：以 5 kW 充电
- 太阳能：将功率设为 0 kW
Sofar EMS 不断以“反馈”消息响应，包含观察到的电网和资产功率值。该功能也包含在此示例中。
请在您喜欢的 Python IDE 中下载以下文件。填写您的序列号和 MQTT 凭据并执行脚本：
当上述操作成功时，您可以继续发送其他类型的命令。所有命令在我们的 MQTT 远程控制文档中都有描述。
发送命令的 MQTT 文档
本节详细说明了用于远程控制 Sofar EMS 网络内设备的电源策略的 MQTT 消息格式和有效负载要求。
MQTT 主题
用于发送命令的 MQTT 主题结构如下：
standard1/rp_one_s/remoteControlMetrics/'controller SN'
其中“controller SN”应替换为您打算控制的 Sofar EMS 的实际序列号。
MQTT 有效负载结构
命令以 JSON 有效负载发送。有 效负载结构的设计旨在为智能电网系统的不同组件指定各种电力管理策略和设定点。以下是有效负载的轮廓及详细字段描述：
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": "<Unix Timestamp>",
"fields": {
"<Component Policy>": "<Policy Type>",
"<Component Power Setpoint>": <Setpoint in watts>
}
}
字段描述
可以同时控制多种设备类型（例如电池 + 太阳能）。
- extraTags (对象):
- nodeId (字符串)：在 Sofar EMS 网络中节点的唯一标识符。这等于您的序列号，后面跟随 '_site_0'，适用于大多数 Sofar EMS 设备。
- time (整数)：以秒为单位的 Unix 时间戳，指示消息发送的时间。
- fields (对象):
- <Component>_policy (字符串)：组件的策略类型。是可选的，如果未指定，系统将回退为 Sofar EMS 的默认设置。
- <Component>_power_setpoint_w (浮点数)：组件的期望功率设定点，单位为瓦特。这是可选的，仅在指定了相应策略时相关。
组件和策略
相同类型的资产（例如两块电池）将合并为一个组件。例如，当安装两块 5 kWh 电池时，它将被视为一块 10 kWh 电池。
fields 对象中的每个组件都可以包含一个策略和一个功率设定点。可以控制以下组件：
-
solar_policy 和 solar_power_setpoint_w：
- 控制太阳能发电的政策和设定点。支持的政策：
- 策略设定点：设置所有连接的太阳能设施所产生的最大功率。字段 solar_power_setpoint_w 应设置为瓦特的生产功率限制。
- 策略进料限制：以全功率产生，遵循当前的电网限制。
- 策略成本：启用前一天价格（EPEX 现货市场）成本最小化的太阳能生产。当出现负的注入价格时，我们减少生产以供自用；当提取和注入价格均为负时，我们关闭所有太阳能设施。字段 solar_power_setpoint_w 被忽略。
- 策略关闭：禁用所有太阳能资产的所有交互。警告：在此模式下，限制不会被保护。字段 solar_power_setpoint_w 被忽略。
- 控制太阳能发电的政策和设定点。支持的政策：
-
storage_policy 和 storage_power_setpoint_w：
-
控制能量存储系统的策略和电力放电或充电速率。
- 策略设定点：为电池组设置总的充电功率（正设定点）或放电功率（负设定点）。当多个电池连接时，设定点按可用的充电/放电功率进行拆分，以均匀施加负载到电池上。字段 storage_power_setpoint_w 设置为所需的电池功率。
- 策略成本：通过在便宜的时段充电和在贵的时段使用能量来实现电池的日间价格（EPEX现货市场）成本优化。字段 storage_power_setpoint_w 被忽略。
- 策略自耗：为电池启用简单的自耗算法。多余的太阳能生产在白天储存到电池中，太阳落下时，从电池中获取能量。字段 storage_power_setpoint_w 被忽略。
- 策略关闭：禁用所有电池资产的交互。警告：在此模式下，限制没有得到保护。字段 storage_power_setpoint_w 被忽略。
-
heat_pump_policy：
- 切换热泵系统的开/关。最小和最大开启时间将始终得到遵守。
- 策略成本：为热泵启用日间价格（EPEX现货市场）成本优化。地方动态定价算法决定最佳的开启时间段。
- 策略自耗：如果产生了多余的太阳能，则开启热泵。
- 策略关机：关闭热泵。
- 策略开机：开启热泵。
- 切换热泵系统的开/关。最小和最大开启时间将始终得到遵守。
-
switched_load_policy：
- 切换继电器控制系统的开/关。这可以是内置继电器或网络连接的继电器。
- 策略成本：为继电器启用日间价格（EPEX现货市场）成本优化。
- 策略自耗：如果产生了多余的太阳能，则开启继电器。
- 策略关机
- 策略开机
- 切换继电器控制系统的开/关。这可以是内置继电器或网络连接的继电器。
-
variable_power_load_policy 和 variable_power_load_power_setpoint_w：
- 管理电动汽车的功率消费策略和设定点。
- 策略设定点：为电动汽车组设置总的充电功率。字段 variable_power_load_power_setpoint_w 设置为所需的充电功率。
- 策略成本：通过在便宜的时段进行充电，为电池启用日间价格（EPEX现货市场）成本优化。字段 variable_power_load_power_setpoint_w 被忽略。
- 策略自耗：如果产生了多余的太阳能，则启用充电。字段 variable_power_load_power_setpoint_w 被忽略。
- 策略关闭：禁用所有电动汽车资产的交互。字段 variable_power_load_power_setpoint_w 被忽略。
- 管理电动汽车的功率消费策略和设定点。
-
site_policy 和 site_power_setpoint_w：
- 管理场地出口限制。
- 策略出口：为场地设置出口限制。字段 site_power_setpoint_w 设置为出口限制。
- 策略默认：将场地限制恢复为控制器配置中设置的默认出口功率。
- 管理场地出口限制。
设备控制
特定设备也可以被控制，而不是根据其类型控制设备组。消息的结构相同：
nodeId_policy 和nodeId_power_setpoint_w
当两个命令发送到同一资产（例如，一个设备特定命令发送给太阳能逆变器，一个命令发送给所有太阳能设备）时，设备特定控制方法将优先于设备类型控制。
退回行为
对于每个组件，如果未指定 _policy 和 _power_setpoint_w，系统将自动使用在 Sofar EMS 中配置的退回策略。这确保每个设备或设备组安全运行并继续工作，即使未提供具体指令。
如果根本没有发送命令，在60秒（或配置的超时）后，资产的默认策略将重新激活。
示例载荷
以下是设置各种策略和设定点的载荷示例：
{
"extraTags": {
"nodeId": "OM12404080000000000_site_0"
},
"time": 1714652046,
"fields": {
"solar_policy": "setpoint",
"solar_power_setpoint_w": 5000,
"storage_policy": "setpoint",
"storage_power_setpoint_w": -5000
}
}
在此示例中，太阳能功率设置为最多生成5000瓦，能量存储系统设置为以5000瓦的速率充电或放电，具体取决于设定点值的符号。如果省略 solar_policy 或 storage_policy，则相应的设备将恢复为由 Sofar EMS 确定的默认设置。
MQTT 文档以接收反馈
本节概述 Sofar EMS 通过 MQTT 发送的反馈消息的结构和内容。这些消息在命令处理后发布到主题 standard1/outbound/remoteControlMetrics/feedback/<Controller SN>。
MQTT 反馈主题
反馈 MQTT 主题的结构如下：
standard1/outbound/remoteControlMetrics/feedback/<Controller SN>
其中 <Controller SN> 应替换为发送反馈的 Sofar EMS 的序列号。
MQTT 反馈载荷结构
所有资产按其类型进行分组。这意味着两个独立的3千瓦太阳能安装将被视为一个6千瓦资产。
反馈消息格式为 JSON 载荷。这些载荷提供了在应用设定点命令后系统状态的详细反馈，考虑了电网/设备限制。以下是反馈载荷的结构及其字段的描述：
{
"time": "<Unix Timestamp>",
"data": {
"state": {
"grid": {
"active_power_W": <电网有功功率（瓦特）>,
"today_imported_energy_Wh": <电网进口能量（瓦时）>,
"today_exported_energy_Wh": <电网出口能量（瓦时）>,
"import_limit_W": <电网进口限制（瓦特）>,
"export_limit_W": <电网出口限制（瓦特）>,
},
"vpp_id": "<虚拟发电厂标识符>",
"storage": {
"energy_stored_Wh": <储存的能量（瓦时）>,
"energy_capacity_Wh": <总能量容量（瓦时）>,
"mean_soc_perc": <平均充电状态百分比>,
"active_power_W": <有功功率（瓦特）>,
"executed_power_W": <发送给设备的功率设定点（瓦特）>,
"executed_policy": <控制器执行的策略>,
"max_charge_power_W": <最大充电功率（瓦特）>,
"max_discharge_power_W": <最大放电功率（瓦特）>,
"today_charged_Wh": <今天充电的能量（瓦时）>,
"today_discharged_Wh": <今天放电的能量（瓦时）>,
"nr_devices": <已安装的受控储能设备数量>
},
"solar": {
"active_power_W": <太阳能有功功率（瓦特）>,
"executed_power_W": <发送给设备的功率设定点（瓦特）>,
"executed_policy": <控制器执行的策略>,
"capacity_W": <太阳能容量（瓦特）>,
"today_energy_Wh": <今天产生的能量（瓦特时）>.
"nr_devices": <已安装的被控太阳能设备数量>
},
"heat_pump": {
"executed_policy": <控制器执行的策略>,
"operation_modes": <热泵操作模式>,
"executed_power_W": <发送到设备的功率设定点（瓦特）>,
"nr_devices": <已安装的被控热泵设备数量>
},
"switched_load": {
"executed_policy": <控制器执行的策略>,
"devices_on": <开启设备数量>,
"devices_off": <关闭设备数量>,
"executed_power_W": <发送到设备的功率设定点（瓦特）>,
"nr_devices": <已安装的被控开关负载设备数量>
}
},
"response_code": <响应代码>
},
"fields": {},
"requestTime": "<Unix时间戳>",
"time": "<Unix时间戳>",
"siteNodeId": "<控制器序列号>_site_0"
}
### 字段描述
- time (整数): Unix 时间戳，表示反馈消息发送的时间。
- fields (对象):
- state (对象):
- vpp_id (字符串): 与该设备关联的虚拟电厂标识符。
- grid (对象):
- active_power_W (浮点): 表示电网当前的有功功率（瓦特）。
- today_imported_energy_Wh (浮点): 今天从电网获取的总能量（瓦特时）。注意：今天的时间是UTC时间。
- today_exported_energy_Wh (浮点): 今天注入回电网的总能量（瓦特时）。注意：今天的时间是UTC时间。
- import_limit_W (浮点): 电网的进口限制（瓦特），
- export_limit_W (浮点): 电网的出口限制（瓦特），
- storage (对象):
- energy_stored_Wh (浮点): 当前存储的能量（瓦特时）。
- energy_capacity_Wh (浮点): 存储系统的总能量容量（瓦特时）。
- mean_soc_perc (浮点): 充电状态的百分比。这是所有连接电池的加权平均值。（当多个电池连接时：例如，电池 'a' 的能量容量为 10 kWh，充电状态为 20%；电池 'b' 的能量容量为 20 kWh，充电状态为 50%，则 mean_soc_perc 为 40%）
- active_power_W (浮点): 存储系统当前的有功功率（瓦特），显示充电或放电速率。
- max_charge_power_W (浮点): 存储充电的最大功率。
- max_discharge_power_W (浮点): 存储放电的最大功率。
- executed_power_W (浮点): 从存储资产请求的总功率之和，由我们的控制算法发送。仅在“follow_setpoint”的策略处于活动状态时 适用。
- executed_policy (字符串): 应用于可控设备的策略。
- today_charged_Wh (浮点): 今天充入可控电池资产的总能量。注意：今天的时间是UTC时间。
- today_discharged_Wh (浮点): 今天从可控电池资产放出的总能量。注意：今天的时间是UTC时间。
- nr_devices (整数): 可控电池资产的数量。
- solar (对象):
- active_power_W (浮点): 太阳能电池板当前产生的有功功率（瓦特）。
- capacity_W (浮点): 太阳能发电系统的总容量（瓦特）。
- executed_power_W (浮点): 从太阳能资产请求的总功率之和，由我们的控制算法发送。仅在“follow_setpoint”的策略处于活动状态时适用。
- executed_policy (字符串): 应用于可控设备的策略。
- today_energy_Wh (浮点): 今天从可控太阳能资产产生的总能量。注意：今天的时间是UTC时间。
- nr_devices (整数): 可控太阳能资产的数量。
- heat_pump (对象):
- executed_policy (字符串): 应用于可控设备的策略。
- operation_modes (字符串): 热泵的模式（阻塞模式，增强模式，自我控制模式）
- executed_power_W (浮点): 当前的预期功率。
- nr_devices (整数): 可控热泵的数量。
- switched_load (对象):
- executed_policy (字符串): 应用于可控设备的策略。
- devices_on (整数): 开启设备的数量。
- devices_off (整数): 关闭设备的数量。
- executed_power_W (浮点): 当前使用的功率（如果可用）。
- nr_devices (整数): 可控开/关负载的数量。
- nodeId (对象):
- 如果命令 中包含 nodeId，反馈将包含相应设备的状态。
- response_code (整数):
- 指示操作的状态。响应代码为 0 通常表示成功，而其他值可能表示不同类型的错误或状态信息（这些应在单独的参考中详细说明）。
### 示例反馈有效负载
以下是设置各种功率设定点后反馈消息的示例：
<ClickableImage src="/img/generic/mqtt-example-feedback.png" alt="图像1" maxWidth="450px" />
此反馈展示了设置点执行后的系统当前操作状态，指示对太阳能发电、储能和整体电网交互的影响。
## 支持的 MQTT 版本及未授权主题的行为
在使用 MQTT 时，考虑不同版本（3.1、3.1.1 和 5.0）之间的规范差异特别重要，尤其是关于代理在客户端发布到未授权主题时的行为。
根据 MQTT 3.1.1 规范（参见 OASIS MQTT 3.1.1 规范，第 MQTT-3.3.5-2 节），代理必须在客户端发送 PUBLISH 到未授权主题时立即终止连接。这种行为可能导致客户端在尝试发布到配置错误或未授权主题时意外断开连接。
在 MQTT 3.1 版本中，该要求并不存在。当客户端在此版本下发布到未授权主题时，代理通常会忽略该消息（无声丢弃），而不会终止连接。这使得在某些情况下，MQTT 3.1 更适合当对配置错误或暂时缺失权限的鲁棒性更重要，而不是严格的安全强制执行。
尽管 MQTT 5.0 引入了处理原因代码的能力（例如 PUBACK 具有拒绝原因），但这需要客户端和服务器双方的支持。因此，迁移到 MQTT 5.0 需要额外的实现努力。
__忽视兼容性的后果：__
如果客户端使用 MQTT 3.1.1 连接并尝试发布到未经授权的主题，代理将会突然终止会话。这可能导致不稳定、连接丢失或由于重复重新连接尝试而增加负载。
__推荐方法：__
对于客户端可能（暂时）尝试发布到未经授权的主题的系统，或者错误处理没有严格实施的情况，我们建议使用 MQTT 3.1。这可以确保更稳定的连接，并避免在运行时发生意外断开。