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

—ON/OFF Switch
—Inching
—Power-on State
—WiFi Signal Strength
—WiFi SSID and Password Setting
—OTA Function Unlocking
—OTA New Firmware
—Get Device Info

SONOFF

MINIR3 HTTP API

Version: 1.0 Date: 2022-3-11

MINIR3 HTTP API

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

NOTE: MINIR3 is a single-channel device, but it uses a multi-channel protocol. The protocol can control the switches of channels 1, 2, 3, and 4. MINIR3 uses the first channel.

ON/OFF Switch

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

e.g.

{
"deviceid": "1000000001",
"data": {
"switches": [
{ "switch": "on", "outlet": 0 },
{ "switch": "on", "outlet": 1 },
{ "switch": "off", "outlet": 2 },
{ "switch": "off", "outlet": 3 }
]
}
}

Attribute	Type	Optional	Description
switch	String	No	on: turn the switch on, off: turn the switch off
outlet	Number	No	Ranges: [0,3]; Represents channels: 1-4

Inching

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

Request body

e.g.

{
"deviceid": "1000000001",
"data": {
"pulses":[
{
"pulse":"on",
"switch":"on",
"width":2000,
"outlet":0
},
{
"pulse":"on",
"switch":"off",
"width":2000,
"outlet":1
},
{
"pulse":"off",
"switch":"on",
"width":2000,
"outlet":2
},
{
"pulse":"off",
"switch":"on",
"width":2000,
"outlet":3
}
]
}
}

Attribute	Type	Optional	Description
pulses	Array	No	Inching setting list
pulse	String	No	on: activate the inching function; off: disable the inching function
width	Number	Yes	Required when “pulse” is on, pulse time length, positive integer, ms, only supports multiples of 500 in range of 500~3599500
switch	String	No	You can set to on or off. The switch state after the end of inching. If set to on, after turning off the device, when the inching time is up, the device will be turned on.

Power-on State

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

e.g.

{
"deviceid": "1000000001",
"data": {
"configure": [
{ "startup": "on", "outlet": 0 },
{ "startup": "off", "outlet": 1 },
{ "startup": "off", "outlet": 2 },
{ "startup": "stay", "outlet": 3 }
]
}
}

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.

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

Empty object, no attribute is required.

Response body

e.g.

{ 
    "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.

{ 
    "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.

{ 
    "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.

{ 
    "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.

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

Empty object, no attribute is required.

Response body

{
"seq":2,
"error":0,
"data":{
"switches":[
{
"switch":"on",
"outlet":0
},
{
"switch":"off",
"outlet":1
},
{
"switch":"off",
"outlet":2
},
{
"switch":"off",
"outlet":3
}
],
"configure":[
{
"outlet":0,
"startup":"on"
},
{
"startup":"stay",
"outlet":1
},
{
"outlet":2,
"startup":"off"
},
{
"outlet":3,
"startup":"off"
}
],
"sledOnline":"on",
"pulses":[
{
"pulse":"on",
"switch":"on",
"width":2000,
"outlet":0
},
{
"pulse":"off",
"switch":"on",
"width":2000,
"outlet":1
},
{
"pulse":"off",
"switch":"on",
"width":2000,
"outlet":2
},
{
"pulse":"off",
"switch":"on",
"width":2000,
"outlet":3
}
],
"fwVersion" : "3.4.1",
"deviceid":"100000140e",
"bssid":"xx:xx:xx:xx:xx:xx",
"signalStrength":-67
}
}

Note:

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

SONOFF

MINIR3 HTTP API

MINIR3 HTTP API

ON/OFF Switch

Inching

Power-on State

WiFi Signal Strength

WiFi SSID and Password Setting

OTA Function Unlocking

OTA New Firmware

Get Device Info

Subscribe

Success!

Pin It on Pinterest