MQTT Protocol

MQTT Connection Parameters

1. Keep Alive: 60s
2. Clean Start: 0

Limitations

1. If the size of each message sent by the device exceeds 1M, it may cause data parsing errors. It is recommended to use packet splitting.

MQTT Connection Authentication

clientId: ${ProductKey}+"&"+${DeviceKey}
username: ${ProductKey}+"&"+${DeviceKey};${timestamp:milliseconds}
password: hmacsha256(secret:${deviceSecret},digest body: ${timestamp})

Topic

Topic Description

Upstream Topic refers to the device sending messages to the platform. Downstream Topic refers to the application sending messages to the device.

Data Compression

The protocol supports data compression for long messages. By compressing data before transmission, you can save device bandwidth and improve transmission speed.

Data Compression Topic Description

Add /gzip suffix to the regular Topic, compress the request body using Gzip, and then send it. The cloud platform will decompress and process it.
Example:
Device Property Reporting: $thing/up/property/{productKey}/{DeviceKey}/gzip
Request Data Format (gzip compress the following JSON before sending):

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

Gateway Proxy Online/Offline

Functional Overview

Gateway type devices can proxy the online and offline operations of their sub-devices through data communication with the cloud.

• Data Upstream Topic (for publishing): $gateway/operation/up/${ProductKey}/${DeviceKey}
• Data Downstream Topic (for subscription): $gateway/operation/down/${ProductKey}/${DeviceKey}

Proxy Sub-device Online

Gateway type devices can proxy sub-devices to go online via the data upstream topic. After a successful request, the cloud returns the sub-device online result information via the data downstream topic. Gateway Proxy Sub-device Online Request Data Format:

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

Gateway Proxy Sub-device Online Response Data Format:

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

Request Parameter Field Description:

Field	Type	Description
type	String	Device online/offline status, online: online, offline: offline
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
ts	Long	Online time, millisecond timestamp
payload	Object	Parameter information
payload.devices	Array	Device information list
payload.devices.productKey	String	Sub-device Product Key
payload.devices.deviceKey	String	Sub-device Key

Response Parameter Field Description:

Field	Type	Description
type	String	Corresponding request type
msgId	String	Corresponding request msgId, used for correlation
payload	Object	Parameter information
payload.devices	Array	Device information list
payload.devices.productKey	String	Sub-device Product Key
payload.devices.deviceKey	String	Sub-device Key
payload.devices.result	Integer	Sub-device online result, 0 means success, see table below for specific error codes

Proxy Sub-device Offline

Gateway type devices can proxy sub-devices to go offline via the data upstream topic. After a successful request, the cloud returns the successful sub-device offline information via the data downstream topic.
Gateway Proxy Sub-device Offline Request Data Format:

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

Gateway Proxy Sub-device Offline Response Data Format:

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

Request Parameter Description:

Field	Type	Description
type	String	Device online/offline status, online: online, offline: offline
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
ts	Long	Online time, millisecond timestamp
payload	Object	Parameter information
payload.devices	Array	Device information list
payload.devices.productKey	String	Sub-device Product Key
payload.devices.deviceKey	String	Sub-device Key

Response Parameter Description:

Field	Type	Description
type	String	Corresponding request type
msgId	String	Corresponding request msgId, used for correlation
payload	Object	Parameter information
payload.devices	Array	Device information list
payload.devices.productKey	String	Sub-device Product Key
payload.devices.deviceKey	String	Sub-device Key
payload.devices.result	Integer	Sub-device online result, 0 means success, see table below for specific error codes

Error Codes

Error Code	Description
0	Success
1	The gateway device is not bound to this sub-device
2	System error, sub-device online or offline failed

Proxy Sub-device Publish and Subscribe

Functional Overview

Gateway type devices can proxy the publishing and subscription of messages for their sub-devices through data communication with the cloud.

Publish and Subscribe Messages

After the gateway product establishes a binding with the sub-product and obtains the Topic permissions of the sub-device, the gateway device can use the sub-device Topic proxy to send and receive messages.

Device Property Reporting

Data Upstream Topic (for publishing): $thing/up/property/{productKey}/{DeviceKey}
Data Downstream Topic (for subscription): $thing/down/property/{productKey}/{DeviceKey}
Request Data Format:

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

Response Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	report indicates property reporting, fixed value.
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
ts	Long	Time reported by the device. Millisecond timestamp
params	Object	Property values reported by the device
params.power_switch	Boolean	Boolean value is generally true/false
payload.brightness	Integer	Integer type property is an integer value

Response Parameter Description:

Field	Type	Description
method	String	report_reply indicates the response message for property reporting
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Device Property Reporting Data Compression

When reporting many properties, you can compress data to save device bandwidth and improve transmission speed.
For details, please refer to the Data Compression section.
Data Upstream Topic (for publishing): $thing/up/property/{productKey}/{DeviceKey}/gzip

The request data format is the same as the normal format, as shown below. You need to gzip compress the entire JSON before sending:

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

Property Setting

When controlling the device via the cloud, the device needs to subscribe to the downstream Topic to receive cloud commands:
Downstream Topic: $thing/down/property/{ProductKey}/{DeviceKey}
Upstream Topic: $thing/up/property/{ProductKey}/{DeviceKey}
Downstream Data Format:

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

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	control indicates property setting, fixed value.
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
ts	Long	Command issuance time. Millisecond timestamp
params	Object	Device property setting values

Response Parameter Description:

Field	Type	Description
method	String	control_reply indicates the response message for property setting
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Gateway Batch Reporting

Gateway type devices quickly report property change information for sub-devices and themselves in batches.
Upstream Topic: $thing/up/property/gateway/{ProductKey}/{DeviceKey}
Downstream Topic: $thing/down/property/gateway/{ProductKey}/{DeviceKey}
Request Data Format:

{
  "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
        }
      }
    ]
  }
}

Response Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	report indicates property reporting, fixed value.
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
ts	Long	Request time. Millisecond timestamp
params	Object	Device property setting values
params.properties	Object	Property changes of the gateway device itself
params.properties.ts	Long	Property change time point. Millisecond timestamp
params.properties.values	Map	Property values reported by the gateway device
params.subDevices	Array	List of gateway sub-device property values
params.subDevices.productKey	String	Sub-device Product Key
params.subDevices.deviceKey	String	Sub-device Key
params.subDevices.properties	Object	Sub-device property value information
params.subDevices.properties.ts	Long	Sub-device property change time
params.subDevices.properties.values	Map	Sub-device property values, KV pairs

Response Parameter Description:

Field	Type	Description
method	String	report_reply indicates the response message for property setting
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Service Invocation

Application invokes device action (Downstream) Topic: $thing/down/service/{ProductKey}/{DeviceKey}
Device responds to action execution result (Upstream) Topic: $thing/up/service/{ProductKey}/{DeviceKey}
Downstream Data Format:

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

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
ts	Long	Request time. Millisecond timestamp
serviceId	String	Service identifier in the Thing Model. Defined in the Thing Model.
params	Object	Request parameters defined in the service of the Thing Model

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure
response	Object	Response parameters defined in the service of the Thing Model

Peak Shaving and Valley Filling Data

Issue Control

Downstream Data Format:

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "peakShaving",
  "ts": 1212121221,
  "params": {
    "strategyName": "Strategy Name",
    "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
      }
    ]
  }
}

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Peak shaving fixed as peakShaving
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.strategyName	String	Strategy Name
params.startDate	String	Start time, must be less than end time
params.endDate	String	End time, must be greater than start time
params.maxChargingPower	Int	Max charging power: default 0 Unit: W
params.maxDischargePower	Int	Max discharging power: default 0 Unit: W
params.socUpperLimit	Int	SOC Upper Limit: default 0
params.socLowerLimit	Int	SOC Lower Limit: default 0
params.status	Int	Strategy enable status: default enabled if not passed 1-Enable 0-Disable
params.strategyParam	Array	Strategy configuration parameters
params.strategyParam.startTime	String	Start time: 15-minute interval, must be less than end time Time format 00:15, 00:30
params.strategyParam.endTime	String	End time: 15-minute interval, must be greater than start time Time format 00:15, 00:30
params.strategyParam.pattern	Int	Pattern 1-Charge 2-Standby 3-Discharge
params.strategyParam.activePower	Int	Active Power Unit: W

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Get Strategy

Downstream Data Format:

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

Upstream Data Format:

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error",
  "response": {
    "strategy":[
      {
        "strategyName": "Strategy Name",
        "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
          }
        ]
      }
    ]
  }
}

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Peak shaving fixed as getPeakShaving
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.startDate	String	Start time, must be less than end time
params.endDate	String	End time, must be greater than start time

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure
response	Object	Response parameters
response.strategy	Array	Strategy List
response.strategy.strategyName	String	Strategy Name
response.strategy.startDate	String	Start time, must be less than end time
response.strategy.endDate	String	End time, must be greater than start time
response.strategy.maxChargingPower	Int	Max charging power Unit: W
response.strategy.maxDischargePower	Int	Max discharging power Unit: W
response.strategy.socUpperLimit	Int	SOC Upper Limit
response.strategy.socLowerLimit	Int	SOC Lower Limit
response.strategy.strategyParam	Array	Strategy configuration parameters
response.strategy.strategyParam.startTime	String	Start time: 15-minute interval, must be less than end time Time format 00:15, 00:30
response.strategy.strategyParam.endTime	String	End time: 15-minute interval, must be greater than start time Time format 00:15, 00:30
response.strategy.strategyParam.pattern	Int	Pattern 1-Charge 2-Standby 3-Discharge
response.strategy.strategyParam.activePower	Int	Active Power Unit: W

Anti-Reflux

Issue Control

Downstream Data Format:

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

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Anti-reflux fixed as antiReflux
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.startDate	String	Start time, must be less than end time
params.endDate	String	End time, must be greater than start time
params.strategyName	String	Strategy Name
params.refluxThresholdValue	String	Anti-reflux threshold
params.refluxMaxValue	String	Anti-reflux dead zone upper limit
params.refluxMinValue	Int	Anti-reflux dead zone lower limit
params.refluxStatus	Int	Anti-reflux enable status: default enabled if not passed 1-Enable 0-Disable
params.executionInterval	Int	Execution interval: Unit seconds, default 60 seconds if not passed

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Get Strategy

Downstream Data Format:

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

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Anti-reflux fixed as getAntiReflux
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.startDate	String	Start time, must be less than end time
params.endDate	String	End time, must be greater than start time

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure
response	Object	Response parameters
response.strategy	Array	Strategy List
response.strategy.strategyName	String	Strategy Name
response.strategy.startDate	String	Start time, must be less than end time
response.strategy.endDate	String	End time, must be greater than start time
response.strategy.refluxThresholdValue	Int	Anti-reflux threshold
response.strategy.refluxMaxValue	Int	Anti-reflux dead zone upper limit Unit: W
response.strategy.refluxMinValue	Int	Anti-reflux dead zone lower limit Unit: W
response.strategy.executionInterval	Int	Execution interval: Unit seconds

Demand Control

Issue Control

Downstream Data Format:

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

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Demand control fixed as demandControl
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.strategyName	String	Strategy Name
params.startDate	String	Start time, must be less than end time
params.endDate	String	End time, must be greater than start time
params.overDemandThresholdValue	Int	Anti-excess demand threshold Unit: W
params.overDemandMaxValue	Int	Anti-excess demand dead zone upper limit Unit: W
params.overDemandMinValue	Int	Anti-excess demand dead zone lower limit Unit: W
params.overDemandStatus	Int	Anti-excess demand enable status: default enabled if not passed 1-Enable 0-Disable
params.executionInterval	Int	Execution interval: Unit seconds, default 60 seconds if not passed

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Get Strategy

Downstream Data Format:

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

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Demand control fixed as getDemandControl
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.startDate	String	Start time, must be less than end time
params.endDate	String	End time, must be greater than start time

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure
response	Object	Response parameters
response.strategy	Array	Strategy List
response.strategy.strategyName	String	Strategy Name
response.strategy.startDate	String	Start time, must be less than end time
response.strategy.endDate	String	End time, must be greater than start time
response.strategy.overDemandThresholdValue	Int	Anti-excess demand threshold Unit: W
response.strategy.overDemandMaxValue	Int	Anti-excess demand dead zone upper limit Unit: W
response.strategy.overDemandMinValue	Int	Anti-excess demand dead zone lower limit Unit: W
response.strategy.executionInterval	Int	Execution interval: Unit seconds

Dynamic Expansion

Issue Control

Downstream Data Format:

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "dynamicExpansion",
  "ts": 1212121221,
  "params": {
    "strategyName": "Strategy Name",    
    "startDate": "2024-07-01",
    "endDate": "2024-07-30",
    "expansionThresholdValue": 7500,
    "expansionMaxValue": 7900,
    "expansionMinValue": 7200,
    "expansionStatus": 1
  }
}

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Dynamic expansion fixed as getDynamicExpansion
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.strategyName	String	Strategy Name
params.startDate	String	Start time, must be less than end time
params.endDate	String	End time, must be greater than start time
params.expansionThresholdValue	Int	Target Value Unit: VA
params.expansionMaxValue	Int	Dynamic expansion dead zone upper limit Unit: VA
params.expansionMinValue	Int	Dynamic expansion dead zone lower limit Unit: VA
params.expansionStatus	Int	Dynamic expansion enable status: default enabled if not passed 1-Enable 0-Disable

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Get Strategy

Downstream Data Format:

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

Upstream Data Format:

{
  "method": "action_reply",
  "msgId": "1234",  
  "code": 0,
  "status": "some message where error",
  "response": {
    "strategy": [
      {
        "strategyName": "Strategy Name",    
        "startDate": "2024-07-01",
        "endDate": "2024-07-30",
        "expansionThresholdValue": 7500,
        "expansionMaxValue": 7900,
        "expansionMinValue": 7200,
        "expansionStatus": 1
      }
    ]
  }
}

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Dynamic expansion fixed as getDynamicExpansion
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.startDate	String	Start time, must be less than end time
params.endDate	String	End time, must be greater than start time

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure
response	Object	Response parameters
response.strategy	Array	Strategy List
response.strategy.strategyName	String	Strategy Name
response.strategy.startDate	String	Start time, must be less than end time
response.strategy.endDate	String	End time, must be greater than start time
params.expansionThresholdValue	Int	Target Value Unit: VA
params.expansionMaxValue	Int	Dynamic expansion dead zone upper limit Unit: VA
params.expansionMinValue	Int	Dynamic expansion dead zone lower limit Unit: VA
params.expansionStatus	Int	Dynamic expansion enable status: default enabled if not passed 1-Enable 0-Disable

Electricity Price Issuance

Issue Electricity Price

Downstream Data Format:

{
  "method": "action",
  "msgId": "1234",
  "serviceId": "electricityConfig",
  "ts": 1212121221,
  "params": {
    "periodType": [
      {
        "type": "sharp",
        "name": "Sharp"
      },
      {
        "type": "peak",
        "name": "Peak"
      },
      {
        "type": "shoulders",
        "name": "Shoulder"
      },
      {
        "type": "off_peak",
        "name": "Off-peak"
      },
      {
        "type": "deep_valley",
        "name": "Deep Valley"
      }
    ],
    "electricityConfig": [
      {
        "date": "2024-07-01",
        "schemeId": 1
      }
    ],
    "schemes": [
      {
        "schemeId": 1,
        "schemeName": "Scheme Name",
        "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"
          }
        ]
      }
    ]
  }
}

Upstream Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	action indicates invoking a service of the device, fixed value.
msgId	String	Corresponding request msgId, used for correlation
serviceId	String	Electricity price issuance fixed as electricityConfig
ts	Long	Millisecond timestamp
params	Object	Request parameters
params.periodType	Array	Electricity price period type
params.periodType.type	String	Period type
params.periodType.name	String	Period name
params.electricityConfig	Array	Electricity price configuration
params.electricityConfig.date	String	Date
params.electricityConfig.schemeId	Long	Scheme ID
params.schemes	Array	Electricity price scheme
params.schemes.schemeId	Long	Scheme ID
params.schemes.schemeName	String	Scheme name
params.schemes.year	Int	Year
params.schemes.type	String	Electricity price type UNITARY: Unitary system, TWO_PART: Two-part system
params.schemes.type2	String	Electricity price type normal: General industrial and commercial, largeIndustry: Large industrial
params.schemes.method	String	Billing method TRANSFORMER: Transformer capacity, MAX_DEMAND: Maximum demand
params.schemes.demand	Long	Maximum demand Unit: W
params.schemes.demandPrice	String	Maximum demand price Unit: milli/kW month
params.schemes.capacity	Long	Transformer capacity Unit: V
params.schemes.capacityPrice	String	Transformer capacity price Unit: milli/kVA month
params.schemes.periodTime	Array	Electricity price period
params.schemes.periodTime.type	String	Period type, refer to periodType
params.schemes.periodTime.startTime	String	Start time
params.schemes.periodTime.endTime	String	End time
params.schemes.periodPrice	Array	Electricity price period
params.schemes.periodPrice.type	String	Period type, refer to periodType
params.schemes.periodPrice.buyPrice	Long	Buying price (milli/kWh) e.g.: 1 Yuan/kWh is 10000
params.schemes.periodPrice.salePrice	Long	Selling price (milli/kWh) e.g.: 1 Yuan/kWh is 10000

Response Parameter Description:

Field	Type	Description
method	String	action_reply indicates the response message for service invocation
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Event Reporting

Device Event Upstream Request Topic: $thing/up/event/{ProductKey}/{DeviceKey}
Device Event Downstream Response Topic: $thing/down/event/{ProductKey}/{DeviceKey}
Upstream Data Format:

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

Response Data Format:

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

Request Parameter Description:

Field	Type	Description
method	String	event_post indicates invoking event reporting, fixed value.
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
ts	Long	Request time. Millisecond timestamp
eventId	String	Event identifier in the Thing Model. Defined in the Thing Model.
params	Object	Response parameters defined in the event of the Thing Model
type	String	Event type, values: INFO/WARNING/ERROR

Response Parameter Description:

Field	Type	Description
method	String	event_reply indicates the response message for event reporting
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Time Synchronization

Data Upstream Topic (for publishing): time-sync/up/{ProductKey}/{DeviceKey}
Data Downstream Topic (for subscription): time-sync/down/{ProductKey}/{DeviceKey}
Upstream Data Format:

{
  "deviceSendTime":"1571724098000"
}

Downstream Data Format:

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

Assuming the request latency and response latency are the same, and the time the device receives the server message is ${deviceRecvTime}, then the precise time on the device is: (${serverRecvTime}+${serverSendTime}+${deviceRecvTime}-${deviceSendTime})/2.

Request Parameter Description:

Field	Type	Description
deviceSendTime	Long	Client request time, millisecond timestamp

Response Parameter Description:

Field	Type	Description
deviceSendTime	Long	Client request time, millisecond timestamp
serverRecvTime	Long	Server received message time, millisecond timestamp
serverSendTime	Long	Server reply message time, millisecond timestamp

Log Collection

Log Collection Service Invocation

Data Downstream Topic (for subscription): $thing/down/service/{ProductKey}/{DeviceKey}
Data Upstream Topic (for publishing): $thing/up/service/{ProductKey}/{DeviceKey}
Downstream Data Format:

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

Upstream Data Format:

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

Request Parameter Field Description:

Field	Type	Description
method	String	Service invocation fixed value: "action". Indicates invoking a behavior of the device.
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
serviceId	String	System parameter. Fixed as $log
ts	Long	Time of behavior invocation, in milliseconds
switch	String	Optional parameter. Device-side log collection switch. on: Enable device-side log collection function. off: Disable device-side log collection switch.
endTime	Long	Optional, log collection end time

Response Parameter Field Description:

Field	Type	Description
method	String	Invocation response fixed value: "action_reply". Indicates the response replied to the cloud after the device completes execution.
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

Log Reporting

Data Downstream Topic (for subscription): $thing/up/log/{ProductKey}/{DeviceKey}
Data Upstream Topic (for publishing): $thing/down/log/{ProductKey}/{DeviceKey}
Downstream Data Format:

{
  "msgId": "1234",
  "serviceId": "$log",  // Fixed as $log	
  "ts": 1212121221,
  "params": [{
    "time": "on",
    "level": "INFO",
    "type": "Type",
    "content": "Log Content"
  }]
}

Upstream Data Format:

{
  "msgId": "1234",
  "code": 0,
  "status": "some message where error"  // Error message
}

Request Parameter Field Description:

Field	Type	Description
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
ts	Long	Time of behavior invocation, in milliseconds.
params	Array	Log details
time	Long	Log generation time
level	String	Log level, values: INFO/WARNING/ERROR
type	String	Log type, self-defined
content	String	Log body content

Response Parameter Field Description:

Field	Type	Description
msgId	String	Corresponding request msgId, used for correlation
code	Integer	Execution result, 0 means success
status	String	Error description after execution failure

OTA

OTA Process

1. Report device version information when device connection initializes ($ota/device/inform/{ProductKey}/{DeviceKey})
2. Backend uploads firmware upgrade package and initiates OTA push to the device
3. Firmware push update $ota/update/{ProductKey}/{DeviceKey}
4. Report upgrade progress ($ota/report/progress/{ProductKey}/{DeviceKey})
5. Report latest version after device upgrade is complete ($ota/device/inform/{ProductKey}/{DeviceKey})

Firmware Push Logic

Every time device version information is reported, it checks if the current device matches the latest firmware version. If inconsistent, a firmware update is pushed.

Version Reporting

Data Upstream Topic (for publishing): $ota/device/inform/{ProductKey}/{DeviceKey}

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

Request Parameter Field Description:

Field	Type	Description
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
version	String	Version number
module	String	Module name, can be omitted when reporting the device itself (default)

Report Upgrade Progress

Data Upstream Topic (for publishing): $ota/report/progress/{ProductKey}/{DeviceKey}

{
    "msgId": "123",
    "params": {
        "step": "-1",
        "desc": "OTA upgrade failed, cannot request upgrade package information.",
        "module": "MCU"
    }
}

Request Parameter Field Description:

Field	Type	Description
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
step	String	Upgrade progress, progress value and description reported by the device, Integer 1~100: Upgrade progress percentage. -1: Upgrade failed. -2: Download failed. -3: Verification failed. -4: Burning failed.
desc	String	Progress description information, max 128 characters. Can be used to describe exception information when an exception occurs.
module	String	Module name, can be omitted when reporting the device itself (default)

Firmware Update Push

Data Downstream Topic (for subscription): $ota/update/{ProductKey}/{DeviceKey}

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

Return Parameter Field Description:

Field	Type	Description
msgId	String	Message unique identifier, ensure uniqueness for at least 24 hours. Auto-increment id can be used
size	Long	Firmware size, in bytes
version	String	Version number
url	String	Firmware download url
md5	String	MD5 value of the firmware
module	String	Module name, no such parameter for the device itself (default)