1、简介

能控云平台提供云端数据转发的通道，以便第三方平台可以同步逆变器设备的数据。本文主要介绍数据转发的方法和数据解析的格式。

MQTT —— 一种基于客户端/服务器（发布/订阅）模式的轻量级消息传输协议。

JSON —— 一种轻量级的数据交换格式。

本文档描述的内容因为版本更新，可能和实际使用有些不同。我们将会不定期更新文档，如果在使用中遇到问题，请联系我们。

2、系统框架图

3、数据消息服务说明

数据消息服务（Data Message Service，简称 DMS），是能控云平台自建的 MQTT 服务端；是一种高效、可靠、安全、便捷的消息服务。DMS 能够帮助应用开发者在他们的应用中快速集成消息能力，轻松实现设备数据的可靠转发与同步。

第三方平台需通过 MQTT 客户端与服务端建立连接，并订阅相应的主题。连接所需的 url、topic、client id、username、password 由能控云平台提供。

平台按第三方账号分配推送主题（topic），第三方账号与设备在开放平台完成绑定后，设备数据将推送至对应主题。主题规则如下：

1. 主题以 SUB/ 为前缀，示例：SUB/{deviceType}/0；
2. 同一账号可配置多个主题，多个主题以英文逗号分隔，平台推送时按设备类型（deviceType）自动匹配对应主题；
3. 主题由能控云平台统一分配，第三方不可自行修改；
4. 支持 MQTT 共享订阅：订阅 $share/{消费组名}/{主题} 时，同一消费组内的客户端轮询接收消息（每条消息只投递给组内一个客户端），不同消费组均会收到该主题推送的全量消息。

示例通过 MQTTX 客户端与服务端进行连接，具体的连接信息需与能控云平台联系获取。

1. 新建连接，Host 填写平台提供的地址和端口，Client ID 填写平台分配的 mqttId；
2. 勾选 User Credentials，Username 填写 keyId，Password 填写 keySecret；
3. 点击 Connect 连接成功后，订阅平台分配的主题（多实例负载均衡可使用 $share/{消费组名}/{主题}）；
4. 在平台绑定设备并等待设备上报后，即可在订阅窗口查看推送的 JSON 数据。

String broker  = "tcp://<url>:8091";
String clientId = "<mqttId>";
MqttClient client = new MqttClient(broker, clientId, new MemoryPersistence());
MqttConnectOptions options = new MqttConnectOptions();
options.setUserName("<keyId>");
options.setPassword("<keySecret>".toCharArray());
options.setKeepAliveInterval(60);
options.setCleanSession(true);
client.setCallback(new MqttCallbackExtended() {
    @Override
    public void messageArrived(String topic, MqttMessage message) {
        String json = new String(message.getPayload(), StandardCharsets.UTF_8);
        // 处理推送数据, 建议按 msgId 做幂等去重
    }
    // 其余回调方法按需实现 connectionLost / deliveryComplete / connectComplete
});
client.connect(options);
client.subscribe("<topic>", 1);

4、数据转发模型

data 为数据实体，不同传输类型（type）对应不同的字段结构。以下字段基于开放平台通用数据模型（逆变器/储能类设备），不同设备类型字段可能存在差异，具体以设备实际上报数据为准。

1. 推送 QoS 为 1（至少一次），网络抖动时可能收到重复消息，请以 msgId 做幂等去重；
2. 推送频率与设备上报周期一致（常见为 1 分钟～15 分钟，取决于设备型号与配置）；
3. type=1 设备额定数据在设备上电后传输一次，type=2 设备监控数据按上报间隔持续推送；
4. data.faultCodeStr 为设备故障码集合（多个故障码英文逗号分割），具体故障码含义请联系能控云获取对照表；
5. 第三方服务断线重连后（Clean Session=true）需重新发起订阅，建议采用指数退避策略重连，避免频繁重连触发服务端限制。