Home - xoseperez/espurna GitHub Wiki

ESPurna Firmware

ESPurna ("spark" in Catalan) is a custom firmware for ESP8285/ESP8266 based smart switches, lights and sensors. It uses the Arduino Core for ESP8266 framework and a number of 3rd party libraries.

latest release latest snapshot build ci build ci build
development branch license downloads
gitter twitter github


Collaborators

Since November 2018, Max Prokhorov (@mcspr) is also actively working as a collaborator of the project.

Contributors

Without your help this project would not be possible. I (@xoseperez) simply can't spend all the time I wish on ESPurna but luckly I recieve a lot of contributions, bug fixes, enhancement suggestions,... from people all around the world. I would like to thank each and every one of you. The contributors page shows the ones that have done a PR in the past, but I also get contributions in the issues, by email or via the gitter ESPurna channel, those I also want to thank.

Thank you all very much.

Notice

Ladies and gentlemen in the embedded world, use PlatformIO. If I could offer you only one tip for the future, PlatformIO would be it.

Please use the gitter ESPurna channel for support and questions, you have better chances to get fast answers from me or other ESPurna users. Open an issue here only if you feel there is a bug or you want to request an enhancement. Thank you.

Features

  • KRACK vulnerability free (when built with Arduino Core >= 2.4.0)
  • Support for multiple ESP8266-based boards (check list)
  • Power saving options
  • Wifi AP Mode or STA mode
    • Supports static IP
    • Up to 5 different networks can be defined
    • Scans for strongest network if more than one defined (also available in web UI)
    • Handles correctly multiple AP with the same SSID
    • Defaults to AP mode (also available after double clicking the main button)
    • Support for WPS and Smart Config (not available in default builds)
  • Network visibility
    • Supports mDNS (service reporting and metadata) both server mode and client mode (.local name resolution)
    • Supports NetBIOS, LLMNR and Netbios (when built with Arduino Core >= 2.4.0) and SSDP (experimental)
  • Switch management
    • Support for push buttons and toggle switches
    • Configurable status on boot per switch (always ON, always OFF, same as before or toggle)
    • Support for pulse mode per switch (normally ON or normally OFF) with configurable time
    • Support for relay synchronization (all equal, only one ON, one and only on ON)
    • Support for MQTT groups to sync switches between devices
    • Support for delayed ON/OFF
    • Support for latched relays
  • MQTT enabled
    • SSL/TLS support (not on regular builds, see #64)
    • Switch on/off and toggle relays, group topics (sync relays between different devices)
    • Report button event notifications
    • Enable/disable pulse mode
    • Change LED notification mode
    • Remote reset the board
    • Fully configurable in WebUI (broker, user, password, QoS, keep alive time, retain flag, client ID)
  • Scheduler to automatically turn on, off or toggle any relay at a given time and day, also change light intensity for dimmers
  • Alexa integration using the FauxmoESP Library
  • Google Assistant integration using IFTTT and Webhooks (Google Home, Allo)
  • Domoticz integration via MQTT
  • Home Assistant integration
    • Support for switches (on/off)
    • Support for lights (color, brightness, on/off state)
    • Supports MQTT auto-discover feature (switches, lights and sensors)
    • Integration via MQTT Discover or copy-pasting configuration code
  • InfluxDB integration via HTTP API
  • Prometheus metrics integration via HTTP API
  • Thingspeak integration via HTTP API (HTTPS available for custom builds)
  • Sonoff RF Bridge support
  • Support for different sensors
    • Environment
      • DHT11 / DHT12 / DHT22 / DHT21 / AM2301 / Itead's SI7021
      • BMP180, BMP280 and BME280 pressure, humidity (BME280) and temperature (BMP280 & BME280) sensor by Bosch
      • BME680 pressure, humidity, temperature and gas sensor by Bosch with support for Bosch's proprietary library BSEC for accurate Indoor Air Quality (IAQ) monitoring
      • TMP35 and TMP36 analog temperature sensors
      • MAX6675 temperature sensor
      • NTC temperature sensors
      • SI7021 temperature and humidity sensor
      • SHT3X temperature and humidity sensor over I2C (Wemos shield)
      • AM2320 temperature and humidity sensor over I2C
      • Dallas OneWire sensors like the DS18B20
      • MHZ19 CO2 sensor
      • MICS2710 CO2 & NO2 sensor
      • MICS5525 CO & CO2 sensor
      • SenseAir S8 CO2 sensor
      • PMSX003/PMS5003T/ST dust sensors
      • SDS011 dust sensor
      • BH1750 luminosity sensor
      • GUVAS12SD UV sensor
      • VEML6075 UV Sensor
      • EZO pH Circuit
      • Geiger counter by RH Electronics
      • HC-SR04, SRF05, SRF06, DYP-ME007, JSN-SR04T & Parallax PING)))™ distance sensors
      • VL53L1X distance sensor
    • Power monitoring
      • HLW8012 using the HLW8012 Library (Sonoff POW)
      • CSE7766 and CSE7759B power monitor chips
      • HJL-01 and BL0937 power monitor chips
      • Non-invasive current sensor using internal ADC or ADC712 or ADC121 or ADS1115
      • V9261F power monitor chip
      • PZEM0004T power monitor board
    • Raw analog and digital sensors
    • Simple pulse counter with event triggering option
    • Support for (almost) any UART based sensor via the UART-to-MQTT module
    • Support for different units (Fahrenheit or Celsius, Watts or Kilowatts, Joules or kWh)
  • Support for LED lights
    • MY92XX-based light bulbs and PWM LED strips (dimmers) up to 5 channels (RGB, cold white and warm white, for instance)
    • Support for CCT lights
    • RGB and HSV color codes supported
    • Manage channels individually
    • Temperature color supported (in mired and kelvin) via MQTT / REST API
    • Flicker-free PWM management
    • Soft color transitions
    • Color synchronization between light using MQTT
    • Option to have separate switches for each channel
  • Support for simple 433MHz RF receivers
  • Support for UART-to-MQTT bidirectional bridge
  • Fast asynchronous HTTP Server and cool Web User Interface
    • Configurable port
    • Basic authentication
    • Web-based configuration
    • Relay switching and sensor data from the web interface
    • Handle color, brightness, and white/warm channels for lights
    • Websockets-based communication between the device and the browser
    • Backup and restore settings option
    • Upgrade firmware from the web interface
    • Works great behind a secured reverse proxy
  • REST API (enable/disable from web interface)
    • GET and PUT relay status (including pulses)
    • Change light color (for supported hardware)
    • GET sensor data (power, current, voltage, temperature and humidity) depending on the available hardware
    • Works great behind a secured reverse proxy
  • RPC API (enable/disable from web interface)
    • Remote reset the board
  • RPN Rules on-device automation
    • Relays on/off/toggle
    • Lights control
    • Publish / subscribe to MQTT
    • RF receiver integration
  • Over-The-Air (OTA) updates even for 1Mb boards
    • Manually from PlatformIO or Arduino IDE
    • Automatic updates through the NoFUSS Library
    • Update from web interface using pre-built images
  • Command line configuration
    • Change configuration
    • Run special commands
  • Telnet support
    • Enable/disable via the web UI
    • Shows debug info and allows to run terminal commands
  • NTP for time synchronization
    • Supports worldwide time zones
    • Compatible with DST (based on POSIX TZ variable support)
  • Unstable system check
    • Detects unstable system (crashes on boot continuously) and defaults to a stable system
    • Only WiFi AP, OTA and Telnet available if system is flagged as unstable
  • Configurable LED notifications based on WiFi status, relays status or MQTT messages.
  • Button interface
    • Click to toggle relays
    • Double click to enter AP mode (only main button)
    • Long click (>1 second) to reboot device (only main button)
    • Extra long click (>10 seconds) to go back to factory settings (only main button)
    • Specific definitions for touch button devices (ESPurna Switch, Sonoff Touch & T1)
  • Configuration stored in different sectors to prevent data loosing and corruption

Notices


2018-04-08
Please use gitter for support and questions, you have better chances to get fast answers by me or other ESPurna users. Open an issue here only if you feel there is a bug or you want to request an enhancement. Thank you.


2018-03-09
Default branch in GitHub is now the development branch "dev".
The stable branch (the one used to create the binary releases) is "master".


2018-01-24
This repository has been migrated from Bitbucket to GitHub. There were a number of reason to migrate the repository to GitHub. I like Bitbucket and I'm still using it for a lot of projects, but ESPurna has grown and its community as well. Some users have complain about Bitbucket not being enough community-focused. This change is mainly aimed to use a platform with greater acceptance on the open-source community and tools better suited to them (to you), like the possibility to contribute to the documentation in an easy way.

What happened with all the info in Bitbucket? Well, most of it has been ported to GitHub, albeit with some quirks:

  • Code has, of course been migrated completely
  • Issues are all on GitHub already but all issues and comments show up as reported by me. The original reporter is referenced inside the body of the issue (or comment) with a link to his/her profile at Bitbucket and a link to his/her profile at GitHub if it happens to be the same username. I suggest all reporters to subscribe to the issues they originally filed (search for your BitBucket username to list them).
  • Pull requests historic has not been migrated. At the moment of the migration all pull-requests have been either merged or declined. Of course, those PR merged are in the code base, but the historic and comments in the PR pages will be lost.
  • Documentation it's on it way, first step will be to migrate existing wiki, maybe with a new TOC structure
  • Watchers, Forks, I'm afraid they are all gone. Visit the new repo home and click on the "Watch" button on the top right. And as you do it click also on the "Star" button too :)

I apologize for any inconvenience this migration may have caused. I have decided to do it the hard way.


2018-01-11
As of current version (1.12.0) ESPurna is tested using Arduino Core 2.3.0 and it's meant to be built against that version.


2017-08-26
Since version 1.9.0 the default MQTT topics for commands have changed. They all now end with "/set". This means you will have to change your controller software (Node-RED or alike) to send messages to -for instance- "/home/living/light/relay/0/set". The device will publish its state in "/home/living/light/relay/0" like before.


2017-07-24
Default flash layout changed in 1.8.3, as an unpredicted consequence devices will not be able to persist/retrieve configuration if flashed with 1.8.3 via OTA from PlatformIO. Please check issue #187.


Contribute

There are several ways to contribute to ESPurna development. You can contribute to the repository by doing:

  • Pull requests (fixes, enhancements, new features... are very welcome)
  • Documentation (I reckon I'm bad at it)
  • Testing (filing issues or help resolving them, they take a lot of time and sometimes I don't have the required hardware to test them all)

And of course you can always buy me a beer, coffee, tea,... via the donation button below.

Donate

Documentation

For more information please refer to the ESPurna Wiki.

Supported hardware

Here is the list of supported hardware. For more information please refer to the ESPurna Wiki Hardware page.

Power monitoring devices

BlitzWolf BW-SHP6 BlitzWolf BW-SHP2 Power meters based on V9261F
Blitzwolf BW-SHP6 Blitzwolf BW-SHP2
(also by Coosa, Goosund, HomeCube, Teckin)
Power meters based on V9261F
Itead Sonoff POW Itead Sonoff POW Itead Sonoff S31
Itead Sonoff POW Itead Sonoff POW R2 Itead Sonoff S31
Smartlife Mini Smart Socket Teckin SP20 Digoo NX SP202
Smartlife (NETVIP) Mini Smart Socket Teckin SP20 Digoo NX SP202
Vanzavanzu Smart WiFi Plug Mini
Vanzavanzu Smart WiFi Plug Mini

Embedded switches

Itead Sonoff Basic Itead Sonoff Dual/Dual R2 Itead Sonoff TH10/TH16
Itead Sonoff Basic Itead Sonoff Dual/Dual R2 Itead Sonoff TH10/TH16
Electrodragon WiFi IOT OpenEnergyMonitor WiFi MQTT Relay / Thermostat
Electrodragon WiFi IOT OpenEnergyMonitor WiFi MQTT Relay / Thermostat
Itead Sonoff 4CH Itead Sonoff 4CH Pro
Itead Sonoff 4CH Itead Sonoff 4CH Pro
Allterco Shelly1 Allterco Shelly2 Jan Goedeke Wifi Relay (NO/NC)
Alterco Shelly1 Alterco Shelly2 Jan Goedeke Wifi Relay (NO/NC)
EXS Wifi Relay v3.1 EXS Wifi Relay v5.0 Jorge García Wifi + Relays Board Kit
EXS Wifi Relay v3.1 EXS Wifi Relay v5.0 Jorge García Wifi + Relays Board Kit
Allnet ESP8266-UP-Relay Bruno Horta's OnOfre Luani HVIO
Allnet ESP8266-UP-Relay Bruno Horta's OnOfre Luani HVIO

Wall Sockets

Itead S20 Itead S26 Neo Coolcam NAS WR01W
Itead S20 Itead S26 Neo Coolcam NAS WR01W
Maxcio W-US002S HEYGO HY02 YiDian XS-SSA05
Maxcio W-US002S HEYGO HY02 YiDian XS-SSA05
WiOn 50055 LINGAN SWA1 HomeCube 16A
WiOn 50055 LINGAN SWA1 HomeCube 16A
WorkChoice EcoPlug Bestek MRJ1011 Tonbux XS-SSA01
WorkChoice EcoPlug Bestek MRJ1011 Tonbux XS-SSA01
Schuko Wifi Plug Schuko Wifi Plug V2 KMC 70011
Schuko Wifi Plug Schuko Wifi Plug V2 KMC 70011
Xenon SM-PW702U Orvibo B25 Oukitel P1
Xenon SM-PW702U Orvibo B25 Oukitel P1
Tonbux XS-SSA06 Litesun LA-WF3 Maxcio W DE-004
Tonbux XS-SSA06 Litesun LA-WF3 Maxcio W DE-004
Hama WiFi Steckdose GBLife RGBW Socket Gosund WP3
Hama WiFi Steckdose GBLife RGBW Socket Gosund WP3

Wall switches

Itead Sonoff Touch Itead Sonoff T1 YJZK switch
Itead Sonoff Touch Itead Sonoff T1 YJZK 1/2/3-gangs switch
Gosund WS1 / KS-602S
Gosund WS1 / KS-602S

Power strips

Tonbux PowerStrip02 ForNorm ZLD-34EU Zhilde ZLD-EU55-W
Tonbux PowerStrip02 Fornorm Power Strip Zhilde ZLD-EU55-W

Smart lights

Itead Slampher Arilux E27 Itead Sonoff B1
Itead Slampher Arilux E27 Itead Sonoff B1
AI-Thinker Wifi Light / Noduino OpenLight Authometion LYT8266 AG-L4
AI-Thinker Wifi Light / Noduino OpenLight Authometion LYT8266 AG-L4
Lohas 9W Xiaomi Smart Desk Lamp iWoole LED Table Lamp
Lohas 9W Xiaomi Smart Desk Lamp iWoole LED Table Lamp
Itead Sonoff LED Itead BN-SZ01 Lombox LUX Nova 2
Itead Sonoff LED Itead BN-SZ01 Lombex LUX Nova 2 (white and color)
Arilux AL-LC01 (RGB) Arilux AL-LC02 (RGBW) Arilux AL-LC06 (RGBWWCW)
Arilux AL-LC01 (RGB) Arilux AL-LC02 (RGBW) Arilux AL-LC06 (RGBWWCW)
Arilux AL-LC11 (RGBWWW) & RF MagicHome LED Controller (1.0 and 2.x) Huacanxing H801/802
Arilux AL-LC11 (RGBWWW) & RF MagicHome LED Controller (1.0/2.x, also ZJ WFMN A/B11) Huacanxing H801/802

Radio links / gateways

Tinkerman RFM69GW Itead Sonoff RF Bridge Itead Sonoff RF
Tinkerman RFM69GW Itead Sonoff RF Bridge Itead Sonoff RF

Other devices

Tonbux Mosquito Killer Itead Sonoff IFAN02
Tonbux Mosquito Killer Itead Sonoff IFAN02

Custom & Development boards

Tinkerman Espurna H NodeMCU
Tinkerman ESPurna H NodeMCU Lolin V3
Itead Sonoff SV Itead 1CH Inching Itead Motor Clockwise/Anticlockwise
Itead Sonoff SV Itead 1CH Inching Itead Motor Clockwise/Anticlockwise
ManCaveMade ESP-Live Wemos D1 Mini Relay Shield Gizwits Witty Cloud
ManCaveMade ESP-Live Wemos D1 Mini Relay Shield Gizwits Witty Cloud
IKE ESPike Pilotak ESP DIN Arniex Swifitch
IKE ESPike **Pilotak ESP DIN Arniex Swifitch
Heltec Touch Relay Generic Relay v4.0 Generic RGBLed v1.0
Heltec Touch Relay Generic Relay v4.0 Generic RGBLed v1.0
Generic DHT11 v1.0 Generic DS18B20 v1.0 InterMitTech QuinLED 2.6
Generic DHT11 v1.0 Generic DS18B20 v1.0 InterMitTech QuinLED 2.6
Phyx ESP12 RGBW RH Electronics Geiger Counter Green ESP Relay
Phyx ESP12 RGBW RH Electronics Geiger Counter Green ESP Relay
Foxel Lightfox Dual
Foxel Lightfox Dual

License

Copyright (C) 2016-2019 by Xose Pérez (@xoseperez)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

⚠️ **GitHub.com Fallback** ⚠️