Sonoff smart relays are a very affordable devices that allows you to control AC powered furnitures using your wifi network. You can connect these relays to an OpenSource smart home software like jeedom or homeassistant. However, by default, Sonoff devices are preinstalled with a proprietary software from ITEAD and can only be controlled using eWiLink app which relies on a cloud based service. Fortunately, starting 2019, there are Sonoff devices labeled DIY which can be flashed to use Tasmota: an OpenSource firmware to control small smart devices based on ESxyz chips which the Sonoff mini relies on.


If you want to build your own smart home solution based on Sonoff hardware  that do not rely on any proprietary software and that allows you to be autonomous and have interoperability, the first step then, is to install Tasmota on it. Be sure that the Sonoff devices that you buy is labeled “DIY” otherwise you will have to proceed to a hardware flashing which much more complex.
In this article, we will cover how to install Tasmota on Sonoff Mini Devices using Linux or MacOSX. We will rely only on simple tools available on internet and that can be scripted using command line.


In a nutshell (TL;DR)

I wish I can have more time to fully automate this, but here a script snippet, that you can use to do the whole process if you know your device ID, the Sonoff IP address and your IP address:

curl -sSf | sh 
cargo install simple-http-server
curl -s http://$DEVICE_IP:8081/zeroconf/ota_unlock -XPOST -d '{"deviceid":"$DEVICE_ID","data":{}}'
cd $HOME/tasmota-firmwares
mkdir -p api/device/otaFlash
SHA256=$(sha256-sum tasmota-basic.bin | cut -f1 -d\ )
simple-http-server &
curl http://DEVICE_IP:8081/zeroconf/ota_flash -X POST \
     -d '{"deviceid": "$DEVICE_ID" , \
          "data": {"downloadUrl": "http://$SERVER_IP:8000/tasmota-basic.bin" , \
                   "sha256sum": "$SHA256" } \


Preparing your Sonoff device

Upgrade original firmware and set the DIY jumper

To be able to perform Over The Air (OTA) firmware upgrade, you will have to be sure that your Sonoff device has an ITEAD firmware version greather or equal to 3.1. I bought my devices on nov 2019, and they were shipped with a 3.0 firmware. We cover the article “First steps with your Sonoff WiFi Switch”.


Secondly, you will have to open your Sonoff swith and connect the two DIY pins with the provided jumper. Your device is then ready.

Sofware Requirements

We will do it with very simple tools: curl and simple-http-server.

curl is available on many platforms that fortunately includes OSX, Linux and even Windows.


The second requirement is an HTTP Server that supports the “Range” header properly. That means that Python SimpleHTTPServer does not work. I also tried from github but with no success. The support of the Range HTTP header is required because Sonoff devices have small amount of memory. The Range header allows to specify a range of data  that the request wants to grab. This endups as the server send HTTP 206 responses when the requests is satisfied.


simple-http-server written in Rust language and available using the cargo package manager. You can use Apache or nginx but, sometimes they are hard to install and configure, where simple-http-server is just a single line command that will start an HTTP Server on port 8080 to server the directory in which is has been started.

The curl command is installed by default on OSX or Linux, so you don’t have anything special for it.


Install cargo package manager if you don’t have it already:

curl -sSf | sh
info: downloading installer
Welcome to Rust!
This will download and install the official compiler for the Rust
programming language, and its package manager, Cargo.
It will add the cargo, rustc, rustup and other commands to
Cargo's bin directory, located at:


Then install simple-http-server: If it is your first cargo application, it will download a hunderd of packages first.


$ cargo install simple-http-server
>     Updating index

Downloaded simple-http-server v0.4.7

Downloaded 1 crate (222.1 KB) in 1.48s

Compiling multipart v0.16.1

Compiling simple-http-server v0.4.7

Finished release [optimized] target(s) in 2m 24s

Installing /Users/akram/.cargo/bin/simple-http-server

Installed package `simple-http-server v0.4.7` (executable `simple-http-server`)


Flashing the Sonoff with Tasmota


In the following step, I assume that you have setup your laptop has an IP address of .


The IP address of your Sonoff device can also be fixed if you setup DHCP lease reservations on your router, but, I will assume that we neither know the IP address of the Sonoff devices nor its device ID.

Sonoff devices are configured by default to announce themselves using the Bonjour/avahi protocol. So, you can detect them using the dns-sd command and filter on the service named _ewelink._tcp . All the Sonoff devices connected to your network will appear here.


$ dns-sd -B _ewelink._tcp
> Browsing for _ewelink._tcp
DATE: —Sat 28 Sep 2019—
13:59:15.223  …STARTING…
Timestamp     A/R Flags if Domain               Service Type Instance Name
13:59:15.507  Add 2 5 local.               _ewelink._tcp. eWeLink_10009abcde
^C   (i.e. press CtrlC to exit..168.1.127


You can get then its IP address using a simple DNS resolution:


$ nslookup eWeLink_10009abcde


By default, sonoff devices with stock firmware will listen on port 8081.  To know if your Sonoff device is properly connected and answering requests, you can POST a simple HTTP query to your device address on port 8081 with the following JSON payload:


$ curl -s -XPOST -d ‘{“deviceid”:”10009abcdef”,”data”:{}}’
> {

“seq”: 2,

“error”: 0,

“data”: “{\”switch\”:\”off\”,\”startup\”:\”off\”,\”pulse\”:\”off\”,\”pulseWidth\”:500,\”ssid\”:\”sonoffDiy\”,\”otaUnlock\”:false}”



My sonoff device does not allow OTA (Over The Air) updates by default, so we need to change this using the following command:


$ curl -s -XPOST -d ‘{“deviceid”:”10009abcdef”,”data”:{}}’
> {

“seq”: 3,

“error”: 0



Once the command passes, the otaUnlock attribute becomes “true”:

$ curl -s -XPOST -d ‘{“deviceid”:”10009abcdef”,”data”:{}}’
> {

“seq”: 4,

“error”: 0,

“data”: “{\”switch\”:\”off\”,\”startup\”:\”off\”,\”pulse\”:\”off\”,\”pulseWidth\”:500,\”ssid\”:\”sonoffDiy\”,\”otaUnlock\”:true}”



Create a directory to store firmwares, and creat an empty directory named api/device/otaFlash and theb download the tasmota-basic firmware using the following commands:


$ cd $HOME/tasmota-firmwares && mkdir -p api/device/otaFlash && \


> –2019-11-30 09:52:36–

Resolving (…

Connecting to (||:80… connected.

HTTP request sent, awaiting response… 200 OK

Length: 575664 (562K) [application/octet-stream]

Saving to: ‘tasmota-basic.bin’

tasmota.bin                                        100%[===============================================================================================================>] 562.17K  3.49MB/s in 0.2s

2019-11-30 09:52:37 (3.49 MB/s) – ‘tasmota-basic.bin’ saved [575664/575664]


At the end of the flashing process, the sonoff device tries to POST a query on /api/device/otaFlash . This empty directory may be useless.


It is now the moment to start our simple-http-server in a directory containing the tasmota-basic.bin firmware:


$ simple-http-server
>     Index: disabled, Upload: disabled, Cache: enabled, Cors: disabled, Range: enabled, Sort: enabled, Threads: 3

Auth: disabled, Compression: disabled

https: disabled, Cert: , Cert-Password:

Root: /Users/akram/tasmota-firmwares,



======== [2019-11-30 22:33:06] ========


Your Sonoff device is now ready to receive the command to allow it to download the new firmware from the simple-http-server:

$ curl -X POST \

-d ‘{“deviceid”: “100098a8c4” , \

“data”: {“downloadUrl”: ““, \

“sha256sum”: “d12c8fb96b4cce4d570124488ebf874922fb2c2412d1001f37f01b9e1b580435” } \


> {

“seq”: 3,

“error”: 0



On the simple-http-server window terminal you should see something like:


> [2019-11-30 22:33:27] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:27] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:27] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:27] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:28] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:28] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:28] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:28] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:28] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:28] – – 206 – GET /tasmota-basic.bin

[2019-11-30 22:33:29] – – 200 – POST /api/device/otaFlash


Your Sonoff device may now be flashed and running the Tasmota-Basic firmware. As it is unconfigured, your device will start a simple Access Point on which you can connect to configure at most 2 wifi SSID and password where the device can connect on boot.


To continue the process, you need to connect your laptop to a Wifi AP named SONOFF_12345 (where 12345 is an ID hardcoded in the hardware). Your laptop may redirect you directly to a login page similar to one you use to connect to public Access Points. This is the Tasmota configuration page.

If you don’t, and  if you are using DHCP, your Sonoff device may still have the same IP address, so you can try to reach on your browser:


Once configured, you can restart you device, and it will automatically connect to first wifi network you specified on your configuration of the 2nd one if it cannot reach the first one.


If you want to restart the configuration process, you have to press your Sonoff device button for 40 long seconds until it stops blinking, and then the configuration Access Point named SONOFF_12345 will be available again.


Last modified: 1st December 2019