DIY MODE API PROTOCOL
    BASICR3/RFR3/MINI HTTP API
    B02-BL/B05-BL HTTP API

    —Get Device Info
    —Turn On&Off
    —Dimmable Light
    —WiFi SSID and Password Setting
    —WiFi Signal Strength
    —OTA Function Unlocking
    —OTA New Firmware

    D1 HTTP API
    MINIR3 HTTP API
    SPM MAIN HTTP API
    Reference

    SONOFF

    B02-BL/B05-BL HTTP API

    Version: 2.2  Date: 2022-5-13

    B02-BL/B05-BL HTTP API

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

    Get Device Info

    URL?http://[ip]:[port]/zeroconf/info

    Return value format: json

    Method: HTTP post

    eg.

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

    Response body

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

     

     

    Turn On&Off

    URL?http://[ip]:[port]/zeroconf/switch

    Return value format: json

    Method: HTTP post

    eg.

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

     

    AttributeTypeOptionalDescription
    switchStringNoon: turn the light on, off: turn the light off

     

    Dimmable Light

    URL?http://[ip]:[port]/zeroconf/dimmable

    Return value format: json

    Method: HTTP post

    eg.

    {
//Change the light to cool & warm type
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype": "white",
 "white": {"br": 70, "ct": 100}
 }
}
//Change the light to RGBCW type
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype": "color",
 "color": {"br": 100, "r": 255, "g": 0, "b": 0}
 }
}
//Bright
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype":"bright",
 "bright":{"r":255,"g":255,"b":255,"br":100} 
 }
}
//Sleep
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype": "goodNight",
 "goodNight": {"r":255,"g":250,"b":125,"br":25}
 }
}
//Read
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype":"read",
 "read":{"r":255,"g":255,"b":255,"br":60}
 }
}
//Night
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype":"nightLight",
 "nightLight":{"r":255,"g":240,"b":225,"br":5}
 }
}
// The following Scene can be modified options in the app
//Party
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype":"party",
 "party":{"r":254,"g":132,"b":0,"br":45,"tf":1,"sp":1}
 }
}
//Relax
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype":"leisure",
 "leisure":{"r":0,"g":40,"b":254,"br":55,"tf":1,"sp":1}
 }
}
//Soft
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype":"soft",
 "soft":{"r":38,"g":254,"b":0,"br":20,"tf":1,"sp":1}
 }
}
//Vivid
{
 "deviceid": "1000xxxxxx",
 "data":{
 "ltype":"colorful",
 "colorful":{"r":255,"g":0,"b":0,"br":100,"tf":1,"sp":1}
 }
}

     

    AttributeTypeOptionalDescription
    ltypeStringNoLight Mode, include white,color,bright,goodNight,read,nightLight,party,leisure,soft,colorful
    whiteObjectChange the type to cool & warm
    colorObjectChange the type to RGBCW
    brightObjectChange the Scene to “Bright”
    goodNightObjectChange the Scene to “Sleep”
    readObjectChange the Scene to “Read”
    nightLightObjectChange the Scene to “Night”
    partyObjectChange the Scene to “Party”
    leisureObjectChange the Scene to “Relax”
    softObjectChange the Scene to “Soft”
    colorfulObjectChange the Scene to “Vivid”
    brNumberNoBrightness, [1,100]
    ctNumberNoColor temperature, [0,100]
    rNumberNoRed value, [0,255]
    gNumberNoGreen value, [0,255]
    bNumberNoBlue value, [0,255]
    tfNumberNoColor transformation mode, [1,3]. 1: Static, 2: Gradual, 3: Flicker
    spNumberNoColor transformation speed, [1,100]. The bigger number, the faster speed.

    WiFi SSID and Password Setting

    URL?http://[ip]:[port]/zeroconf/wifi

    Return value format: json

    Method: HTTP post

    eg.

    1
2
3
4
5
6
7
    { 
    "deviceid": "", 
    "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

     

    WiFi Signal Strength

    URL?http://[ip]:[port]/zeroconf/signal_strength

    Return value format: json

    Method: HTTP post

    eg.

    1
2
3
4

    { 
    "deviceid": "1000000001", 
    "data": {} 
 }

    Response body

    eg.

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

     

    AttributeTypeOptionalDescription
    signalStrengthNumberNoThe WiFi signal strength currently received by the device, negative integer, dBm

     

     

    OTA Function Unlocking

    URL?http://[ip]:[port]/zeroconf/ota_unlock

    Return value format: json

    Method: HTTP post

    eg.

    1
2
3
4

    { 
    "deviceid": "", 
    "data": {} 
 }

     

    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

    eg.

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

     

    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

    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.

    Pin It on Pinterest