DIY MODE API PROTOCOL
BASICR3/RFR3/MINI HTTP API
B02-BL/B05-BL HTTP API
D1 HTTP API
MINIR3 HTTP API
SPM MAIN HTTP API

—Device Status Broadcast
—Get the Device id
—Add Sub-device
—Get the List of Sub-device
—ON/OFF Switch
—Overload Protection
—I Am Here
—Set Device Time
—Historical Data of Sub-device
—Set up Real-time Monitoring Related Information
—WiFi SSID and Password Setting
—OTA Firmware
—Get Channel Operation Records
—Get Device State
—Switch to eWeLink Mode

Reference

SONOFF

SPM-Main HTTP API

Version: 2.2  Date: 2021-11-15

SPM-Main HTTP API

The device type is diy_meter(type=diy_meter) and the device API interface version is 1 (apivers=1).

Device Status Broadcast

When the status of the sub-device changes, the DNS TXT must contain the field “id” which is the [chip id] of the sub-device. The sub-device only broadcasts the changed field. If the switch of the sub-device is changed, only the switches field is reported, and the threshold overload_00 field is not reported.

This example adds line breaks and spaces to make it easier to read, but there are actually no line breaks and spaces.

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
//All fields broadcast by sub-device
{
	"switches": [
    {
        "outlet":0,
        "switch":"on"
    },
    {
        "outlet":1,
        "switch":"on"
    },
    {
        "outlet":2,
        "switch":"on"
    },
    {
        "outlet":3,
        "switch":"on"
    }
],

//_00 represents the value of channel 1, _01 represents the value of channel 2, and so on
"current_00":100,
"voltage_00":22000,
"actPow_00":22000,
"reactPow_00":22000,
"apparentPow_00":22000,
  
"overload_00": 
{
    "minAP": {
        "en": 0,
        "val": 110000
    },
    "maxAP": {
        "en": 1,
        "val": 10000
    },
    "minV": {
        "en": 1,
        "val": 1000
    },
    "maxV": {
        "en": 0,
        "val": 22000
    },
    "maxC": {
        "en": 1,
        "val": 2000
    },
    "delayTime": 10
},
"overload_01":{},
"overload_02":{},
"overload_03":{},
"faultState": {
    "subDevCom": 0,
    "overloadTrig": [
        {
            "outlet": 0,
            "rsn": [1]
        },
        {
            "outlet": 2,
            "rsn": [3]
        }
    ],
    "cse7761Com": [
        1,
        0,
        1,
        1
    ],
    "overTemp": [
        0
    ],
    "overLimit": [
        {
            "outlet": 1,
            "rsn": [0]
        },
        {
            "outlet": 3,
            "rsn": [1]
        }
    ]
}
}

//If the switch status of the sub-device changes, only the switches field is reported.
{
"switches": [
    {
        "outlet":0,
        "switch":"on"
    },
    {
        "outlet":1,
        "switch":"on"
    },
    {
        "outlet":2,
        "switch":"on"
    },
    {
        "outlet":3,
        "switch":"on"
    }
]
}

//Report the PVC status of channel 1 in real time
{
"current_00":100,
"voltage_00":22000,
"actPow_00":22000,
"reactPow_00":22000,
"apparentPow_00":22000,
}


//Sub-device failure

{
"faultState": {
    "subDevCom": 0,
    "overloadTrig": [
        {
            "outlet": 0,
            "rsn": [1]
        },
        {
            "outlet": 2,
            "rsn": [3]
        }
    ],
    "cse7761Com": [
        1,
        0,
        1,
        1
    ],
    "overTemp": [
      	1,
        0,
      	1,
      	0
    ],
    "overLimit": [
        {
            "outlet": 1,
            "rsn": [0]
        },
        {
            "outlet": 3,
            "rsn": [1]
        }
    ]
}
}

 

AttributeTypeDescription
switchesArraySwitch status of all channels
outletNumberChannel Number, [0,3]
switchStringon: turn the switch on, off: turn the switch off
subDevComNumberSub-device 485 communication status. 1: Communication is normal, 0: Communication error
overloadTrigArrayOverload protection trigger event. This field appears when there is an overload event.
cse7761ComArraySub-device cse7761 communication error. Array elements are Number type. The quantity is 4. Elements 0-3 are 1-4 channels respectively. [0,1] 1: Communication is normal. 0: Communication error.
overTempArraySub-device cse7761 over-temperature protection trigger event. Array elements are Number type. The quantity is 4. Elements 0-3 are 1-4 channels respectively. [0,1] 1: Communication is normal. 0: Communication error. This field appears when there is an over-temperature trigger event.
overLimitArrayLimit value overload protection trigger event. This field appears when there is a limit value overload event.

Get the Device id

URL: http://[ip]:[port]/zeroconf/deviceid
Return value format: json
Method: HTTP post

e.g.

1
2
3
{ 
     "data": {} 
 }

 

Empty object, no attribute is required.

Response body

1
2
3
4
5
6
7
{
"seq": 2,
"error": 0,
"data": {
"deviceid": "1000012345"
}
}

 

Add Sub-device

URL: http://[ip]:[port]/zeroconf/add_sub_devices
Return value format: json
Method: HTTP post

e.g.

1
2
3
4
{ 
    "deviceid": "100000140e", 
    "data": {} 
 }

 

Empty object, no attribute is required.

Response body

1
2
3
4
{
  "seq": 2,
  "error": 0,
 }

 

Get the List of Sub-device

URL: http://[ip]:[port]/zeroconf/subDevList
Return value format: json
Method: HTTP post

e.g.

1
2
3
4
{ 
    "deviceid": "100000140e", 
    "data": {} 
 }

 

Empty object, no attribute is required.

Response body

1
2
3
4
5
6
7
8
9
10
11
12
{
  "seq": 2,
  "error": 0,
  "data": {
    "subDevList": [
      {
        "subDevId": "123456",
        "type": 130
      }
    ]
  }
}

 

AttributeTypeOptionalDescription
subDevIdStringNoChip ID of sub-device
typeNumberNoType of sub-device. 130: Four-channel sub-device

ON/OFF Switch

URL: http://[ip]:[port]/zeroconf/switches
Return value format: json
Method: HTTP post .

e.g.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "deviceid": "100000140e",
  "data": {
    "subDevId": "123456",
    "switches": [
      {
        "switch": "on",
        "outlet": 0
      },
      {
        "switch": "on",
        "outlet": 1
      },
      {
        "switch": "on",
        "outlet": 2
      },
      {
        "switch": "on",
        "outlet": 3
      }
    ]
  }
}

 

AttributeTypeOptionalDescription
switchStringNoon: turn the switch on, off: turn the switch off
outletNumberNoChannel Number, [0,3]

    Overload Protection

    URL: http://[ip]:[port]/zeroconf/overload
    Return value format: json
    Method: HTTP post

    Request body

    e.g.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    {
        "deviceid": "100000140e",
        "data": {
            "subDevId": "123456",
            "overload_00": 
            {
                "minAP": {
                    "en": 0,
                    "val": 110000
                },
                "maxAP": {
                    "en": 1,
                    "val": 10000
                },
                "minV": {
                    "en": 1,
                    "val": 1000
                },
                "maxV": {
                    "en": 0,
                    "val": 22000
                },
                "maxC": {
                    "en": 1,
                    "val": 2000
                },
                "delayTime": 10
            },
            "overload_01":{},
            "overload_02":{},
            "overload_03":{}
        },
    }

     

    AttributeTypeOptionalDescription
    minAPNumberNoMin.power, [10,440000], Unit: 0.01 W
    maxAPNumberNoMax.power, [10,440000], Unit: 0.01 W
    minVNumberNoMin.voltage, [10,24000], Unit: 0.01 V
    maxVNumberNoMax.vpltage, [10,24000], Unit: 0.01 V
    maxCNumberNoMax.current, [10,2000], Unit: 0.01 A
    delayTimeNumberNoDelay to switch off, [0,180]
    enNumberNo0: Disable overload protection.
    1: Enable overload protection.
    valNumberNoUpper limit or lower limit

    Note:
    -_00 represents the value of channel 1, _01 represents the value of channel 2, and so on.
    -When the power, voltage upper threshold and lower threshold are all open, the upper threshold must be greater than the lower threshold.

      I Am Here

      URL: http://[ip]:[port]/zeroconf/iAmHere
      Return value format: json
      Method: HTTP post

      e.g.

      1
      2
      3
      4
      5
      6
      {
        "deviceid": "100000140e",
        "data": {
          "subDevId": "123456"
        }
      }

       

      Note:
      -This function can find the designated sub-device through the indicator light.

      Set Device Time

      URL: http://[ip]:[port]/zeroconf/time
      Return value format: json
      Method: HTTP post

      e.g.

      1
      2
      3
      4
      5
      6
      7
      {
          "deviceid":"1000001234",
          "data": {
            "timeZone":8,
            "date":"2020-12-15T06:31:14.115Z"
          }
      }

       

      AttributeTypeOptionalDescription
      timeZoneNumberNoTime zone, [-12,+14], can be a decimal, such as 7.5
      dateStringNoUTC

       

      Note:
      -The Historical Data of Sub-devices will only take effect after the time zone information is set, and does not affect the single-time statistics.

      Historical Data of Sub-device

      URL: http://[ip]:[port]/zeroconf/historicalData
      Return value format: json
      Method: HTTP post

      e.g.

      1
2
3
4
5
6
7
8
9
      {
  "deviceid": "100000140e",
  "data": {
    "subDevId": "123456",
    "outlet": 3,
    "dateStart": "2020-07-10 05:30",
    "dateEnd": "2020-07-10 19:10"
  }
}

       

      AttributeTypeOptionalDescription
      outletNumberNoChannel Number,[0,3]
      dateStartStringNoStart time; format: “yyyy-mm-dd hh:mm”
      dateEndStringNoEnd time, format: “yyyy-mm-dd hh:mm”

      Response

      1. Correct response:

      The Content-Type of the response header is application/octet-stream

      Returns Comma-Separated Values(CSV) file data. The file contains header and normal record lines. The title header contains the corresponding name of the record field. Each normal record line is a data record, and each record consists of 9 fields, separated by commas.

      The fields in the order from left to right are as follows:
      | Date | time | Outlet | Current(A) | Voltage(V) | Real power(W) | Reactive power(W) | Apparent power(W) | 5 Minutes Power Consumption(W·s) |

      e.g.
      Users query data from 00: 00 – 00: 20 on October 10, 2021.

      1
2
3
4
5
6
       Date, time, Outlet, Current(A), Voltage(V),Real power(W), Reactive power(W), 
      Apparent power(W), 5 Minutes Power Consumption(W·s)      
2021-10-10 , 0:0:0 , 0 , 0.00, 240.94, 0.56, 0.00, 0.55,172.00
2021-10-10 , 0:5:0 , 0 , 0.00, 241.41, 0.60, 0.00, 0.59,172.00
2021-10-10 , 0:10:0 , 0 , 0.00, 241.13, 0.51, 0.00, 0.55,173.00
2021-10-10 , 0:15:0 , 0 , 0.00, 240.94, 0.58, 0.00, 0.56,173.00
2021-10-10 , 0:20:0 , 0 , 0.00, 240.95, 0.57, 0.00, 0.57,173.00
      1. Error response:
        Refer to the general part.

      Note：
      -This function will be released after firmware version 1.1.0.
      -Support query data for up to 1 day.
      e.g. When the dateStart is “2020-07-10 05: 30”, dateEnd can be filled as “2020-07-11 00: 00” at most.

      URL: http://[ip]:[port]/zeroconf/monitor
      Return value format: json
      Method: HTTP post

      e.g.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      {
          "deviceid": "100000140e",
          "data": {
              "url": "http://www.123.com",
              "port": 7790,
              "subDevId": "123456",
              "outlet": 3,
              "time":180
          }
      }
      AttributeTypeOptionalDescription
      urlStringYesReal-time monitoring data reporting URL, format:”http://www.xxx.com/yyy”
      portNumberYesReal-time monitoring data reporting port, [1024,65535]
      subDevIdStringNoChip ID of sub-device
      outletNumberNoChannel Number, [0,3]
      timeNumberNoReal-time monitoring duration, [1,3600], Unit second

       

      Note:
      -The url only supports non-encrypted connections, and the monitoring data report format is http post request.
      -The url and port fields must be filled in or not filled in at the same time, you cannot fill in only one of them.

      Device report:

      1
      2
      3
      4
      5
      6
      7
      8
      9
      {
        "subDevId": 123456,
        "outlet": 3,
        "current": 100,
        "voltage": 22000,
        "actPow": 22000,
        "reactPow": 22000,
        "apparentPow": 22000
      }

       

      AttributeTypeOptionalDescription
      currentNumberNoReal-time current value, Unit: 0.01 A
      voltageNumberNoReal-time voltage value, Unit: 0.01 V
      actPowNumberNoReal-time actPow value, Unit: 0.01 W
      reactPowNumberNoReal-time reactPow value, Unit: 0.01 W
      apparentPowNumberNoReal-time apparentPow value, Unit: 0.01 W

      Reporting conditions:
      -The current change exceeds 0.03 A.
      -The voltage change exceeds 5 V.
      -The active power, reactive power, or apparent power change exceeds 2 W.

      WiFi SSID and Password Setting

      URL: http://[ip]:[port]/zeroconf/wifi
      Return value format: json
      Method: HTTP post

      e.g.

      1
      2
      3
      4
      5
      6
      7
      {
        "deviceid": "100000140e",
        "data": {
          "ssid": "eWeLink",
          "password": "WeLoveIoT"
        }
      }

       

      AttributeTypeOptionalDescription
      ssidStringNoSSID of the WiFi network to which the device will connect
      passwordStringNoPassword of the WiFi network to which the device will connect

      Note:
      -The new wifi setting will take effect the next time the wifi is connected.

      OTA Firmware

      URL: http://[ip]:[port]/zeroconf/upgrade
      Return value format: json
      Method: HTTP post

      e.g.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      {
        "deviceid": "1000xxxxxx",
        "data": {
          "binList": [
            {
              "downloadUrl": "http://52.83.223.225:8088/ota/rom/hNLhVpovUgFJcipxmDD8fQv9b2BdJNgT/user1.1024.new.2.bin",
              "digest": "56a013b0f2ea151fb337a24025a5abb2f4390d4617c5ec57b27a79c86d6c4174",
              "name": "user1.bin"
            },
            {
              "downloadUrl": "http://52.83.223.225:8088/ota/rom/hNLhVpovUgFJcipxmDD8fQv9b2BdJNgT/user2.1024.new.2.bin",
              "digest": "62503540c241b4783bdc46026d86035b9d0775e2d48c59e40227be8067cadac6",
              "name": "user2.bin"
            }
          ]
        }
      }

       

      AttributeTypeOptionalDescription
      downloadUrlStringNoThe download address of the new firmware, only supports the HTTP protocol, the HTTP server must support the Range request header.
      sha256sumStringNoSHA256 checksum (hash) of the new firmware, it is used to verify the integrity of the new firmware downloaded.
      nameStringNoFirmware name

       

      The following failure codes are added to the error field of the response body：

      1. 404 Not Found (Download failed).
      2. 409 Firmware verification failed.

      Get Channel Operation Records

      URL: http://[ip]:[port]/zeroconf/record
      Return value format: json
      Method: HTTP post

      e.g.

      1
      2
      3
      4
      5
      6
      7
      8
      {
        "deviceid": "100000140e",
        "data": {
          "subDevId": "123456",
          "rangeStart": 200,
          "rangeEnd": 229
        }
      }

       

      AttributeTypeOptionalDescription
      rangeStartNumberNoStart number of operation records, [0,65535]
      rangeEndNumberNoEnd number of operation records, [0,65535]

      Response body

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      {
          "seq": 2,
          "error": 0,
          "data": {
              "record": [
                  {
                      "date": "2020-07-29 18:00:05",
                      "trigType": 1,
                      "outlet": 1,
                      "action": 1
                  },
                  {
                      "date": "2020-07-29 18:02:05",
                      "trigType": 0,
                      "outlet": 1,
                      "action": 0
                  }
              ]
          }
      }

       

      AttributeTypeOptionalDescription
      dateStringNoOperating time; format: “yyyy-mm-dd hh:mm”
      trigTypeNumberNo[0,3], 0: APP trigger; 1: Device trigger; 2: Overload protection trigger; *3: *Over-temperature protection trigger
      outletNumberNoChannel Number, [0,3]
      actionNumberNo0: Channel closed;
      1: Channel open

      Note:
      -The conditions need to be met: rangeEnd>=rangeStart and rangeEnd-rangeStart<=29.

      Get Device State

      URL: http://[ip]:[port]/zeroconf/getState
      Return value format: json
      Method: HTTP post

      e.g.

      1. Get gateway status:

      1
      2
      3
      4
      5
      {
          "deviceid":"1000001234",
          "data": {
          }
      }

       

      Response body

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      {
          "seq": 2,
          "error": 0,
          "data": {
              "sledOnline":"on",
              "ssid": "eWeLink",
              "fwVersion": "3.5.0",
              "subChipFwVer": "3.5.0",
              "deviceid": "100000140e",
              "bssid": "xx:xx:xx:xx:xx:xx",
              "signalStrength": -10,
              "wifiConnected": true/false
          }
      }

       

      2. Get sub-device status:

      1
      2
      3
      4
      5
      6
      {
          "deviceid":"1000001234",
          "data": {
              "subDevId": "123456"
          }
      }

       

      Response body

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      65
      66
      67
      68
      69
      70
      71
      72
      73
      74
      75
      {
          "seq": 2,
          "error": 0,
          "data": {
            	"fwVersion": "1.1.1",
              "switches": [
                  {
                      "outlet":0,
                      "switch":"on"
                  },
                  {
                      "outlet":1,
                      "switch":"on"
                  },
                  {
                      "outlet":2,
                      "switch":"on"
                  },
                  {
                      "outlet":3,
                      "switch":"on"
                  }
              ],
              "overload_00": 
              {
                  "minAP": {
                      "en": 0,
                      "val": 110000
                  },
                  "maxAP": {
                      "en": 1,
                      "val": 10000
                  },
                  "minV": {
                      "en": 1,
                      "val": 1000
                  },
                  "maxV": {
                      "en": 0,
                      "val": 22000
                  },
                  "maxC": {
                      "en": 1,
                      "val": 2000
                  },
                  "delayTime": 10
              },
              "overload_01":{},
              "overload_02":{},
              "overload_03":{},
              "faultState": {
                  "subDevCom": 0,
                  "cse7761Com": [
                      1,
                      0,
                      1,
                      1
                  ]
              },
              "threshold": {
                  "actPow":{
                      "min":10,
                      "max":440000
                  },
                  "voltage":{
                      "min":10,
                      "max":440000
                  },
                  "current":{
                      "min":10,
                      "max":440000
                  }
              }
          }
      }

       

      AttributeTypeDescription
      subDevComNumberSub-device 485 communication status. 1: Communication is normal. 0: Communication error.
      cse7761ComArraySub-device cse7761 communication error. Array elements are Number type. The quantity is 4. Elements 0-3 are 1-4 channels respectively. [0,1] 1: Communication is normal. 0: Communication error.
      fwVersionStringThe gateway is the firmware version of the main chip, and the sub-device is the firmware version number of the sub-device.
      subChipFwVerStringThe firmware version of the sub-chip.
      wifiCinnectedBoolCheck if wifi is connected. When false, the values of ssid, bssid and signalStrength are invalid.
      thresholdObjectThreshold range.
      actPowObjectReal Power, Unit: 0.01 W
      voltageObjectVoltage, Unit: 0.01 V
      currentObjectCurrent, Unit: 0.01A
      minNumberMinimum
      maxNumberMax

      URL: http://[ip]:[port]/zeroconf/ops_mode
      Return value format: json
      Method: HTTP post

      e.g.

      1
      2
      3
      4
      5
      6
      {
          "deviceid":"1000001234",
          "data": {
              "ops_mode": "ewelink"
          }
      }

       

      Note:
      “ops_mode”: “ewelink” means switch back to ewelink mode.

       

      Pin It on Pinterest