fbpx

SONOFF

D1 HTTP API

Version: 2.2  Date: 2021-11-15

D1 HTTP API

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

ON/OFF Switch

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

e.g.

1
2
3
4
5
6
{ 
"deviceid": "",
"data": {
"switch": "on"
}
}

 

Attribute Type Optional Description
switch String No on: turn the switch on, off: turn the switch off

 

Dimmable

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

e.g.

1
2
3
4
5
6
7
8
9
10
{ 
    "deviceid": "", 
    "data": {
        "switch": "on", 
        "brightness": 30,
        "mode": 0,
        "brightmin": 10, 
        "brightmax": 255
    } 
 }

 

Attribute Type Optional Description
switch String No The “switch” field must be “on”
brightness Number No Light brightness, [1~100], positive integer
mode Number Yes Device mode, [0-255], positive integer
brightmin Number Yes Minimum brightness, [0~254], positive integer
brightmax Number Yes Maximum brightness, [1~255], positive integer

 

Note:

  • To adjust the brightness of the light, the light must be “on”, so if send a Dimmble API request with “switch”: “off”, it will report “400” error as operation failed.
  • The “mode” parameter is used for APP development to define different modes with specific brightness, and sync the modes content of the device when sharing the device operation to others.
    For instance:
    The APP of the developer defines two modes (mode 1: brightness=5; mode 2: brightness=50) that the device can reach a specific brightness by buttons, the “mode” parameter provides the way to sync the device mode for all shared users.
  • The value of brightmin should be less than brightmax.

Power-on State

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

e.g.

1
2
3
4
5
6
{ 
"deviceid": "",
"data": {
"startup": "stay"
}
}

 

Attribute Type Optional Description
startup String No on: the device is on when power supply is recovered.
off: the device is off when power supply is recovered.
stay: the device status keeps as the same as the state before power supply is gone

 

    WiFi Signal Strength

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

    Request body

    e.g.

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

     

    Empty object, no attribute is required.

    Response body

    e.g.

    1
    2
    3
    4
    5
    6
    7
    { 
    "seq": 2,
    "error": 0,
    "data": {
    "signalStrength": -67
    }
    }

     

    Attribute Type Optional Description
    signalStrength Number No The WiFi signal strength currently received by the device, negative integer, dBm

     

      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": "",
      "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

       

      OTA Function Unlocking

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

      e.g.

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

       

      Empty object, no attribute is required.

      The following failure codes are added to the error field of the response body:
       500: The operation failed and the device has errors. For example, the device ID or API Key error which is not authenticated by the vendor’s OTA unlock service;
       503: The operation failed and the device is not able to request the vendor’s OTA unlock service. For example, the device is not connected to WiFi, the device is not connected to the Internet, the manufacturer’s OTA unlock service is down, etc.

      OTA New Firmware

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

      e.g.

      1
      2
      3
      4
      5
      6
      7
      { 
      "deviceid": "",
      "data": {
      "downloadUrl": "http://192.168.1.184/ota/new_rom.bin",
      "sha256sum": "3213b2c34cecbb3bb817030c7f025396b658634c0cf9c4435fc0b52ec9644667"
      }
      }

       

      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

       

      The following failure codes are added to the error field of the response body:
       403: The operation failed and the OTA function was not unlocked. The interface “3.2.6 OTA function unlocking” must be successfully called first.
       408: The operation failed and the pre-download firmware timed out. You can try to call this interface again after optimizing the network environment or increasing the network speed.
       413: The operation failed and the request body size is too large. The size of the new OTA firmware exceeds the firmware size limit allowed by the device.
       424: The operation failed and the firmware could not be downloaded. The URL address is unreachable (IP address is unreachable, HTTP protocol is unreachable, firmware does not exist, server does not support Range request header, etc.)
       471: The operation failed and the firmware integrity check failed. The SHA256 checksum of the downloaded new firmware does not match the value of the request body’s sha256sum field. Restarting the device will cause bricking issue.

      Note:

      • The maximum firmware size is 508KB.
      • The SPI flash read mode must be DOUT.

      Get Device Info

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

      e.g.

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

       

      Empty object, no attribute is required.

      Response body

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      { 
      "seq": 2,
      "error": 0,
      "data": {
      "switch": "off",
      "startup": "off",
      "brightness": 30,
      "mode": 0,
      "brightmin": 10,
      "brightmax": 255,
      "ssid": "eWeLink",
      "otaUnlock": false,
      "fwVersion": "3.5.0",
      "deviceid": "100000140e",
      "bssid": "ec:17:2f:3d:15:e",
      "signalStrength": -25
      }
      }

       

      Note:

      • Monitor and parse the device’s DNS TXT record to get the device information in real time.

      Pin It on Pinterest

      Share This