MQTT协议

MQTT连接参数

Keep Alive: 60s
Clean Start: 0

限制

设备上送数据每条报文大小大于1M可能会导致数据解析有误，建议分包处理

MQTT连接鉴权

clientId: ${ProductKey}+"&"+${DeviceKey}
username: ${ProductKey}+"&"+${DeviceKey};${timestamp:毫秒}
password: hmacsha256(密钥:${deviceSecret},摘要正文: ${timestamp})

Topic

Topic 说明

上行 Topic 指的是设备往平台发送消息下行 Topic 指的是应用往设备发送消息

数据压缩

针对长消息协议支持数据压缩传输, 可以通过压缩处理后传输数据，达到节约设备流量和提高传输速度的效果。

数据压缩的 Topic 说明

常规Topic添加 /gzip 后缀, 同时对请求正文使用Gzip压缩后，再进行发送，云平台会完成解压缩后处理。
示例:
设备属性上报: $thing/up/property/{productKey}/{DeviceKey}/gzip
请求数据格式（发送前需对以下JSON进行gzip压缩）:

json

{
  "msgId": "123",
  "method": "report",
  "ts": 1628646783000,
  "params": {
    "power_switch": 1,
    "brightness": 32
  }
}

网关代理上下线

功能概述

网关类型的设备，可通过与云端的数据通信，代理其下的子设备进行上线与下线操作。

数据上行 Topic（用于发布）：$gateway/operation/up/${ProductKey}/${DeviceKey}
数据下行 Topic（用于订阅）：$gateway/operation/down/${ProductKey}/${DeviceKey}

代理子设备上线

网关类型的设备，可以通过数据上行 Topic 代理子设备上线。请求成功之后，云端通过数据下行 Topic 返回子设备的上线结果信息。网关代理子设备上线请求数据格式：

json

{
  "type": "online",
  "msgId": "123",
  "ts": 1628646783000,
  "payload": {
    "devices": [
      {
        "productKey": "CFC******AG7",
        "deviceKey": "subdeviceaaaa"
      }
    ]
  }
}

代理子设备上线响应数据格式：

json

{
  "type": "online",
  "msgId": "123",
  "payload": {
    "devices": [
      {
        "productKey": "CFC******AG7",
        "deviceKey": "subdeviceaaaa",
        "result": 0 
      }
    ]
  }
}

请求参数字段说明:

字段	类型	描述
type	String	设备上下线状态, 上线:online, 下线:offline
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
ts	Long	上线时间毫秒时间戳
payload	Object	参数信息
payload.devices	Array	设备信息列表
payload.devices.productKey	String	子设备的产品Key
payload.devices.deviceKey	String	子设备的Key

响应参数字段说明:

字段	类型	描述
type	String	对应请求对应的type
msgId	String	对应请求的msgId, 做关联使用
payload	Object	参数信息
payload.devices	Array	设备信息列表
payload.devices.productKey	String	子设备的产品Key
payload.devices.deviceKey	String	子设备的Key
payload.devices.result	Integer	子设备上线结果, 0为成功, 具体错误码见下表

代理子设备下线

网关类型的设备，可以通过数据上行 Topic 代理子设备下线。请求成功之后，云端通过数据下行 Topic 返回成功子设备的下线信息。
网关代理子设备下线请求数据格式：

json

{
  "type": "offline",
  "msgId": "123",
  "ts": 1628646783000,
  "payload": {
    "devices": [
      {
        "productKey": "CFC******AG7",
        "deviceKey": "subdeviceaaaa"
      }
    ]
  }
}

网关代理子设备下线响应数据格式：

json

{
  "type": "offline",
  "msgId": "123",
  "payload": {
    "devices": [
      {
        "productKey": "CFC******AG7",
        "deviceKey": "subdeviceaaaa",
        "result": 0 
      }
    ]
  }
}

请求参数说明:

字段	类型	描述
type	String	设备上下线状态, 上线:online, 下线:offline
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
ts	Long	上线时间毫秒时间戳
payload	Object	参数信息
payload.devices	Array	设备信息列表
payload.devices.productKey	String	子设备的产品Key
payload.devices.deviceKey	String	子设备的Key

响应参数说明:

字段	类型	描述
type	String	对应请求对应的type
msgId	String	对应请求的msgId, 做关联使用
payload	Object	参数信息
payload.devices	Array	设备信息列表
payload.devices.productKey	String	子设备的产品Key
payload.devices.deviceKey	String	子设备的Key
payload.devices.result	Integer	子设备上线结果, 0为成功, 具体错误码见下表

错误码

错误码	描述
0	成功
1	网关设备未绑定该子设备
2	系统错误，子设备上线或者下线失败

代理子设备发布和订阅

功能概述

网关类型的设备，可通过与云端的数据通信，代理其下的子设备发布和订阅消息。

发布和订阅消息

网关产品与子产品建立绑定，获取子设备的 Topic 权限后，网关设备可以使用子设备Topic代理进行收发消息。

设备属性上报

数据上行 Topic（用于发布）：$thing/up/property/{productKey}/{DeviceKey}
数据下行 Topic（用于订阅）：$thing/down/property/{productKey}/{DeviceKey}
请求数据格式：

json

{
  "msgId": "123",
  "method": "report",
  "ts": 1628646783000,
  "params": {
    "power_switch": 1,
    "brightness": 32
  }
}

响应数据格式:

json

{
    "method":"report_reply",
    "msgId":"123",
    "code":0,
    "status": ""
}

请求参数说明:

字段	类型	描述
method	String	report表示属性上报, 固定值.
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
ts	Long	设备上报的时间. 毫秒时间戳
params	Object	设别上报的属性值
params.power_switch	Boolean	布尔值一般为true/false
payload.brightness	Integer	整数型的属性为整数值

响应参数说明:

字段	类型	描述
method	String	report_reply 表示属性上报的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

设备属性上报数据压缩

针对较多属性上报时可通过压缩数据以达到节省设备流量和提高传输速度的效果。
具体可参见数据压缩说明
数据上行 Topic（用于发布）：$thing/up/property/{productKey}/{DeviceKey}/gzip

请求数据格式和正常格式无区别, 如下所示。发送前需对整个JSON进行gzip压缩后再发送：

json

{
  "msgId": "123",
  "method": "report",
  "ts": 1628646783000,
  "params": {
    "power_switch": 1,
    "brightness": 32
  }
}

属性设置

当通过云端控制设备时, 设备需订阅下行Topic接收云端指令:
下行 Topic： $thing/down/property/{ProductKey}/{DeviceKey}
上行 Topic： $thing/up/property/{ProductKey}/{DeviceKey}
下行数据格式:

json

{
  "msgId": "123",
  "method": "control",
  "ts": 1628646783000,
  "params": {
    "power_switch": 1,
    "color": 1,
    "brightness": 32
  }
}

上行数据格式:

json

{
  "msgId": "123",
  "method": "control_reply",
  "code": 0,
  "status": ""
}

请求参数说明:

字段	类型	描述
method	String	control 表示属性设置, 固定值.
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
ts	Long	指令下发的时间. 毫秒时间戳
params	Object	设备属性的设置值

响应参数说明:

字段	类型	描述
method	String	control_reply 表示属性设置的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

网关批量上报

网关类型设备, 为子设备和自身通过批量的形式快速上报属性变更信息.
上行Topic: $thing/up/property/gateway/{ProductKey}/{DeviceKey}
下行Topic: $thing/down/property/gateway/{ProductKey}/{DeviceKey}
请求数据格式:

json

{
  "msgId": "123",
  "method": "report",
  "ts": 1212121221,
  "params": {
    "properties": {
      "values": {
        "power_switch": 1,
        "color": 1,
        "brightness": 32
      },
      "ts": 1212121221
    },
    "subDevices": [
      {
        "productKey": "",
        "deviceKey": "",
        "properties": {
          "values": {
            "power_switch": 1,
            "color": 1,
            "brightness": 32
          },
          "ts": 1212121221
        }
      }
    ]
  }
}

响应数据格式:

json

{
  "msgId": "123",
  "method": "report_reply",
  "code": 0,
  "status": ""
}

请求参数说明:

字段	类型	描述
method	String	report 表示属性上报, 固定值.
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
ts	Long	请求的时间. 毫秒时间戳
params	Object	设备属性的设置值
params.properties	Object	网关设备自身的属性变更
params.properties.ts	Long	属性变更时间点. 毫秒时间戳
params.properties.values	Map	网关设备上报的属性值
params.subDevices	Array	网关子设备属性值列表
params.subDevices.productKey	String	子设备产品Key
params.subDevices.deviceKey	String	子设备Key
params.subDevices.properties	Object	子设备属性值信息
params.subDevices.properties.ts	Long	子设备属性变更时间
params.subDevices.properties.values	Map	子设备属性值, KV对

响应参数说明:

字段	类型	描述
method	String	report_reply 表示属性设置的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

服务调用

应用调用设备行为(下行) Topic： $thing/down/service/{ProductKey}/{DeviceKey}
设备响应行为执行结果(上行) Topic： $thing/up/service/{ProductKey}/{DeviceKey}
下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "openDoor",
  "ts": 1212121221,
  "params": {
    "userid": "323343"
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",
  "code": 0,
  "status": "some message where error",
  "response": {
    "Code": 0
  }
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
ts	Long	请求的时间. 毫秒时间戳
serviceId	String	物模型中的service标识符. 由物模型中定义.
params	Object	物模型中service定义的请求参数

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述
response	Object	物模型中service定义的响应参数

削峰填谷数据

下发控制

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "peakShaving",
  "ts": 1212121221,
  "params": {
    "strategyName": "策略名称",
    "startDate": "2024-07-01",
    "endDate": "2024-07-30",
    "maxChargingPower": 0,
    "maxDischargePower": 0,
    "socUpperLimit": 95,
    "socLowerLimit": 5,
    "status": 1,
    "strategyParam": [
      {
        "startTime": "00:00",
        "endTime": "01:00",
        "pattern": 0,
        "activePower": 100
      }
    ]
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error"
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	削峰填谷固定peakShaving
ts	Long	毫秒时间戳
params	Object	请求参数
params.strategyName	String	策略名称
params.startDate	String	开始时间, 必须小于结束时间
params.endDate	String	解释时间, 必须大于开始时间
params.maxChargingPower	Int	最大充电功率：默认0 单位:W
params.maxDischargePower	Int	最大放电功率：默认0 单位:W
params.socUpperLimit	Int	SOC上限：默认0
params.socLowerLimit	Int	SOC下限：默认0
params.status	Int	策略启用状态：不传默认启用 1-启用 0-禁用
params.strategyParam	Array	策略配置参数
params.strategyParam.startTime	String	开始时间：间隔15分钟、需要小于结束时间时间格式00:15、00:30
params.strategyParam.endTime	String	结束时间：间隔15分钟、需要小于开始时间时间格式00:15、00:30
params.strategyParam.pattern	Int	模式 1-充电 2-待机 3-放电
params.strategyParam.activePower	Int	有功功率单位:W

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

获取策略

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "getPeakShaving",
  "ts": 1212121221,
  "params": {
    "startDate": "2024-07-01",
    "endDate": "2024-07-30"
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error",
  "response": {
    "strategy":[
      {
        "strategyName": "策略名称",
        "startDate": "2024-07-01",
        "endDate": "2024-07-30",
        "maxChargingPower": 0,
        "maxDischargePower": 0,
        "socUpperLimit": 95,
        "socLowerLimit": 5,
        "strategyParam": [
          {
            "startTime": "00:00",
            "endTime": "01:00",
            "pattern": 0,
            "activePower": 100
          }
        ]
      }
    ]
  }
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	削峰填谷固定getPeakShaving
ts	Long	毫秒时间戳
params	Object	请求参数
params.startDate	String	开始时间, 必须小于结束时间
params.endDate	String	解释时间, 必须大于开始时间

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述
response	Object	响应参数
response.strategy	Array	策略列表
response.strategy.strategyName	String	策略名称
response.strategy.startDate	String	开始时间, 必须小于结束时间
response.strategy.endDate	String	解释时间, 必须大于开始时间
response.strategy.maxChargingPower	Int	最大充电功率单位:W
response.strategy.maxDischargePower	Int	最大放电功率单位:W
response.strategy.socUpperLimit	Int	SOC上限
response.strategy.socLowerLimit	Int	SOC下限
response.strategy.strategyParam	Array	策略配置参数
response.strategy.strategyParam.startTime	String	开始时间：间隔15分钟、需要小于结束时间时间格式00:15、00:30
response.strategy.strategyParam.endTime	String	结束时间：间隔15分钟、需要小于开始时间时间格式00:15、00:30
response.strategy.strategyParam.pattern	Int	模式 1-充电 2-待机 3-放电
response.strategy.strategyParam.activePower	Int	有功功率单位:W

防逆流

下发控制

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "antiReflux",
  "ts": 1212121221,
  "params": {
    "strategyName": "策略名称",
    "startDate": "2024-07-01",
    "endDate": "2024-07-30",
    "refluxThresholdValue": 1,
    "refluxMaxValue": 1,
    "refluxMinValue": 1,
    "refluxStatus": 1,
    "executionInterval": 60
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error"
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	防逆流固定antiReflux
ts	Long	毫秒时间戳
params	Object	请求参数
params.startDate	String	开始时间, 必须小于结束时间
params.endDate	String	结束时间, 必须大于开始时间
params.strategyName	String	策略名称
params.refluxThresholdValue	String	防逆流阈值
params.refluxMaxValue	String	防逆流死区上限
params.refluxMinValue	Int	防逆流死区下限
params.refluxStatus	Int	防逆流启用状态：不传默认启用 1-启用 0-禁用
params.executionInterval	Int	执行间隔：单位秒，不传默认60秒

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

获取策略

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "getAntiReflux",
  "ts": 1212121221,
  "params": {
    "startDate": "2024-07-01",
    "endDate": "2024-07-30"
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error",
  "response": {
    "strategy": [
      {
        "strategyName": "策略名称",
        "startDate": "2024-07-01",
        "endDate": "2024-07-30",
        "refluxThresholdValue": 1,
        "refluxMaxValue": 1,
        "refluxMinValue": 1,
        "executionInterval": 60
      }
    ]
  }
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	防逆流固定getAntiReflux
ts	Long	毫秒时间戳
params	Object	请求参数
params.startDate	String	开始时间, 必须小于结束时间
params.endDate	String	结束时间, 必须大于开始时间

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述
response	Object	响应参数
response.strategy	Array	策略列表
response.strategy.strategyName	String	策略名称
response.strategy.startDate	String	开始时间, 必须小于结束时间
response.strategy.endDate	String	结束时间, 必须大于开始时间
response.strategy.refluxThresholdValue	Int	防逆流阈值
response.strategy.refluxMaxValue	Int	防逆流死区上限单位:W
response.strategy.refluxMinValue	Int	防逆流死区下限单位:W
response.strategy.executionInterval	Int	执行间隔：单位秒

需量控制

下发控制

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "demandControl",
  "ts": 1212121221,
  "params": {
    "strategyName": "策略名称",    
    "startDate": "2024-07-01",
    "endDate": "2024-07-30",
    "overDemandThresholdValue": 1,
    "overDemandMaxValue": 1,
    "overDemandMinValue": 1,
    "overDemandStatus": 1,
    "executionInterval": 60
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error"
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	需量控制固定demandControl
ts	Long	毫秒时间戳
params	Object	请求参数
params.strategyName	String	策略名称
params.startDate	String	开始时间, 必须小于结束时间
params.endDate	String	结束时间, 必须大于开始时间
params.overDemandThresholdValue	Int	防超需阈值单位:W
params.overDemandMaxValue	Int	防超需死区上限单位:W
params.overDemandMinValue	Int	防超需死区下限单位:W
params.overDemandStatus	Int	防超需启用状态：不传默认启用 1-启用 0-禁用
params.executionInterval	Int	执行间隔：单位秒，不传默认60秒

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

获取策略

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "getDemandControl",
  "ts": 1212121221,
  "params": { 
    "startDate": "2024-07-01",
    "endDate": "2024-07-30"
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error",
  "response": {
    "strategy": [
      {
        "strategyName": "策略名称",    
        "startDate": "2024-07-01",
        "endDate": "2024-07-30",
        "overDemandThresholdValue": 1,
        "overDemandMaxValue": 1,
        "overDemandMinValue": 1,
        "executionInterval": 60
      }
    ]
  }
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	需量控制固定getDemandControl
ts	Long	毫秒时间戳
params	Object	请求参数
params.startDate	String	开始时间, 必须小于结束时间
params.endDate	String	结束时间, 必须大于开始时间

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述
response	Object	响应参数
response.strategy	Array	策略列表
response.strategy.strategyName	String	策略名称
response.strategy.startDate	String	开始时间, 必须小于结束时间
response.strategy.endDate	String	结束时间, 必须大于开始时间
response.strategy.overDemandThresholdValue	Int	防超需阈值单位:W
response.strategy.overDemandMaxValue	Int	防超需死区上限单位:W
response.strategy.overDemandMinValue	Int	防超需死区下限单位:W
response.strategy.executionInterval	Int	执行间隔：单位秒

动态扩容

下发控制

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "dynamicExpansion",
  "ts": 1212121221,
  "params": {
    "strategyName": "策略名称",    
    "startDate": "2024-07-01",
    "endDate": "2024-07-30",
    "expansionThresholdValue": 7500,
    "deadUpperLimit": 7900,
    "deadLowerLimit": 7200,
    "expansionStatus": 1
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error"
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	动态扩容固定getDynamicExpansion
ts	Long	毫秒时间戳
params	Object	请求参数
params.strategyName	String	策略名称
params.startDate	String	开始时间, 必须小于结束时间
params.endDate	String	结束时间, 必须大于开始时间
params.expansionThresholdValue	Int	目标值单位:VA
params.deadUpperLimit	Int	动态扩容死区上限值单位:VA
params.deadLowerLimit	Int	动态扩容死区上限值单位:VA
params.expansionStatus	Int	动态扩容启用状态：不传默认启用 1-启用 0-禁用

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

获取策略

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "getDynamicExpansion",
  "ts": 1212121221,
  "params": { 
    "startDate": "2024-07-01",
    "endDate": "2024-07-30"
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error",
  "response": {
    "strategy": [
      {
        "strategyName": "策略名称",    
        "startDate": "2024-07-01",
        "endDate": "2024-07-30",
        "expansionThresholdValue": 7500,
        "deadUpperLimit": 7900,
        "deadLowerLimit": 7200,
        "expansionStatus": 1
      }
    ]
  }
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	动态扩容固定getDynamicExpansion
ts	Long	毫秒时间戳
params	Object	请求参数
params.startDate	String	开始时间, 必须小于结束时间
params.endDate	String	解释时间, 必须大于开始时间

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述
response	Object	响应参数
response.strategy	Array	策略列表
response.strategy.strategyName	String	策略名称
response.strategy.startDate	String	开始时间, 必须小于结束时间
response.strategy.endDate	String	解释时间, 必须大于开始时间
params.expansionThresholdValue	Int	目标值单位:VA
params.deadUpperLimit	Int	动态扩容死区上限值单位:VA
params.deadLowerLimit	Int	动态扩容死区上限值单位:VA
params.expansionStatus	Int	动态扩容启用状态：不传默认启用 1-启用 0-禁用

电价下发

下发电价

下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "electricityConfig",
  "ts": 1212121221,
  "params": {
    "periodType": [
      {
        "type": "sharp",
        "name": "尖"
      },
      {
        "type": "peak",
        "name": "峰"
      },
      {
        "type": "shoulders",
        "name": "平"
      },
      {
        "type": "off_peak",
        "name": "谷"
      },
      {
        "type": "deep_valley",
        "name": "深谷"
      }
    ],
    "electricityConfig": [
      {
        "date": "2024-07-01",
        "schemeId": 1
      }
    ],
    "schemes": [
      {
        "schemeId": 1,
        "schemeName": "方案名称",
        "year": 2024,
        "type": "TWO_PART",
        "type2": "normal",
        "method": "TRANSFORMER",
        "demand": 1000000,
        "demandPrice": "0.3",  
        "capacity": 1000000,
        "capacityPrice": "0.3",
        "periodPrice": [
          {
            "type": "peak",
            "buyPrice": 3000,
            "salePrice": 3000
          },
          {
            "type": "off_peak",
            "buyPrice": 3000,
            "salePrice": 3000
          }
        ],
        "periodTime": [
          {
            "type": "peak",
            "startTime": "00:00",
            "endTime": "01:00"
          },
          {
            "type": "off_peak",
            "startTime": "01:00",
            "endTime": "02:00"
          },
          {
            "type": "peak",
            "startTime": "02:00",
            "endTime": "03:00"
          },
          {
            "type": "off_peak",
            "startTime": "03:00",
            "endTime": "04:00"
          }
        ]
      }
    ]
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error"
}

请求参数说明:

字段	类型	描述
method	String	action 表示调用设备的某个服务, 固定值.
msgId	String	对应请求的msgId, 做关联使用
serviceId	String	电价下发固定electricityConfig
ts	Long	毫秒时间戳
params	Object	请求参数
params.periodType	Array	电价时段类型
params.periodType.type	String	时段类型
params.periodType.name	String	时段名称
params.electricityConfig	Array	电价配置
params.electricityConfig.date	String	日期
params.electricityConfig.schemeId	Long	方案ID
params.schemes	Array	电价方案
params.schemes.schemeId	Long	方案ID
params.schemes.schemeName	String	方案名称
params.schemes.year	Int	年份
params.schemes.type	String	电价类型 UNITARY: 单一制, TWO_PART: 两部制
params.schemes.type2	String	电价类型 normal: 一般工商业, largeIndustry: 大工业
params.schemes.method	String	计费方式 TRANSFORMER: 变压器容量, MAX_DEMAND: 最大需量
params.schemes.demand	Long	最大需量单位: W
params.schemes.demandPrice	String	最大需量电价单位: 毫/千瓦月
params.schemes.capacity	Long	变压器容量单位: V
params.schemes.capacityPrice	String	变压器容量电价单位: 毫/千伏安月
params.schemes.periodTime	Array	电价时段
params.schemes.periodTime.type	String	时段类型参考periodType
params.schemes.periodTime.startTime	String	开始时间
params.schemes.periodTime.endTime	String	结束时间
params.schemes.periodPrice	Array	电价时段
params.schemes.periodPrice.type	String	时段类型参考periodType
params.schemes.periodPrice.buyPrice	Long	买入价格（毫/kWh） e.g.:1元/kWh 为10000
params.schemes.periodPrice.salePrice	Long	卖出电价（毫/kWh） e.g.:1元/kWh 为10000

响应参数说明:

字段	类型	描述
method	String	action_reply 表示服务调用的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

事件上报

设备事件上行请求 Topic： $thing/up/event/{ProductKey}/{DeviceKey}
设备事件下行响应 Topic： $thing/down/event/{ProductKey}/{DeviceKey}
上行数据格式:

json

{
  "method": "event_post",
  "msgId": "123",
  "eventId": "PowerAlarm",
  "type": "error",
  "ts": 1212121221,
  "params": {
    "Voltage": 2.8,
    "Percent": 20
  }
}

响应数据格式:

json

{
    "method": "event_reply",
    "msgId": "123",
    "code": 0,
    "status": ""
}

请求参数说明:

字段	类型	描述
method	String	event_post 表示调用事件上报, 固定值.
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
ts	Long	请求的时间. 毫秒时间戳
eventId	String	物模型中的event标识符. 由物模型中定义.
params	Object	物模型中event定义的响应参数
type	String	事件类型, 值: INFO/WARNING/ERROR

响应参数说明:

字段	类型	描述
method	String	event_reply 表示属性设置的响应报文
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

时间同步

数据上行 Topic（用于发布）：time-sync/up/{ProductKey}/{DeviceKey}
数据下行 Topic（用于订阅）：time-sync/down/{ProductKey}/{DeviceKey}
上行数据格式:

json

{
  "deviceSendTime":"1571724098000"
}

下行数据格式:

json

{
  "deviceSendTime": "1571724098000",
  "serverRecvTime": "1571724098110",
  "serverSendTime": "1571724098115"
}

假设基于请求的时延和响应的时延相同，设备端收到服务端的时间即${deviceRecvTime}，则设备上的精确时间为：(${serverRecvTime}+${serverSendTime}+${deviceRecvTime}-${deviceSendTime})/2。

请求参数说明:

字段	类型	描述
deviceSendTime	Long	客户端请求时间, 毫秒时间戳

响应参数说明:

字段	类型	描述
deviceSendTime	Long	客户端请求时间, 毫秒时间戳
serverRecvTime	Long	服务端收到消息的时间, 毫秒时间戳
serverSendTime	Long	服务端回复消息的时间, 毫秒时间戳

日志收集

日志收集服务调用

数据下行 Topic（用于订阅）: $thing/down/service/{ProductKey}/{DeviceKey}
数据上行 Topic（用于发布）: $thing/up/service/{ProductKey}/{DeviceKey}
下行数据格式:

json

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "$log",
  "ts": 1212121221,
  "params": {
    "switch": "on",
    "endTime": 1571724098110
  }
}

上行数据格式:

json

{
  "method": "action_reply",
  "msgId": "1234",
  "code": 0,
  "status": "some message where error"
}

请求参数字段说明:

字段	类型	描述
method	String	服务调用固定值:"action". 表示是调用设备的某个行为。
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
serviceId	String	系统参数. 固定$log
ts	Long	行为调用的时间，单位为毫秒
switch	String	可选参数. 设备侧日志收集开关。 on：开启设备侧日志收集功能。 off：关闭设备侧日志收集开关。
endTime	Long	可选, 日志收集结束时间

响应参数字段说明:

字段	类型	描述
method	String	调用响应固定值:"action_reply". 表示是设备执行完成后向云端回复的响应
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

日志上报

数据下行 Topic（用于订阅）: $thing/up/log/{ProductKey}/{DeviceKey}
数据上行 Topic（用于发布）: $thing/down/log/{ProductKey}/{DeviceKey}
下行数据格式:

json

{
  "msgId": "1234",
  "serviceId": "$log",  // 固定$log	
  "ts": 1212121221,
  "params": [{
    "time": "on",
    "level": "INFO",
    "type": "类型",
    "content": "日志内容"
  }]
}

上行数据格式:

json

{
  "msgId": "1234",
  "code": 0,
  "status": "some message where error"  //错误消息
}

请求参数字段说明:

字段	类型	描述
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
ts	Long	行为调用的时间，单位为毫秒。
params	Array	日志明细
time	Long	日志产生时间
level	String	日志级别, 值: INFO/WARNING/ERROR
type	String	日志类型, 自行定义
content	String	日志正文内容

响应参数字段说明:

字段	类型	描述
msgId	String	对应请求的msgId, 做关联使用
code	Integer	执行结果, 0表示成功
status	String	执行失败后的错误描述

OTA

OTA流程

设备链接初始化时上报设备版本信息($ota/device/inform/{ProductKey}/{DeviceKey})
后台上传固件升级包, 并对该设备发起OTA推送
固件推送更新$ota/update/{ProductKey}/{DeviceKey}
上报升级进度($ota/report/progress/{ProductKey}/{DeviceKey})
设备升级完成后上报最新版本($ota/device/inform/{ProductKey}/{DeviceKey})

固件推送逻辑

每一次上报设备版本信息时都会检测当前设备是否和最新固件版本一致, 不一致时会推送固件更新

版本上报

数据上行 Topic（用于发布）: $ota/device/inform/{ProductKey}/{DeviceKey}

json

{
  "msgId": 1,
  "params": {
    "version": "1.0.0",
    "module":"mcu"
  }
}

请求参数字段说明:

字段	类型	描述
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
version	String	版本号
module	String	模块名, 上报设备本身(default)时可不传该参数

上报升级进度

数据上行 Topic（用于发布）: $ota/report/progress/{ProductKey}/{DeviceKey}

json

{
    "msgId": "123",
    "params": {
        "step": "-1",
        "desc": "OTA升级失败，请求不到升级包信息。",
        "module": "MCU"
    }
}

请求参数字段说明:

字段	类型	描述
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
step	String	升级进度, 设备上报的进度值及其描述信息， 1~100的整数：升级进度百分比。 -1：升级失败。 -2：下载失败。 -3：校验失败。 -4：烧写失败。
desc	String	进度描述信息, 最多128个字符. 异常时可用该字段描述异常信息
module	String	模块名, 上报设备本身(default)时可不传该参数

固件更新推送

数据下行 Topic（用于订阅）: $ota/update/{ProductKey}/{DeviceKey}

json

{
  "msgId": "123",
	"size": 93796291,
	"version": "1.0.0",
	"url": "https://the_firmware_url",
	"md5": "f8d85b250d4d787a9f48***",
	"module": "MCU"
}

返回参数字段说明:

字段	类型	描述
msgId	String	消息唯一标识符, 最少确保24小时内唯一. 可用自增id等方式
size	Long	固件大小, 单位为字节
version	String	版本号
url	String	固件下载url
md5	String	固件的MD5值
module	String	模块名, 设备本身(default)时无该参数

MQTT协议 ​

MQTT连接参数 ​

限制 ​

MQTT连接鉴权 ​

Topic ​

Topic 说明 ​

数据压缩 ​

数据压缩的 Topic 说明 ​

网关代理上下线 ​

功能概述 ​

代理子设备上线 ​

代理子设备下线 ​

错误码 ​

代理子设备发布和订阅 ​

功能概述 ​

发布和订阅消息 ​

设备属性上报 ​

设备属性上报数据压缩 ​

属性设置 ​

网关批量上报 ​

服务调用 ​

削峰填谷数据 ​

下发控制 ​

获取策略 ​

防逆流 ​

下发控制 ​

获取策略 ​

需量控制 ​

下发控制 ​

获取策略 ​

动态扩容 ​

下发控制 ​

获取策略 ​

电价下发 ​

下发电价 ​

事件上报 ​

时间同步 ​

日志收集 ​

日志收集服务调用 ​

日志上报 ​

OTA ​

OTA流程 ​

固件推送逻辑 ​

版本上报 ​

上报升级进度 ​

固件更新推送 ​

MQTT协议

MQTT连接参数

限制

MQTT连接鉴权

Topic

Topic 说明

数据压缩

数据压缩的 Topic 说明

网关代理上下线

功能概述

代理子设备上线

代理子设备下线

错误码

代理子设备发布和订阅

功能概述

发布和订阅消息

设备属性上报

设备属性上报数据压缩

属性设置

网关批量上报

服务调用

削峰填谷数据

下发控制

获取策略

防逆流

下发控制

获取策略

需量控制

下发控制

获取策略

动态扩容

下发控制

获取策略

电价下发

下发电价

事件上报

时间同步

日志收集

日志收集服务调用

日志上报

OTA

OTA流程

固件推送逻辑

版本上报

上报升级进度

固件更新推送