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": 9000
                  },
                  "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, [9000,24000], Unit: 0.01 V
      maxVNumberNoMax.vpltage, [9000,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
        urlStringNoReal-time monitoring data reporting URL, format:”http://www.xxx.com/yyy”
        portNumberNoReal-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.

        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