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

 

Attribute Type Optional Description
switch String No on: 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}
 }
}

 

Attribute Type Optional Description
ltype String No Light Mode, include white,color,bright,goodNight,read,nightLight,party,leisure,soft,colorful
white Object Change the type to cool & warm
color Object Change the type to RGBCW
bright Object Change the Scene to “Bright”
goodNight Object Change the Scene to “Sleep”
read Object Change the Scene to “Read”
nightLight Object Change the Scene to “Night”
party Object Change the Scene to “Party”
leisure Object Change the Scene to “Relax”
soft Object Change the Scene to “Soft”
colorful Object Change the Scene to “Vivid”
br Number No Brightness, [1,100]
ct Number No Color temperature, [0,100]
r Number No Red value, [0,255]
g Number No Green value, [0,255]
b Number No Blue value, [0,255]
tf Number No Color transformation mode, [1,3]
sp Number No Color transformation speed, [1,100]

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

 

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

 

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

 

Attribute Type Optional Description
signalStrength Number No The 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"
    } 
}

 

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.

Pin It on Pinterest

Share This