Refactored documentation, still a work in progress

README.md

@@ -1,163 +1,54 @@
 # ESPurna
 
-ESPurna ("spark" in Catalan) is a custom C firmware for ESP8266 based smart switches. It was originally developed with the **[ITead Sonoff][1]** in mind. This device has an ESP8266 on board with a 8Mbit flash memory chip, a mains to 3V3 transformer and a relay (GPIO12). It also features a button (GPIO0), an LED (GPIO13) and an unpopulated header you can use to reprogram it.
-You can read about this board and firmware in [my blog][2].
-
-![Sonoff board - front view](/images/pinout_front.jpg)
-
-![Sonoff board - back view](/images/pinout_back.jpg)
-
-## Hardware support
-
-* [ITead Sonoff TH][1]
-* [ITead Sonoff RF][8]
-* [ITead Slampher][9]
-* [ITead S20 Smart Socket][10]
-* [ITead Sonoff POW][15]
-* Tinkerman ESPurna board
+ESPurna ("spark" in Catalan) is a custom C firmware for ESP8266 based smart switches. It was originally developed with the **[ITead Sonoff][1]** in mind.
 
 ## Features
 
-* **WebServer for configuration** and simple relay toggle with basic authentication
-* Communication between webserver and webclient via websockets with CSRF check
+* **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
-* Support for **automatic over-the-air updates** through the [NoFUSS Library][6]
+* **Alexa** integration (Amazon Echo or Dot) by emulating a Belkin WeMo switch
+* Support for **automatic over-the-air updates** through the [NoFUSS Library][2]
 * Support for **DHT22** sensors
-* Support for the **HLW8012** power sensors present in the Sonoff POW
-* Support for **current monitoring** through then [EmonLiteESP Library][7] using a non-intrusive current sensor (requires some hacking)
+* Support for the **HLW8012** power sensor present in the Sonoff POW
+* Support for **current monitoring** through the [EmonLiteESP Library][3] using a non-intrusive current sensor ([requires some hacking][4])
 * Command line configuration
 
-## Installing
-
-### Build the web config site
-
-Normally when you flash an ESP8266 you only flash the firmware, like for any other microcontroller. But the ESP8266 has plenty of room and normally it is split into different partitions. One such partition is used to store web files like a normal webserver. In the "Flash your board" section below you'll know how to flash this special partition, but first we will have to build it.
-
-The build process read the HTML files, looks for the stylesheet and script files linked there, grabs them, merges them, minifies them and compresses them. Thus, a single HTML with N linked scripts and M linked CSS files is transformed in just 1 file (index.html.gz). This way the ESP8266 webserver can serve them really fast. Mind the ESP8266 is just a microcontroller, the webserver has a very limited capacity to hold concurrent requests, so few and lighter files are a must.
-
-To build these files we are using **[Gulp][11]**, a build system built in [node.js][13]. So you will need node (and [npm][14], its package manager) first. [Read the documentation][12] on how to install them.
-
-Once you have node and npm installed, go to the 'code' folder and install all the dependencies with:
-
-```
-npm install
-```
-
-It will take a minute or two. Then you are ready to build the webserver files with:
-
-```
-gulp
-```
-
-It will create a populate a 'data' folder with all the required files.
-
-### Build the firmware
-
-The project is ready to be build using [PlatformIO][3].
-Please refer to their web page for instructions on how to install the builder.
-
-PlatformIO will take care of some of the library dependencies, but not all the required libraries are available in the platform library manager. Some dependencies are thus checked out as submodules in GIT. So the normal initial checkout should be:
-
-```
-git clone git@bitbucket.org:xoseperez/espurna.git
-git submodule init
-git submodule update
-```
-
-On linux/max systems the libraries are soft linked to the code/lib folder and you are ready to go. Windows systems do not have this feature so you will have to copy them manually like this (ONLY WINDOWS):
-
-```
-cd espurna/code
-copy vendor/emonliteesp/code/lib/EmonLiteESP lib/EmonLiteESP
-copy vendor/nofuss/client/lib/NoFUSSClient lib/NoFUSSClient
-copy vendor/RemoteSwitch-arduino-library lib/RemoteSwitch
-```
-
-The Embedis library is the only one required in all cases. The other three are optional at the moment and will only be linked if you set ENABLE_NOFUSS, ENABLE_EMON or ENABLE_RF in the defaults.h file.
-
-Once you have all the code, you can check if it's working by:
-
-```bash
-> platformio run -e node-debug
-```
-
-If it compiles you are ready to flash the firmware.
-
-### Flash your board
-
-*This section only applies to the Sonoff Basic, but pretty much every other ESP8266-based hardware will be similar.*
-
-The unpopulated header in the Sonoff has all the required pins. My board has a 5 pins header in-line with the button. They are (from the button outwards):
-
-* 3V3
-* RX
-* TX
-* GND
-* GPIO14
-
-Last one is not necessary. Mind it's a **3V3 device**, if connected to 5V you will probably fry it. Button is connected to GPIO0 on the ESP8266 chip, so to enter flash mode you have to hold the button pressed while powering on the board, then you can realease it again.
-
-Wire your board and flash the firmware (with ```upload```) and the file system (with ```uploadfs```):
-
-```bash
-> platformio run --target upload -e node-debug
-> platformio run --target uploadfs -e node-debug
-```
-
-You might notice than when you call "uploadfs" target it automatically builds the files (does a "gulp buildfs"). This is done by the hook defined in the extra_script parameter of each environment.
-
-Once you have flashed it you can flash it again over-the-air using the ```ota``` environment:
-
-```bash
-> platformio run --target upload -e node-debug-ota
-> platformio run --target uploadfs -e node-debug-ota
-```
-
-When using OTA environment it defaults to the IP address of the device in SoftAP mode. If you want to flash it when connected to your home network best way is to supply the IP of the device:
-
-```bash
-> platformio run --target upload -e node-debug-ota --upload-port 192.168.1.151
-> platformio run --target uploadfs -e node-debug-ota --upload-port 192.168.1.151
-```
-
-You can also use the automatic OTA update feature. Check the [NoFUSS library][6] for more info.
-
-Library dependencies are automatically managed via PlatformIO Library Manager or included via submodules and linked from the "lib" folder.
-
-## Usage
+## Index
 
-On normal boot (i.e. button not pressed) it will execute the firmware. It configures the hardware (button, LED, relay), the SPIFFS memory access, the WIFI, the WebServer and MQTT connection.
+* [Supported hardware](docs/Hardware.md)
+* [Build and flash the firmware](docs/Firmware.md)
+* [Build and flash the filesystem](docs/Filesystem.md)
+* [Configuration](docs/Configuration.md)
+* [Over-the-air updates](docs/OTA.md)
+* [Sensors](docs/Sensors.md)
+* [Troubleshooting](docs/Troubleshooting.md)
 
-Obviously the default values for WIFI network and MQTT will probably not match your requirements. The device will start in Soft AP creating a WIFI SSID named "SONOFF_XXXXXX", where XXXXXX are the last 3 bytes of the radio MAC. Connect with phone, PC, laptop, whatever to that network, password is "fibonacci". Once connected
-browse to 192.168.4.1. It will then present an authentication challenge. Default user and password are "admin" and "fibonacci" (again). Then you will be presented a configuration page where you will be able to define different configuration parameters, including changing the default password. The same password is used for the WIFI Access Point, for the web interface and for the OTA firmware upload.
+## License
 
-You can configure up to three WIFI networks. It will then try to connect to the configure WIFI networks in order of signal strength. If none of the 3 attempts succeed it will default to SoftAP mode again. Once connected it will try to connect the MQTT server. You can also switch to SoftAP mode by double click the on board button or reset the board long clicking it.
+Copyright (C) 2016 by Xose Pérez (@xoseperez)
 
-The device will publish the relay state to the given topic and it will subscribe to the same topic for remote switching. Don't worry, it avoids infinite loops.
+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.
 
-You can also use "{identifier}" as place holder in the topic. It will be translated to your device ID (same as the soft AP network it creates).
+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.
 
-## Troubleshooting
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-After flashing the firmware via serial do a hard reset of the device (unplug & plug). There is an issue with the ESP.reset() method. Check [https://github.com/esp8266/Arduino/issues/1017][4] for more info.
 
 [1]: https://www.itead.cc/sonoff-wifi-wireless-switch.html
-[2]: http://tinkerman.cat/adding-rf-to-a-non-rf-itead-sonoff
-[3]: http://www.platformio.org
-[4]: https://github.com/esp8266/Arduino/issues/1017
-[5]: https://github.com/esp8266/Arduino/pull/2251
-[6]: https://bitbucket.org/xoseperez/nofuss
-[7]: https://bitbucket.org/xoseperez
-[8]: https://www.itead.cc/sonoff-rf.html
-[9]: https://www.itead.cc/slampher-wifi-wireless-light-holder.html
-[10]: https://www.itead.cc/smart-socket-eu.html
-[11]: http://gulpjs.com/
-[12]: https://docs.npmjs.com/getting-started/installing-node
-[13]: https://nodejs.org/en/
-[14]: https://www.npmjs.com/
-[15]: https://www.itead.cc/sonoff-pow.html
+[2]: https://bitbucket.org/xoseperez/nofuss
+[3]: https://bitbucket.org/xoseperez/emonliteesp
+[4]: http://tinkerman.cat/your-laundry-is-done/

docs/Configuration.md

@@ -0,0 +1,21 @@
+# Configuration
+
+*TODO*
+
+## First boot
+
+On normal boot (i.e. button not pressed) it will execute the firmware. It configures the hardware (button, LED, relay), the SPIFFS memory access, the WIFI, the WebServer and MQTT connection and whatever other enabled modules.
+
+Obviously the default values for WIFI network and MQTT will probably not match your requirements. The device will start in Soft AP creating a WIFI SSID named "DEVICE_XXXXXX", where DEVICE will be an identifier of your device and XXXXXX are the last 3 bytes of the radio MAC. Connect with phone, PC, laptop, whatever to that network, password is "fibonacci". Once connected browse to 192.168.4.1. It will then present an **authentication challenge**. Default user and password are "admin" and "fibonacci" (again). Then you will be presented a configuration page where you will be able to define different configuration parameters, including changing the default password. The same password is used for the WIFI Access Point, for the web interface and for the OTA firmware upload.
+
+## WiFi configuration
+
+You can configure up to three WIFI networks. It will then try to connect to the configure WIFI networks in order of signal strength. If none of the 3 attempts succeed it will default to SoftAP mode again. You can also switch to SoftAP mode by double click the on-board button or reset the board long clicking it.
+
+## MQTT
+
+Once connected to an access point (so in station mode) the board will try to connect the MQTT server defined.
+
+The device will publish the relay state to the given topic and it will subscribe to the same topic for remote switching. Don't worry, it avoids infinite loops.
+
+You can also use "{identifier}" as place holder in the topic. It will be translated to your device ID (same as the soft AP network it creates).

docs/Filesystem.md

@@ -0,0 +1,77 @@
+# Filesystem
+
+## Introduction
+
+Normally when you flash an ESP8266 you only flash the firmware, like for any other microcontroller. But the ESP8266 has plenty of room and normally it is split into different partitions. One such partition is used to store web files like a normal webserver.
+
+Problem is that, even thou the ESP8266 is a very capable microcontroller it has its limitations and does not handle very well concurrent connections. This is specially true for the *default* webserver that comes with the Arduino Core for ESP8266.
+
+On the other side, to provide a good user experience and work with a comfortable development environment you end up having different files: scripts, stylesheet files, images,... The browser will load the index.html file and quickly request for all those other files and the ESP8266 will easily struggle trying to serve them all.
+
+So the trick here is to squeeze them all into one single compressed file just before uploading it. Luckily, we can do that automatically.
+
+## Web interface build process
+
+The build process reads the HTML files, looks for the stylesheet and script files linked there, grabs them, minifies them and includes them inline, in the same order they are loaded. The resulting single HTML file is then cleaned, further minified and compressed resulting in a single index.html.gz file. This way the ESP8266 webserver can serve it really fast.
+
+To build this file we are using **[Gulp][1]**, a build system built in [node.js][2]. So you will need node (and [npm][3], its package manager) first. [Read the documentation][4] on how to install them.
+
+Once you have node and npm installed, go to the 'code' folder and install all the dependencies with:
+
+```
+npm install
+```
+
+It will take a minute or two. Then you are ready to build the webserver files with:
+
+```
+gulp
+```
+
+It will create a populate a 'data' folder with all the required files.
+
+## Images
+
+Along with the HTML, CSS and JS files compressed into the index.html.gz file, the ESPurna firmware uses some images in its web interface. These are the favicon.ico file and a **sprite** for the iPhone style buttons in the interface. Again the idea is to use the minimum possible number of files.
+
+## Flashing it
+
+### Using PlatformIO
+
+[PlatformIO][5] allows the developer to define hooks to be executed before or after certain actions. This is really cool since we can plug one such hook to the *uploadfs* target to automatically build the web interface before uploading it to the board.
+
+This is done by specifying the script with the hook definitions in the *extra_script* option in the platformio.ini file. The script, written in python, binds the target file (spiffs.bin) to a method that executes the gulp command we have seen before.
+
+```
+#!/bin/python
+
+from SCons.Script import DefaultEnvironment
+env = DefaultEnvironment()
+
+def before_build_spiffs(source, target, env):
+    env.Execute("gulp buildfs")
+
+env.AddPreAction(".pioenvs/%s/spiffs.bin" % env['PIOENV'], before_build_spiffs)
+```
+
+The included platformio.ini file has all this already configured, so you don't have to worry about it. Just type:
+
+```
+pio run -t uploadfs -e sonoff
+```
+
+(or whatever other enviroment) and you are good to go.
+
+### Using Arduino IDE
+
+First you will have to manually build the data folder contents using gulp (see [instructions above](#web-interface-build-process)).
+
+Then you will have to have the "[ESP8266 Sketch Data Upload][6]" utility installed. Check the instructions in the previous link. The data folder should be a subfolder of the code folder for the tool to find it. Then just execute it and it will upload the data folder contents to your board.
+
+
+[1]: http://gulpjs.com/
+[2]: https://nodejs.org/en/
+[3]: https://www.npmjs.com/
+[4]: https://docs.npmjs.com/getting-started/installing-node
+[5]: http://www.platformio.org
+[6]: https://github.com/esp8266/Arduino/blob/master/doc/filesystem.md#uploading-files-to-file-system

docs/Firmware.md

@@ -0,0 +1,49 @@
+# Firmware
+
+## Build the firmware
+
+The project is ready to be build using [PlatformIO][1].
+Please refer to their web page for instructions on how to install the builder.
+
+PlatformIO will take care of some of the library dependencies, but not all the required libraries are available in the platform library manager. Some dependencies are thus checked out as submodules in GIT. So the normal initial checkout should be:
+
+```
+git clone https://bitbucket.org/xoseperez/espurna.git
+git submodule init
+git submodule update
+```
+
+On linux/max systems the libraries are soft linked to the code/lib folder and you are ready to go. Windows systems do not have this feature so you will have to copy them manually like this (ONLY WINDOWS):
+
+```
+cd espurna/code
+copy vendor/emonliteesp/code/lib/EmonLiteESP lib/EmonLiteESP
+copy vendor/nofuss/client/lib/NoFUSSClient lib/NoFUSSClient
+copy vendor/RemoteSwitch-arduino-library lib/RemoteSwitch
+```
+
+This libraries are optional at the moment and will only be linked if you set ENABLE_NOFUSS, ENABLE_EMON or ENABLE_RF from your build flag.
+
+Once you have all the code, you can check if it's working by:
+
+```bash
+> pio run -e node-debug
+```
+
+If it compiles you are ready to flash the firmware.
+
+## Flash your board
+
+Wire your board (check the [Hardware page](Hardware.md)) and flash the firmware (with ```upload```):
+
+```bash
+> pio run -t upload -e sonoff
+```
+
+(or any other environment, depending on the board you are woring with).
+
+Library dependencies are automatically managed via PlatformIO Library Manager or included via submodules and linked from the "lib" folder.
+
+Once the firmware is uploaded next step is to upload the web interface. Check how to [build and flash the filesystem](Filesystem.md).
+
+[1]: http://www.platformio.org

docs/Hardware.md

@@ -0,0 +1,123 @@
+# Supported Hardware
+
+This is the official list of supported hardware for the ESPurna firmware. The hardware configuration for each of these boards can be selected by supplying the build flag (see [Firmware section](Firmware.h)).
+
+**CAUTION: Never ever connect any of these devices to your computer and to mains at the same time. Never ever manipulate them while connected to mains. Seriously. I don't want you to die. I hold no responsibility for any damage to you, your family, your house,... for any action or results derived from flashing or using these devices.**
+
+* [IteadStudio Sonoff](#iteadstudio-sonoff)
+* [IteadStudio Sonoff RF](#iteadstudio-sonoff-rf)
+* [IteadStudio Sonoff TH](#iteadstudio-sonoff-th)
+* [IteadStudio Sonoff POW](#iteadstudio-sonoff-pow)
+* [IteadStudio Slampher](#iteadstudio-slampher)
+* [IteadStudio S20](#iteadstudio-s20)
+
+## IteadStudio Sonoff
+
+|Property|Value|
+|---|---|
+|Manufacturer|Itead Studio|
+|Web page|https://www.itead.cc/sonoff-wifi-wireless-switch.html|
+|Build flag|SONOFF|
+
+The [IteadStudio Sonoff][1] has an ESP8266 on board with a 8Mbit flash memory chip, a mains to 3V3 transformer and a relay (GPIO12). It also features a button (GPIO0), an LED (GPIO13) and an unpopulated header you can use to reprogram it.
+
+### Flashing
+
+![Sonoff - Inside front view](images/sonoff-flash.jpg)
+
+The unpopulated header in the Sonoff has all the required pins. My board has a 5 pins header in-line with the button. They are (from the button outwards) 3V3, RX, TX, GND and GPIO14.
+
+Last one is not necessary. Mind it's a **3V3 device**, if connected to 5V you will probably fry it. Button is connected to GPIO0 on the ESP8266 chip, so to enter flash mode you have to hold the button pressed while powering on the board, then you can release it again.
+
+## IteadStudio Sonoff RF
+
+|Property|Value|
+|---|---|
+|Manufacturer|Itead Studio|
+|Web page|[https://www.itead.cc/sonoff-rf.html][2]|
+|Build flag|SONOFF_RF|
+
+### Flashing
+
+![Sonoff POW - Inside back view](images/sonoff-rf-flash.jpg)
+
+The Sonoff RF has the same unpopulated header as the Sonoff. It is a 5 pins header in-line with the button. They are (from the button outwards) 3V3, RX, TX, GND and GPIO14.
+
+Solder a male or female header here and connect your USB-to-UART programmer (remember **it's a 3V3 device**). This time through **the button is not connected to GPIO0** but to a EFM8BB1 microcontroller that also monitors the RF module output.
+
+There are a couple of ways to enter flash mode. Some recommend to move 0Ohm R9 resistor to R21 to connect the button directly to the ESP8266 GPIO0 and use it in the same way as for the Sonoff or Sonoff TH. The drawback is the by doing that you lose the RF capability.
+
+My recommendation is to **temporary shortcut the bottom pad of the unpopulated R21 footprint** (see the image above) and connect your USB-to-UART board at the same time. You will have to do it just once (unless there is something really wrong in the firmware) and use OTA updates from there on.
+
+
+## IteadStudio Sonoff TH
+
+|Property|Value|
+|---|---|
+|Manufacturer|Itead Studio|
+|Web page|https://www.itead.cc/sonoff-th.html|
+|Build flag|SONOFF_TH|
+
+### Flashing
+
+![Sonoff TH - Inside back view](images/sonoff-th-flash.jpg)
+
+You have all the required pins in an unpopulated header in one of the corners of the board (see top left corner in the image above). Solder a 4 pins male or female header here and connect it to your favourite USB-to-UART module. Remember: **it's a 3V3 device**!!.
+
+As in the Sonoff the button is connected to GPIO0, so to enter flash mode press and hold the button and connect the programmer to your computer to power the board.
+
+## IteadStudio Sonoff POW
+
+|Property|Value|
+|---|---|
+|Manufacturer|Itead Studio|
+|Web page|https://www.itead.cc/sonoff-pow.html|
+|Build flag|SONOFF_POW|
+
+### Flashing
+
+![Sonoff POW - Inside back view](images/sonoff-pow-flash.jpg)
+
+Same as for the [Sonoff TH](#iteadstudio-sonoff-th) above.
+
+## IteadStudio Slampher
+
+|Property|Value|
+|---|---|
+|Manufacturer|Itead Studio|
+|Web page|https://www.itead.cc/slampher.html|
+|Build flag|SLAMPHER|
+
+### Flashing
+
+![Slampher - Inside front view](images/slampher-flash1.jpg)
+![Slampher - Flashing short](images/slampher-flash2.jpg)
+
+There is a 4 pin unpopulated header in a border near the ESP8266 chip. Starting form the little white mark this header brings out 3V3, RX, TX and GND. Solder a male or female header here and connect your USB-to-UART programmer (remember it's a 3V3 device). This time through **the button is not connected to GPIO0** but to a EFM8BB1 microcontroller that also monitors the RF module output.
+
+There are a couple of ways to enter flash mode. Some recommend to move R21 to R20 (at the top right of the first picture above) to connect the button directly to the ESP8266 GPIO0 and use it in the same way as for the Sonoff or Sonoff TH. The drawback is the by doing that you lose the RF capability.
+
+My recommendation is to **temporary shortcut the right pad of the unpopulated R20 footprint** (see second image above) and connect your USB-to-UART board at the same time. You will have to do it just once (unless there is something really wrong in the firmware) and use OTA updates from there on.
+
+## IteadStudio S20 Smart Socket
+
+|Property|Value|
+|---|---|
+|Manufacturer|Itead Studio|
+|Web page|https://www.itead.cc/smart-socket.html|
+|Build flag|S20|
+
+### Flashing
+
+![S20 Smart Socket - Inside front view](images/s20-flash.jpg)
+
+There is a labeled header in the front of the PCB and the button is connected to GPIO0, so no problems here.
+
+Solder a 4 pin male or female header and connect it to your USB-to-UART bridge. Again, remember **it's a 3V3 device**. Then press and hold the button and connect the programmer to your computer. The microcontroller will boot into flash mode and you are ready to update the firmware.
+
+[1]: https://www.itead.cc/sonoff-wifi-wireless-switch.html
+[2]: https://www.itead.cc/sonoff-rf.html
+[2]: https://www.itead.cc/sonoff-th.html
+[4]: https://www.itead.cc/sonoff-pow.html
+[5]: https://www.itead.cc/slampher.html
+[6]: https://www.itead.cc/smart-socket.html

docs/OTA.md

@@ -0,0 +1,28 @@
+# Over-the-air updates
+
+## Manually driven OTA updates
+
+Once you have flashed your board with the ESPurna firmware you can flash it again over-the-air using PlatformIO and the ```ota``` environment:
+
+```bash
+> pio run -t upload -e node-debug-ota
+> pio run -t uploadfs -e node-debug-ota
+```
+
+When using OTA environment it defaults to the IP address of the device in SoftAP mode. If you want to flash it when connected to your home network best way is to supply the IP of the device:
+
+```bash
+> pio run -t upload -e node-debug-ota --upload-port 192.168.1.151
+> pio run -t uploadfs -e node-debug-ota --upload-port 192.168.1.151
+```
+
+Please note that if you have changed the admin password from the web interface you will have to change it too in the platformio.ini file for the OTA to work. Check for the *upload_flags* option in your ota-enabled environment.
+
+## Automatic OTA updates
+
+You can also use the automatic OTA update feature. Check the [NoFUSS library][6] for more info.
+
+This options is disabled by default. Enable it in your firmware with the -DENABLE_FUSS build flag.
+
+
+[6]: https://bitbucket.org/xoseperez/nofuss

docs/Sensors.md

@@ -0,0 +1,3 @@
+# Sensors
+
+*TODO*

docs/Troubleshooting.md

@@ -0,0 +1,5 @@
+# Troubleshooting
+
+After flashing the firmware via serial do a hard reset of the device (unplug & plug). There is an issue with the ESP.reset() method. Check [https://github.com/esp8266/Arduino/issues/1017][1] for more info.
+
+[1]: https://github.com/esp8266/Arduino/issues/1017