Posted on by Jean-Luc Aufranc (CNXSoft) - 43 Comments on How to Build and Flash ESPurna Open Source Firmware to Sonoff POW Wireless Switch

How to Build and Flash ESPurna Open Source Firmware to Sonoff POW Wireless Switch

ITEAD Studio Sonoff family is comprised of various inexpensive ESP8266 WiFi power switch, and the company sent me two of their latest CE certified models with Sonoff TH16 + external temperature & humidity probe, and Sonoff POW to measure power consumption. I checked the hardware is the first part of the review, and used Sonoff TH16 to control a water pump with the stock firmware and Ewelink Android app in the second part. It works reasonably well, but it relies on the cloud, so if you lose your Internet connection or the service closed, you can’t control the relay manually anymore. Luckily, the UART pins are exposed on Sonoff switches so you can solder a 4-pin header and connect a USB to TTL to flash your own firmware.

Click to Enlarge
Click to Enlarge

Please don’t connect Sonoff devices to the mains when programming them, it’s very dangerous, instead the USB to TTL board will power the system, and will allow you to program the board safely. Later you’ll be able to update the firmware, if needed, over the network.

The next step is to select the firmware you want to use, and I’ve been advised two firmware for ESP8266, namely ESPurna specifically designed for Sonoff devices, and ESPEasy with a larger community of users. The latter may be usable to control the relay, but it has yet to support HLW8012 chip used to measure power consumption in Sonoff POW, so I decided to go with ESPurna.

That’s the description of the firmware from its bitbucket page:

ESPurna (“spark” in Catalan) is a custom C firmware for ESP8266 based smart switches. It was originally developed with the ITead Sonoff in mind. Features:

  • Asynchronous WebServer for configuration and simple relay toggle with basic authentication
  • Communication between webserver and webclient via websockets with secure ticket check
  • Flashing firmware Over-The-Air (OTA)
  • Up to 3 configurable WIFI networks, connects to the strongest signal
  • MQTT support with configurable host and topic
  • Manual switch ON/OFF with button (single click the button)
  • AP mode backup (double click the button)
  • Manual reeset the board (long click the button)
  • Visual status of the connection via the LED
  • Alexa integration (Amazon Echo or Dot) by emulating a Belkin WeMo switch
  • Support for automatic over-the-air updates through the NoFUSS Library
  • Support for DHT22 sensors
  • Support for the HLW8012 power sensor present in the Sonoff POW
  • Support for current monitoring through the EmonLiteESP Library using a non-intrusive current sensor (requires some hacking)
  • Command line configuration

I could not find firmware release for ESPurna, but Xose Pérez – the developer – has provided some basic instructions to build and flash the firmware to Sonoff. Those are not really detailed however, and it took me nearly a full day to successfully build and flash the firmware to Sonoff POW, mostly because I was not quite familiar with most of the tools used. So I’ve reproduced the step I went through in Ubuntu 16.04, and hopefully this can help people getting things done more quickly.

Let’s retrieve the source code, and enter the code directory first:


You can build the project with PlatformIO or the Arduino IDE. The instructions are for PlatformIO so that’s what I used. There are two ways to build the code with the project wither using Platform IDE for Atom and the command line, or simply using the command line. With insights, I ended up using the command line, but I’ll show both methods.

Setup PlatformIO IDE for Atom to build ESPurna

First, you’ll need to download PlatformIO IDE for Atom for your operating systems, and install it. For Ubuntu 16.04, I selected “Download .deb” for Linux and installed it through through Ubuntu Software program. Alternatively, after download, you can install it from the command line:


You can now start Atom program in Ubuntu dash, select Open Project, and browse for espurna/code directory to load the project we’ve just gotten from Bitbucket.

Click to Enlarge
Click to Enlarge

The tick button on the top left corner is to build the project, and the right button just under is to upload the firmware to the target board. But if we try to build the firmware now it will fail with an error about “espressif8266_stage”. That’s because we need to install Espressif 8266 (Stage) development platform. First we need to enable Developer mode in the IDE by going to the top menu to select PlatformIO->Settings->PlatformIO IDE, and checking “Use development version of PlatformIO“.

platformio_core_enable_development_version
Click to Enlarge

Now install PlatformIO shell commands from either a system Terminal, or PlatformIO IDE terminal (PlatformIO->Terminal->New Terminal):


and finally install ESP8266 development platform:


At this point you can click on the tick icon to build the default “node-debug” environment, a build output window will show in the IDE, and quickly disappear if the build is successful.

Setup PlatformIO via Command Line to Build ESPurna

If instead we want to use the command line we can install the latest pip version, the developer version of PlatformIO, and the staging version of ESP8266 development platform:


You can check the build environment is set properly by running the following command in espurna/code directory:


It will automatically download, build and install all dependencies and build for “node-debug” firmware for NodeMCU board. If it is successful, it will end as follows:


So I find the command line option much more easy and straightforward.

Build ESPurna for Sonoff POW

However, we are not using NodeMCU board here, but Sonoff POW, and there are two environments defined just for that:

  • sonoff-pow-debug – Build firmware to flash over serial
  • sonoff-pow-debug-ota – Build OTA firmware to upgrade the firmware over the network

The parameters for each environment are all defined in platformio.ini. First we need to build sonoff-pow-debug environment:


But it failed with an error message related to hlw8012 library:


I reported the issue on Bitbucket, but the main developer could not reproduce the issue. Eventually I found out that it could be a PlatformIO bug, as the system does not recursively checking for includes outside of main.ino. So I added <hlw8012.h> in the main.ino as follows:


and the build could complete:


Since we’ve already changed the code, you may also consider changing “#define ADMIN_PASS  fibonacci” in code/src/config/general.h to use a different default password. The password can also be changed in the web interface, but this makes sure you won’t have a device somewhere with the default password common to most users.

Flashing Firmware to Sonoff POW

Now that we’ve made sure the firmware could build, it’s time to flash it to the device.

First we need to setup some udev rules to allow flashing over serial:

Now connect the USB to TTL to a USB port on your computer, press the button (connected to GPIO0) on Sonoff POW for several seconds until both LEDs are off to make sure you are in bootloader mode, and start flashing with:


Success! Great. If you have your own firmware to flash it may be useful to know the actual command used to flash the firmware was:

Building and Flashing the ESPurna filesystem

Wait! We’ve just flashed the firmware, isn’t it all? Nope, as the webserver files are stored in another partitions, and compressed in a single index.html.gz file for better performance. The exact reasons why are further explained here.

We’ll need Node.js and gulp command line client:


Now inside espurna/code folder , we can check if building the file systems works with two commands:


Here my successful gulp attempt:


Finally, we can run the following (which also runs the two commands above) to flash the file system to the board, after entering bootloader mode by pressing the button:


Now that’s done.

A Quick look at ESPurna Web Interface

ESPurna firmware and filesystem has now been flashed to Sonoff POW. But does it work?

Click to Enlarge
Click to Enlarge

I can see a new SONOFF_POW_XXXXX access point, so that does look good. I can connect using the default password “fibonacci”, then go to my web browser to access http://192.168.4.1, and login again with admin/fibonacci credentials.

Click to Enlarge
Click to Enlarge

ESPURNA 1.03 interface goes to the status menu first, and there I can turn on and off the relay remotely, and check the power consumption in watts, which remains at 0 watt since I have not connected it to the mains yet. It’s also possible to turn the relay on and off with the button, and there an option to select whether to turn on or off the relay at boot time, which is great since I need it on at all times.

The web interface also allows you to change general parameters including the hostname and password, as well as enable or disable the HTTP API (disabled by default). The WiFi section is used to connect to up to 3 wireless routers, the MQTT section lets you configure an MQTT (Mosquito) broker, and the power section is used to calibrate the power monitoring device.

If you just intend to check the current power consumption and turn on and off the switch with your phone, you don’t have to do anything else. But I’d like to find some ways to draw daily, weekly, monthly charts of my office power consumption using either MQTT or the HTTP API. I’ll have to study how to do that, and that will hopefully be the topic of my next post about Sonoff POW.

Sonoff POW can be purchased on ITEAD Studio for $10.50 plus shipping, but is currently out of stock with the company manufacturing a third batch soon.

Share this:
FacebookTwitterHacker NewsSlashdotRedditLinkedInPinterestFlipboardMeWeLineEmailShare

Support CNX Software! Donate via cryptocurrencies, become a Patron on Patreon, or purchase goods on Amazon or Aliexpress

ROCK 5 ITX RK3588 mini-ITX motherboard

43 Replies to “How to Build and Flash ESPurna Open Source Firmware to Sonoff POW Wireless Switch”

  1. Thank you for the great report. Though I would suggest to change $ADMIN_PASS and $upload_flags (defaults to “fibonacci”) in

    code/src/config/general.h
    code/platformio.custom.ini
    code/platformio.ini

    as first step just to minimize the risk to expose another device with default logon credentials to the ‘Internet of shitty things’ 😉

    So once you’ve successfully built the firmware it’s basically just connecting the various Sonoff devices to the host computer, enter flash mode and executing two commands to flash firmware and fs, right?

    Reply

    1. New devices should never be exposed to the internet until fully set up. Changes to the source code will result in them being overwritten next time you do a pull from master.

      Reply

  2. @tkaiser
    I’ve added something in the tutorial about changing the default password in the code.

    Yes, once you’ve done once Sonoff POW device, you can flash the others with:

    If you really have many and want to speed up the process by a few second, you could instead run:

    You’d still have to enter bootloader mode between each command. I wonder if there’s a way to combine both into a single command.

    Reply

  3. @cnxsoft
    Regarding the password I thought it would be used in more than one location (see comment above)? Anyway: this should change it directly after checking out Xose’s repo:

    The risk that an Espurna device gets compromised that way is rather low (since an attacker has to be pretty close to the device — almost physical access) but IMO it’s ‘good style’ to try to prevent any of these attacks and well known default logon credentials since nowadays connecting IoT devices to the net means that they are automagically attacked/infected seconds after (see the ‘funny’ TR-069 attacks from last weeks).

    BTW: In the meantime due to insanely low priced Orange Pi Zero my interest in Sonoff devices dropped a bit but I’ll order a few of them anyway to get a clue how energy efficient they are (they should be able to beat OPi Zero’s 450mW)

    Reply

  4. @tkaiser
    The password in the ini files is for the OTA firmware. If you’ve changed the password in the firmware or in the web interface, this won’t work with the default password. So I understand you need to include the password used in Sonoff POW (which may be different from the one you set) for the OTA update to work.

    Reply

  7. Hi
    I’m the developer. Thank you all for the great article and all your suggestions. Several things to note:

    1) Using the staging version shouldn’t be necessary. The only reason it was was that the default environment had support for the fauxmoESP library, which requires the latest version of the Arduino Core for ESP8266. I have removed that requirement from the default environment.
    2) I still cannot reproduce the issue you have with the HLW8018 header. It’s weird the same does not apply to other headers included from included files (like NtpClientLib, for instance). Even thou your fix did it for you I’d like to investigate a bit further first.
    3) Default password topic. My idea is to force the user reset the password upon her first visit to the web interface. Would that work?
    4) Binaries. I see there is a demand for that. Will create an official repository of binaries in the next few days along with the instructions to easily flash them.

    As you might have noticed, even thou the documentation has been updated lately there is still a lot to do. Any suggestions will be welcome.

    Reply

  8. @Xose Pérez
    Thank you for your great work on a better firmware for those devices. I think forcing a password change on first visit is ok even if it leaves the device potentially vulnerable in between (AP with known SSID and logon credentials). But that’s simply the user’s responsiblity to provide some level of physical access protection prior to password change and could be addressed with a simple sentence (in big red letters 😉 ) on download/project page.

    Looking forward to play with ESPurna in 2017 🙂

    Reply

  9. @Xose Pérez
    1) I had to install the staging version because the build would fail without it.
    2) OK. I’ve provided more details in the issue on bitbucket. I could reproduce this in three Ubuntu 16.04 machines.
    3) Looks good to me
    4) If you release binaries, maybe it would be good to enable -DENABLE_FUSS so that people can get automatic firmware updates with possibly an option in the web interface to enable it (e.g. make it disable by default). Or is there an issue with the upload password (since people would use their own password)?

    Reply

  11. Does ESPurna works without the www-internet-connection, I don´t understand where the “ESPurna Web Interface” is “hosted”?
    Is it correct: I don´t need a Hardware – Arduinoboard?
    And Yes, a personal Password would be better.

    Reply

  12. @rebeL
    The web interface is hosted in the device itself. It has a small webserver embedded. If by “www-internet-connection” you mean a “cloud”, yes, it works without internet connection. Just connect it to your local network to benefit from using it from your laptop or smartphone, MQTT, Alexa,…
    I don’t know what you mean by if you need a hardware. ESPurna was coded with the Itead Sonoffs in mind but it will work with most of the ESP8266-based smarts switches out there.

    Reply

  16. @cnxsoft
    The MQTT message format for Domoticz is specific. Right now your best option is to “rewrite” messages back and forth from Node-RED or any other way. That’s also the approach that they suggest in that wiki page. So for instance, you will need to subscribe to “domoticz/out”, capture the messages like “{“command”: “switchscene”, “idx”: 24, “switchcmd”: “On” }” and republish to “/whatever_your_sonoff_topic>/relay/0” as either 0 or 1.

    Reply

  17. I learned something today since the SSID needs to be input manually in the web interface: SSIDs are case-sensitive…
    I was wondering why it would always stay in SoftAP mode, and never switch to client mode. So now I know…

    Reply

  18. Will this work with Peter Scargill all-in-one script? It’s a raspberry pi script to install a MQTT server plus node-red? What are the directions to install this on a standard sonoff please?

    Reply

  19. @Chuxxsss
    It’s quite likely to work with Peter’s software via MQTT, but interoperability would need to be tested. To build install ESPurna on Sonoff, simply replace sonoff-pow-debug by sonoff-debug in the instructions. It should even be easier since there won’t be any HW8012.h header issue.

    Reply

  20. It was my first attempt and, although I used to be a programmer, I had never used this environment before.
    I did the whole procedure without a problem on a basic Sonoff.

    Now I’m going to try and integrate the switch with some control software via MQTT.

    Thank you!

    Gianluca

    Reply

  21. Just to let you know the code builds without errors on arch linux. Platformio installed from AUR. Only one package that should be installed and is not in the dependency lis is python-setuptools from the extra-repositories.

    A last thing I would ask. on the espurna bitbucket site Xose says it should be flashed with a 3,3v usb to ttl. My usb to ttl is the one a use for my dev boards (cubie, odroid). Can I use this one then before I start flashing or do I need another one?

    Reply

  23. I flashed it with succes. To be sure I took 3,3V from my OPI-one.
    One thing I had to find out was when you push the button when powering the board, you are imediately in the flashing mode. You don’t see blinking leds. If you see blinking leds, you are to late.
    So you should power the board while pushing the button, release it and start flashing. The leds will not go on.

    What I miss on the espurna firmware is setting switching schedules. Maybe You can do it throug the command line?

    Reply

  25. I think I will try ESP Easy, where you can set rules. Don’t know if they already support the power measurement though.

    Reply

  29. Hi,

    Does it work with ifttt ?
    I have seen that it is emulating Belkin WeMo switch, but I am curios if someone is able to link it to ifttt?

    Thank you!

    Reply

  31. @Athar
    I will most probably not have time to check out Arendst firmware. The next step will probably be to install Domoticz in NanoPi NEO, learn how to use it, and set it up to get the data from Sonoff POW with ESPurna firmware.

    Reply

  32. Hi,

    i build a binary from the code and flashed it to the Sonoff, that works.

    I connected the WIFI Network”sonoff_xxxxx) from PC and Phone.
    I got a got IP like 192.168.4.2

    but after enter the “authentication challenge” admin/fibonacci i see a blank Website.

    Any Idea`?

    Thanks

    Reply

  36. Great post! I had followed it before and it worked great but when I went through it after a clean OS install I ran into a snag. The links from /usr/local/bin were broken. I didn’t have a penv folder and couldn’t figure out why. In the end the solution was simple.

    I selected Install Shell Commands from the PlatformIO menu in Atom. That showed me that platformio and pio were in another location
    ~/.platformio/penv/bin/platformio
    ~/.platformio/penv/bin/pio

    Reply

  37. Hi,

    I’ve no experience with electronics but I really want my Sonoff to work with Alexa Echo, how I’ll update the firmware of my Sonoff as a novice ? can I use Arduino UNO or Raspberry PI by using Arduino IDE to update firmware?

    Please also suggest the best firmware and detail guide to update firmware.

    Thank you

    Reply

  38. Hie,

    can anyone tell me where to find and use gpio 14 on POW please? i am trying to hack a DHT22 into it to additionally get temp and humidity also. Using espurna firmware which should just pick it up from gpio14. (i tested that on sonoff basic)

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

Boardcon Rockchip and Allwinner SoM and SBC products
Boardcon Rockchip and Allwinner SoM and SBC products