SONOFF DIY MODE API PROTOCOL

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.

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:

1. Entering the Compatible Pairing Mode (AP) by long press the paring button for 5 seconds after power on
2. Connecting the Access Point named ITEAD-XXXXXXXXXX with default password 12345678 via mobile phone or PC
3. Browser visits http://10.10.7.1/
4. Filling in the existing WiFi network SSID and password
5. Entering DIY Mode successfully with specific WiFi network connected.

Example for Single Channel DIY Plug (BASICR3, RFR3, MINI/MINIR2, MINIR3) enters DIY Mode:

1. Power on;
2. Long press the button for 5 seconds to enter Compatible Pairing Mode (AP)
   User tips: If the device has been paired with eWeLink APP, reset the device is necessary by long press the pairing button for 5 seconds, then press another 5 seconds for entering Compatible Pairing Mode (AP)
3. The LED indicator will blink continuously
4. From mobile phone or PC WiFi setting, an Access Point of the device named ITEAD-XXXXXXXXXX will be found, connect it with default password 12345678
5. Open the browser and access http://10.10.7.1/
6. Next, fill in WiFi SSID and password that the device would have connected with
7. Succeed, now the device is in DIY Mode.

Example for Single Channel DIY Dimmer (D1) enters DIY Mode:

1. Power on;
2. Long press the pairing button of RM433 remote controller for 5 seconds to enter Compatible Pairing Mode (AP)
   User tips: If the device has been paired with eWeLink APP, reset the device is necessary by long press the pairing button of RM433 remote controller for 5 seconds, then press another 5 seconds for entering Compatible Pairing Mode (AP)
3. The dimmable Light which is connected with D1 will blink continuously (promptly jump 100% to 1%, 1% to 100% … )

Steps of 4 – 7 are same as the example of Single Channel DIY Plug.

Example for Smart Power Meter (SPM-Main) enters DIY Mode:

1. Power on;
2. Long press the button on SPM-Main for 5 seconds to enter Bluetooth Pairing Mode.
   User tips: If the device has been paired with eWeLink APP, reset the device is necessary by long pressing the pairing button for 5 seconds to enter Bluetooth Pairing Mode.
3. The LED indicator will blink quickly.
4. Connect SPM-Main to your router using an Ethernet cable, and one of the following methods is available to connect.
5. Type the IP address of SPM-Main in the browser on your computer and access.
6. Next, enter the WiFi SSID and password.
7. Succeed. Now the device is in DIY Mode.

Example for Smart LED Bulb (B02-BL-A60, B05-BL-A19,B05-BL-A60) enters DIY Mode:

1. Power on;
2. When the light is on, press the light switch 5 times repeatedly at an interval of every 1s (Off-ON-Off-ON- Off-ON-Off-ON-Off-ON).
3. The “quick flash” indicates the device enters the Compatible Pairing Mode (AP).
4. From mobile phone or PC WiFi setting, an Access Point of the device named ITEAD-XXXXXXXXXX will be found, connect it with default password 12345678
5. Open the browser and access http://10.10.7.1/
6. Next, fill in WiFi SSID and password that the device would have connected with
7. Succeed, now the device is in DIY Mode.

Note:

• The user settings will be cleaned once the operation mode is changed from one to another.
• The WiFi router or AP should work in 2.4GHz and support mDNS service.
• LED blinking meanings
  Fast single blinking – The device does not connect to the WiFi network;
  Fast double blinking – The device connects to the WiFi successfully and is able to be discovered through mDNS and respond the request from LAN network.
• Once the device is already in DIY Mode, the WiFi configuration page of http://10.10.7.1/ is not accessible.
• If a wrong WiFi SSID or password was entered, the device will fail to connect with specific WiFi network, with 20 seconds timeout mechanism, the device stop connecting WiFi network, please try again with the example steps of 1-7.
• Official firmware upgrade is only available in eWeLink APP.
• The protocol v1.4 can be accessed via https://github.com/itead/Sonoff_Devices_DIY_Tools

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:

TXT Record note：

1. TXT Record must contain below strings:
   “txtvers=1”, “id=[device ID]”, “type=[device type]”, “apivers=[device API interface version]”, “seq=[TXT Record serial number]”, “data1=[device information]”;
2. Optional strings:
   “data2=[device information]”, “data3=[device information]”, “data4=[device information]”
3. “seq=[TXT record sequence number]” indicates the order in which the TXT records are updated (the order in which the device status is updated). It is recommended to be a positive integer that increments from 1 (reset to 1 when the device restarts);
4. When the device information is longer than 249 bytes, the first 249 bytes must be stored in data1, and the remaining bytes are divided by length 249, which are stored in data2, data3, and data4. The complete device information format is a JSON object.

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:

1. Search in the LAN for all devices with the service type _ewelink._tcp through the DNS PTR record.
2. Get the Hostname and Port of device service via parsing out the device DNS SRV record. (The default port is 8081)
3. Get device IP address via DNS A record or by other means.
4. Get the info of “device ID”, “Service Type”, “device API interface version” and “device information” via parsing out the device DNS TXT Record.

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:

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

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

Note:

• Due to the device computing capability, the time interval of each HTTP request should be no less than 200ms.
• The default Port: 8081