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

 

Attribute Type Description
switches Array Switch status of all channels
outlet Number Channel Number, [0,3]
switch String on: turn the switch on, off: turn the switch off
subDevCom Number Sub-device 485 communication status. 1: Communication is normal, 0: Communication error
overloadTrig Array Overload protection trigger event. This field appears when there is an overload event.
cse7761Com Array Sub-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.
overTemp Array Sub-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.
overLimit Array Limit 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
      }
    ]
  }
}

 

Attribute Type Optional Description
subDevId String No Chip ID of sub-device
type Number No Type 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
      }
    ]
  }
}

 

Attribute Type Optional Description
switch String No on: turn the switch on, off: turn the switch off
outlet Number No Channel 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":{}
        },
    }

     

    Attribute Type Optional Description
    minAP Number No Min.power, [10,440000], Unit: 0.01 W
    maxAP Number No Max.power, [10,440000], Unit: 0.01 W
    minV Number No Min.voltage, [10,24000], Unit: 0.01 V
    maxV Number No Max.vpltage, [10,24000], Unit: 0.01 V
    maxC Number No Max.current, [10,2000], Unit: 0.01 A
    delayTime Number No Delay to switch off, [0,180]
    en Number No 0: Disable overload protection.
    1: Enable overload protection.
    val Number No Upper 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"
          }
      }

       

      Attribute Type Optional Description
      timeZone Number No Time zone, [-12,+14], can be a decimal, such as 7.5
      date String No UTC

       

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

       

      Attribute Type Optional Description
      outlet Number No Channel Number,[0,3]
      dateStart String No Start time; format: “yyyy-mm-dd hh:mm”
      dateEnd String No End 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
          }
      }
      Attribute Type Optional Description
      url String Yes Real-time monitoring data reporting URL, format:”http://www.xxx.com/yyy”
      port Number Yes Real-time monitoring data reporting port, [1024,65535]
      subDevId String No Chip ID of sub-device
      outlet Number No Channel Number, [0,3]
      time Number No Real-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
      }

       

      Attribute Type Optional Description
      current Number No Real-time current value, Unit: 0.01 A
      voltage Number No Real-time voltage value, Unit: 0.01 V
      actPow Number No Real-time actPow value, Unit: 0.01 W
      reactPow Number No Real-time reactPow value, Unit: 0.01 W
      apparentPow Number No Real-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"
        }
      }

       

      Attribute Type Optional Description
      ssid String No SSID of the WiFi network to which the device will connect
      password String No Password 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"
            }
          ]
        }
      }

       

      Attribute Type Optional Description
      downloadUrl String No The download address of the new firmware, only supports the HTTP protocol, the HTTP server must support the Range request header.
      sha256sum String No SHA256 checksum (hash) of the new firmware, it is used to verify the integrity of the new firmware downloaded.
      name String No Firmware 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
        }
      }

       

      Attribute Type Optional Description
      rangeStart Number No Start number of operation records, [0,65535]
      rangeEnd Number No End 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
                  }
              ]
          }
      }

       

      Attribute Type Optional Description
      date String No Operating time; format: “yyyy-mm-dd hh:mm”
      trigType Number No [0,3], 0: APP trigger; 1: Device trigger; 2: Overload protection trigger; *3: *Over-temperature protection trigger
      outlet Number No Channel Number, [0,3]
      action Number No 0: 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
                  }
              }
          }
      }

       

      Attribute Type Description
      subDevCom Number Sub-device 485 communication status. 1: Communication is normal. 0: Communication error.
      cse7761Com Array Sub-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.
      fwVersion String The gateway is the firmware version of the main chip, and the sub-device is the firmware version number of the sub-device.
      subChipFwVer String The firmware version of the sub-chip.
      wifiCinnected Bool Check if wifi is connected. When false, the values of ssid, bssid and signalStrength are invalid.
      threshold Object Threshold range.
      actPow Object Real Power, Unit: 0.01 W
      voltage Object Voltage, Unit: 0.01 V
      current Object Current, Unit: 0.01A
      min Number Minimum
      max Number Max

      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