DIY MODE API PROTOCOL
— SONOFF DIY Mode Overview
— Supported Device
—eWeLink Mode and DIY Mode
—DIY Mode LAN Discovery
Mechanism
—Device mDNS Service Info
Publish Process
—Discovery Process for Device
Service
—RESTful API Control Protocol
(HTTP POST)
—RESTful API Request and
Response Format
BASICR3/RFR3/MINI HTTP API
B02-BL/B05-BL HTTP API
D1 HTTP API
MINIR3 HTTP API
SPM MAIN HTTP API
Reference
Version: 2.2 Date: 2021-11-1
Do you want to control the SONOFF device via your own app or home automation platform? DIY Mode helps!
The DIY Mode is designed for IoT home automation users and developers who would like to control the SONOFF device via existing home automation open-source platform or local HTTP client instead of eWeLink App. In DIY Mode, when the device is connected with the network, it will publish its services and capabilities according to the mDNS/DNS-SD standard. Before publishing the service, the device has enabled the HTTP server on the port declared by the DNS SRV record. Device exposes the capabilities through an HTTP-based RESTful API. Users can obtain device information, control the device by sending an HTTP API request.
Product Class | Device | Firmware version note |
---|---|---|
Single Channel DIY Plug | Firmware 3.5.0 refers to this article Firmware 1.4.0 refers to this article | |
Single Channel DIY Dimmer | D1 | Firmware 3.5.0 refers to this article |
Smart Power Meter | SPM-Main | Firmware 1.2.0 refers to this article |
Smart LED Bulb | Firmware 1.4.0 refers to this article |
The SONOFF devices [1] can work in either eWeLink mode or DIY Mode, In eWeLink mode, the device is connected with eWeLink cloud and controlled by eWeLink APP, while in DIY Mode, device publishes its capability service and is controlled by HTTP Post request.
The steps of entering the DIY Mode and connecting to an existing WiFi network:
Example for Single Channel DIY Plug (BASICR3, RFR3, MINI/MINIR2, MINIR3) enters DIY Mode:
Example for Single Channel DIY Dimmer (D1) enters DIY Mode:
Steps of 4 – 7 are same as the example of Single Channel DIY Plug.
Example for Smart Power Meter (SPM-Main) enters DIY Mode:
Example for Smart LED Bulb (B02-BL-A60, B05-BL-A19,B05-BL-A60) enters DIY Mode:
Note:
DIY Mode LAN discovery implements IETF Multicast DNS protocol and DNS‑Based Service Discovery protocol. [2]–[8]
The device publishes its own service (i.e. device capability) according to the mDNS/DNS-SD standard discovery protocol when the device is connected to LAN (Local Area Network).
The fields definition as follow:
Attribute | Description | Example |
---|---|---|
IP Address | The LAN IP Address is obtained through DHCP instead of the Link‐Local address of IPv4/IPv6 | |
Hostname | The Hostname must be unique in LAN; Format: eWeLink_[Device ID] | eWeLink_10000000d0 |
Service Type | _ewelink._tcp | |
Service Instance Name | The Service Instance Name must be unique in LAN; Max: 63 bytes (21 UTF8 Characters) | same as Hostname |
TXT Record | One or more strings; No exceeded 255 bytes for each string; No exceeded 1300 bytes for the entire TXT record; |
TXT Record note:
For BASICR3, RFR3, MINI mDNS txt record example:
data1={“switch”:”on”,”startup”:”stay”,”pulse”:”on”,”pulseWidth”:2000,”rssi”:-67,”fwVersion”:”3.5.0”}
For D1 (Dimmer) mDNS txt record example:
data1={“switch”: “on”,”mode”: 0,”brightness”: 50,”brightMin”:0,”brightMax”:255,”startup”: “on”,”rssi”:-67,”fwVersion”:”3.5.0”}
For SPM-Main mDNS txt record example:
data1={“subDevId”: “123456”,”switches”: [{“switch”: “on”,”outlet”: 0},{“switch”: “on”,”outlet”: 1},{“switch”: “on”,”outlet”: 2},{“switch”: “on”,”outlet”: 3}]}
For MINIR3 mDNS txt record example:
data1={“switches”:[{“switch”:”on”,”outlet”:0},{“switch”:”off”,”outlet”:1},{“switch”:”off”,”outlet”:2},{“switch”:”off”,”outlet”:3}],”sledOnline”:”on”}
For B02-BL-A60, B05-BL-A19, B05-BL-A60 txt record example:
data1={“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}
Whenever content other than seq changes, such as Service Instance Name is modified, device information is updated, etc., the device must multicast the corresponding DNS record (including the incremented seq) according to the mDNS/DNS-SD standard.
The discovery process must follow the mDNS/DNS-SD Discovery protocol to discover the Sonoff DIY Mode device with “_ewelink._tcp” service type when your application or client connect with Internet (WiFi or Ethernet);
Here is the discovery process:
Note:
When the “device type” of the device service does not match with the “device type” of your application or client, or the device API interface version of the device service is higher than your application or client’s, the application or client should not parse out the “device information” and call the device API interface, but prompt the specific reason for users why the device cannot be controlled via LAN and suggest to upgrade the application or client.
The application or client get the IP address of the device via DNS A record when the device API interface is about to be called.
The device must open the HTTP server in the port declared by the DNS SRV record before the device publishes its services; the device publishes the capabilities through a HTTP-based RESTful API. Because of the LAN’s security and device’s limited computing power, this document recommends that the device provides HTTP instead of HTTPS interface.
The device type and API interface version of each product is shown as below:
Product | type | apivers |
---|---|---|
diy_plug | 1 | |
D1 | diylight | 1 |
SPM-Main | diy_meter | 1 |
B02-BL-A60 B05-BL-A19 B05-BL-A60 | diy_light | 1 |
URL: http://[ip]:[port]/[path]
Return value format: json
Method: HTTP post
RESTful API Request works in POST method and JSON formatted request body.
1 2 3 4 5 6 | { "deviceid": "100000140e", "data": { "switch": "on" } } |
Attribute | Type | Example | Optional | Description |
---|---|---|---|---|
deviceid | String | 100000140e | Yes | The device ID for this request. |
data | Object | {“switch”: “on”} | No | Object type, Specific device information setting when controlling the device. Empty object when check the device information |
RESTful API Response works in 200 OK HTTP response code and JSON formatted response body.
1 2 3 4 5 6 7 | { "seq": 2, "error": 0, "data": { "signalStrength": -67 } } |
Attribute | Type | Optional | Description |
---|---|---|---|
seq | Number | No | The order of device status update (also the order of TXT Record update) |
error | Number | No | Whether the device successfully sets the specified device information. – 0: successfully – 400: The operation failed and the request was formatted incorrectly. The request body is not a valid JSON format. – 401: The operation failed and the request was unauthorized. Device information encryption is enabled on the device, but the request is not encrypted. – 404: The operation failed and the device does not exist. The device does not support the requested deviceid. – 422: The operation failed and the request parameters are invalid. For example, the device does not support setting specific device information. |
data | Object | No | Object type, it returns specific device info when check the device information |
Note: