计划的 MQTT 控制

提示

定时 MQTT 控制用于提前发送定时消息。有关实时控制，请参见实时 MQTT 控制。

本指南将帮助您在您的 SmartgridOne Controller 上配置 MQTT，以远程控制和监控电池和太阳能电池板的安装。

您需要的

具有互联网连接的 SmartgridOne Controller。
MQTT 凭证：您可以通过发送电子邮件到 support@eniris.be 来请求此凭证。
Python 开发环境（或任何其他 MQTT 客户端）。本指南使用用 Python 编写的基本示例来帮助您入门 MQTT 和发送命令。我们建议您使用 Python，因为它易于使用，但也支持任何其他 MQTT 客户端。

额外信息

MQTT 是一种快速的互联网通信协议。它是一种发布/订阅消息系统，允许您的机器与 SmartgridOne Controller 之间建立直接连接。您的资产被分类为太阳能、电池、电动汽车和暖通空调组。目前，此集成允许按组控制，而不是按设备控制。

第一次配置（新用户的起始点）

我有一个 SmartgridOne Controller，我想为其设置 MQTT 远程控制。

1. 检查您的网络

确保您的网络允许通过 1883 端口的 MQTT 网络流量。您可以使用以下命令进行检查：

nc -zv mqtt.eniris.be 1883

如果此命令不可用，您可以选择下载并执行此 python 代码。

如有疑问，请咨询您的网络工程师，或者在发生连接错误时暂时使用您手机的 4G/5G 热点。

备注

当您的网络无法访问 1883 端口时，我们提供 80 端口的备份。这可以在本手册后面的步骤中在您的 MQTT 客户端中配置。

2. 添加您的设备

登录到调试界面并确保设备已添加到 SmartgridOne Controller。

3. 添加 MQTT 外部信号

4. 启用 MQTT 远程信号

选择您希望包含在 MQTT 远程控制中的所有设备。

5. 远程信号已添加

现在，SmartgridOne Controller 上的 MQTT 远程控制界面已被激活。

我们现在准备使用一个简单示例发送一些基本命令。状态列会告诉您是否有任何命令处于活动状态。

Python 演示脚本

一个很好的起始点是用一个简单的示例测试您新设置的集成。

此测试代码简单地持续发送以下计划：

电池：在 10 分钟内以 5 kW 的功率充电 15 分钟
太阳能：在 30 分钟内将功率设置为 0 kW，持续一个小时

SmartgridOne Controller 会以包含唯一计划标识符的确认消息做出响应，或发送错误消息。

然后我们获取这两种设备类型的下一个计划，以确认命令是否成功。

请在您首选的 Python IDE 中下载下面的文件。填写您的序列号和 MQTT 凭证，然后执行该脚本：

当上述操作成功后，您可以继续发送其他类型的消息。所有消息在下面进行了描述。

发送命令的 MQTT 文档

本节详细说明了在 SmartgridOne Controller 的网络中设置设备定时控制的 MQTT 消息格式和有效负载要求。

MQTT 主题

订阅主题：standard1/rp_one_s/remoteScheduleMetrics/<controller SN>
反馈主题：standard1/outbound/remoteScheduleMetrics/feedback/<controller SN>

其中 <controller SN> 应替换为您打算控制的 SmartgridOne Controller 的实际序列号。

MQTT 消息类型

1. 设置计划 (`set_schedule`)

为设备类型创建一个新计划。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "set_schedule",
    "fields": {
        "device_type": "<Device Type>",
        "node_id": "<Node ID>" (可选),
        "start_time": <Unix Timestamp>,
        "end_time": <Unix Timestamp>,
        "policy": "<Policy>",
        "power_setpoint_w": <Setpoint in watts>,
        "remove_overlap": <True/False> (可选) (默认=False),
        "tag": <Tag String> (可选) (默认=None),
    }
}

响应（成功）：

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "set_schedule_ack",
        "state": {
            "schedule_id": <Schedule ID>,
            "deleted_ids": <Schedulde IDs deleted if remove_overlap=True>
            "tag": <Tag String> (默认=None),
        },
        "responseCode": 0
    }
}

2. 设置多个计划 (`set_schedules`)

创建多个新计划。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "set_schedules",
    "fields": 
        "0": {
            "device_type": "<Device Type>",
            "node_id": "<Node ID>" (可选),
            "start_time": <Unix Timestamp>,
            "end_time": <Unix Timestamp>,
            "policy": "<Policy>",
            "power_setpoint_w": <Setpoint in watts>,
            "remove_overlap": <True/False> (可选) (默认=False),
        }, 
        "1": {
            "device_type": "<Device Type>",
            "node_id": "<Node ID>" (可选),
            "start_time": <Unix Timestamp>,
            "end_time": <Unix Timestamp>,
            "policy": "<Policy>",
            "power_setpoint_w": <Setpoint in watts>,
            "remove_overlap": <True/False> (可选) (默认=False),
        }, 
        ...
}

响应（成功）：

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "set_schedules_ack",
        "state": {
            "schedule_ids": <Schedule IDs>,
            "deleted_ids": <Schedulde IDs deleted if remove_overlap=True>
        },
        "responseCode": 0
    }
}

3. 获取计划 (`get_schedule`)

通过 ID 检索特定计划。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_schedule",
    "fields": {
        "id": <Schedule ID>
    }
}

响应：

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

4. 获取活动计划 (`get_active_schedule`)

检索当前活动计划的设备类型。

{
    "extraTags": {
```json
{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_active_schedule",
    "fields": {
        "device_type": "<Device Type>",
        "node_id": "<Node ID>" (可选),
    }
}

响应（成功）:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_active_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

5. 获取下一个时间表 (`get_next_schedule`)

检索设备类型的下一个即将到来的时间表。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_next_schedule", 
    "fields": {
        "device_type": "<Device Type>",
        "node_id": "<Node ID>" (可选),
    }
}

响应（成功）:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_next_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

6. 获取时间表 (`get_schedules`)

检索特定日期的所有时间表。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_schedules",
    "fields": {
        "date": "<日期字符串格式 dd/mm/yyyy>"
    }
}

响应（成功）:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_schedules_ack",
        "state": {
            "schedules": [<Schedule>, ...]
        },
        "responseCode": 0
    }
}

7. 获取未来时间表 (`get_future_schedules`)

检索所有未来的时间表。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_future_schedules",
    "fields": {}
}

响应（成功）:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_future_schedules_ack",
        "state": {
            "schedules": [<Schedule>, ...]
        },
        "responseCode": 0
    }
}

8. 移除时间表 (`remove_schedule`)

通过 ID 移除特定的时间表。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "remove_schedule",
    "fields": {
        "id": <Schedule ID>
    }
}

响应（成功）:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "remove_schedule_ack",
        "state": "时间表 <Schedule ID> 已成功移除",
        "responseCode": 0
    }
}

9. 获取现场反馈 (`get_feedback`)

检索系统状态的详细反馈。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_feedback",
    "fields": {
        "device": <Device (node) level>
    }
}

响应（成功）:

反馈负载结构

10. 现场拓扑 (`get_toplogy`)

获取现场的拓扑结构。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_topology",
    "fields": {}
}

响应（成功）:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_topology_ack",
        "state": {
            "nodeId": <nodeId>,
            "nodeType": <nodeType>,
            "children": [{<ChildObject>}]
            },
        "responseCode": 0
    }
}

标准时间表响应格式

{
    "id": <Schedule ID>,
    "device_type": "<Device Type>",
    "node_id": "<Node ID>" (可选),
    "start_time": <Unix Timestamp>,
    "end_time": <Unix Timestamp>,
    "policy": "<Schedule Policy>",
    "power_setpoint_w": <Setpoint in watts>,
    "created_at": <Unix Timestamp>
}

组件类型和政策

有关可调度的组件和政策的详细信息，请参阅实时 MQTT 控制文档中的 MQTT 组件和政策部分。

设备特定的时间表可以使用可选的 node_id 字段发送，指的是可控设备的节点 ID。

错误处理

当发生错误时，所有消息可以返回错误响应，responseCode: 1：

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "<Message Type>_ack",
        "error": <Error Body>,
        "responseCode": 1
    }
}

当发生无关错误时，消息类型将为 (general_error)。

常见错误包括：

与现有时间表重叠
时间范围无效
找不到设备类型
找不到时间表 ID
对设备类型的策略无效

时间表管理规则

重叠规则
- 同一设备类型的时间表不能重叠
- 同一设备的时间表不能重叠
- 同一设备和设备类型的时间表不能重叠
- 如果在创建新时间表时将 remove_overlap 变量设置为 True，将删除现有的重叠时间表。
每个时间表必须具有：
- 有效的设备类型
- 开始时间（Unix 时间戳）
- 结束时间（Unix 时间戳）
- 策略（与设备类型的可用策略匹配）
- 功率设定（对于需要的策略）
开始时间必须在结束时间之前
如果开始时间在过去，它将自动更改为现在开始
只有在时间表尚未开始时才能删除时间表。活动时间表不能被删除。
不同设备类型可以独立设置时间表
当时间表变为活动状态时，系统会自动应用适当的策略

您需要的​

额外信息​

第一次配置（新用户的起始点）​

1. 检查您的网络​

2. 添加您的设备​

3. 添加 MQTT 外部信号​

4. 启用 MQTT 远程信号​

5. 远程信号已添加​

Python 演示脚本​

发送命令的 MQTT 文档​

MQTT 主题​

MQTT 消息类型​

1. 设置计划 (set_schedule)​

2. 设置多个计划 (set_schedules)​

3. 获取计划 (get_schedule)​

4. 获取活动计划 (get_active_schedule)​

5. 获取下一个时间表 (get_next_schedule)​

6. 获取时间表 (get_schedules)​

7. 获取未来时间表 (get_future_schedules)​

8. 移除时间表 (remove_schedule)​

9. 获取现场反馈 (get_feedback)​

10. 现场拓扑 (get_toplogy)​

标准时间表响应格式​

组件类型和政策​

错误处理​

时间表管理规则​

您需要的

额外信息

第一次配置（新用户的起始点）

1. 检查您的网络

2. 添加您的设备

3. 添加 MQTT 外部信号

4. 启用 MQTT 远程信号

5. 远程信号已添加

Python 演示脚本

发送命令的 MQTT 文档

MQTT 主题

MQTT 消息类型

1. 设置计划 (`set_schedule`)

2. 设置多个计划 (`set_schedules`)

3. 获取计划 (`get_schedule`)

4. 获取活动计划 (`get_active_schedule`)

5. 获取下一个时间表 (`get_next_schedule`)

6. 获取时间表 (`get_schedules`)

7. 获取未来时间表 (`get_future_schedules`)

8. 移除时间表 (`remove_schedule`)

9. 获取现场反馈 (`get_feedback`)

10. 现场拓扑 (`get_toplogy`)

标准时间表响应格式

组件类型和政策

错误处理

时间表管理规则