Revert tree to v1.5.0 (dev now happens in develop branch)

The new workflow is Git Flow

README.md

@@ -1,24 +1,16 @@
-![homie-esp8266 banner](banner.png)
-
 Homie for ESP8266
 =================
 
-[![Build Status](https://img.shields.io/travis/marvinroger/homie-esp8266/master.svg?style=flat-square)](https://travis-ci.org/marvinroger/homie-esp8266) [![Latest Release](https://img.shields.io/badge/release-v1.5.0-yellow.svg?style=flat-square)](https://github.com/marvinroger/homie-esp8266/releases)
-
-An Arduino for ESP8266 implementation of [Homie](https://github.com/marvinroger/homie), an MQTT convention for the IoT.
-
-## Download
+![homie-esp8266](homie-esp8266.jpg)
 
-The Git repository contains the development version of Homie for ESP8266. Stable releases are available [on the releases page](https://github.com/marvinroger/homie-esp8266/releases).
+An Arduino for ESP8266 implementation of [Homie](https://git.io/homieiot), an MQTT convention for the IoT.
 
 ## Features
 
 * Automatic connection/reconnection to Wi-Fi/MQTT
-* [JSON configuration file](https://homie-esp8266.readme.io/v2.0.0/docs/json-configuration-file) to configure the device
-* [Cute HTTP API / Web UI / App](https://homie-esp8266.readme.io/v2.0.0/docs/http-json-api) to remotely send the configuration to the device and get information about it
-* [Custom settings](https://homie-esp8266.readme.io/v2.0.0/docs/custom-settings)
-* [OTA over MQTT](https://homie-esp8266.readme.io/v2.0.0/docs/ota-configuration-updates)
-* [Magic bytes](https://homie-esp8266.readme.io/v2.0.0/docs/magic-bytes)
+* [Cute JSON configuration file](docs/5.-JSON-configuration-file.md) to configure the credentials of the device
+* [Cute API / Web UI / App](docs/6.-Configuration-API.md) to remotely send the configuration to the device and get information about it
+* [OTA support](docs/4.-OTA.md)
 * Available in the [PlatformIO registry](http://platformio.org/#!/lib/show/555/Homie)
 * Pretty straightforward sketches, a simple light for example:
 
@@ -29,7 +21,7 @@ const int PIN_RELAY = 5;
 
 HomieNode lightNode("light", "switch");
 
-bool lightOnHandler(HomieRange range, String value) {
+bool lightOnHandler(String value) {
   if (value == "true") {
     digitalWrite(PIN_RELAY, HIGH);
     Homie.setNodeProperty(lightNode, "on", "true"); // Update the state of the light
@@ -46,16 +38,12 @@ bool lightOnHandler(HomieRange range, String value) {
 }
 
 void setup() {
-  Serial.begin(115200);
-  Serial.println();
-  Serial.println();
   pinMode(PIN_RELAY, OUTPUT);
   digitalWrite(PIN_RELAY, LOW);
 
-  Homie_setFirmware("awesome-relay", "1.0.0");
-
-  lightNode.advertise("on").settable(lightOnHandler);
-
+  Homie.setFirmware("awesome-relay", "1.0.0");
+  lightNode.subscribe("on", lightOnHandler);
+  Homie.registerNode(lightNode);
   Homie.setup();
 }
 
@@ -66,4 +54,4 @@ void loop() {
 
 ## Requirements, installation and usage
 
-The project is documented on https://homie-esp8266.readme.io with a *Getting started* guide and every piece of information you will need.
+The project is documented on the [/docs folder](docs), with a *Getting started* guide and every piece of informations you will need.

docs/1.-What-is-it.md

@@ -0,0 +1,5 @@
+# What is it?
+
+Homie for ESP8266 is an ESP8266 for Arduino implementation of [Homie](https://git.io/homieiot), a thin and simple MQTT convention for the IoT. More than that, it's also a full-featured framework to get started with your IoT project very quickly. Simply put, you don't have to manage yourself the connection/reconnection to the Wi-Fi/MQTT. You don't even have to hard-code credentials in your sketch: this can be done using a simple JSON API. Everything is handled internally, by Homie for ESP8266.
+
+You guessed it, the purpose of Homie for ESP8266 is to simplify the development of connected objects.

docs/2.-Getting-started.md

@@ -0,0 +1,184 @@
+# Getting started
+
+This *Getting Started* guide assumes you have an ESP8266 board with an user-configurable LED, and an user programmable button, like a NodeMCU DevKit 1.0, for example. These restrictions can be lifted. (see [Advanced usage](3.-Advanced-usage.md))
+
+To use Homie for ESP8266, you will need:
+
+* An ESP8266
+* The Arduino IDE for ESP8266 (version 2.2.0 minimum)
+* Basic knowledge of the Arduino environment (upload a sketch, import libraries, ...)
+* To understand [the Homie convention](https://git.io/homieiot)
+
+## Installing Homie for ESP8266
+
+There are two ways to install Homie for ESP8266.
+
+### 1a. For the Arduino IDE
+
+1. Download the [latest release](https://github.com/marvinroger/homie-esp8266/releases/latest)
+2. Load the `.zip` with **Sketch → Include Library → Add .ZIP Library**
+
+Homie for ESP8266 has 3 dependencies: `ArduinoJson`, `Bounce2` and `PubSubClient`. You can install them through the Arduino IDE, with **Sketch → Include Library → Manage Libraries**. Be sure the installed version is >= 5.0.8 for `ArduinoJson`, >= 2.0 for `Bounce2`, >= 2.5 for `PubSubClient`.
+
+### 1b. With [PlatformIO](http://platformio.org)
+
+In a terminal, run `platformio lib install 555`.
+
+Dependencies are installed automatically.
+
+## Bare minimum sketch
+
+```c++
+#include <Homie.h>
+
+void setup() {
+  Homie.setup();
+}
+
+void loop() {
+  Homie.loop();
+}
+```
+
+This is the bare minimum needed for Homie for ESP8266 to work correctly.
+If you upload this sketch, you will notice the LED of the ESP8266 will light on ![LED solid](assets/led_solid.gif). This is because you are in `configuration` mode.
+
+Homie for ESP8266 has 3 modes of operation:
+
+1. The `configuration` mode is the initial one. It spawns an AP and an HTTP webserver exposing a JSON API. To interact with it, you have to connect to the AP. Then, an HTTP client can get the list of available Wi-Fi networks, and send the credentials (like the Wi-Fi SSID, the Wi-Fi password, ...). Once the device receives the credentials, it boots into `normal` mode.
+
+2. The `normal` mode is the mode the device will be most of the time. It connects to the Wi-Fi, to the MQTT, it sends initial informations to the Homie server (like the local IP, the version of the firmware currently running, ...) and it subscribes from the MQTT to properties change. The device can return to `configuration` mode in different ways (press of a button or custom function, see [3. Advanced usage](3.-Advanced-usage.md)).
+
+3. The `OTA` mode is triggered from the `normal` mode when the MQTT server sends a version different from the current firmware version. It will reach the OTA HTTP server and flash the latest firmware available. When it ends (either a success or a failure), it returns to `normal` mode.
+
+**<u>Very important:</u> As a rule of thumb, never block the device with blocking code for more than 50ms or so.** Otherwise, you may very probably experience unexpected behaviors.
+
+## Connecting to the AP and configuring the device
+
+Homie for ESP8266 has spawned a secure AP named `Homie-xxxxxxxx`. For example, if the AP is named `Homie-c631f278`, the AP password is `c631f278`. Connect to it.
+
+*Note*: This `c631f278` ID is unique to each device, and you cannot change it. If you reflash a new sketch, this ID won't change.
+
+Once connected, the webserver is available at `http://homie.config`. To bypass the built-in DNS server, you can reach directly `192.168.1.1`. You can then configure the device using the [Configuration API](6.-Configuration-API.md). When the device receives its configuration, it will reboot to `normal` mode.
+
+## Understanding what happens in `normal` mode
+
+### Visual codes
+
+When the device boots in `normal` mode, it will start blinking:
+
+* ![Wi-Fi LED blinking](assets/led_wifi.gif) Slowly when connecting to the Wi-Fi
+* ![MQTT LED blinking](assets/led_mqtt.gif) Faster when connecting to the MQTT broker
+
+This way, you can have a quick feedback on what's going on. If both connections are established, the LED will stay off. Note the device will also blink during the automatic reconnection, if the connection to the Wi-Fi or the MQTT broker is lost.
+
+### Under the hood
+
+Although the sketch looks like it does not do anything, it actually does quite a lot:
+
+* It automatically connects to the Wi-Fi and MQTT broker. No more network boilerplate code
+* It exposes the Homie device on MQTT (as devices / `device ID`, e.g. `devices/c631f278`).
+* It subscribes to the special device property `$ota`, automatically rebooting in OTA mode if OTA is available
+* It checks for a button press on the ESP8266, to return to `configuration` mode
+
+## Creating an useful sketch
+
+Now that we understand how Homie for ESP8266 works, let's create an useful sketch. We want to create a smart light.
+
+```c++
+#include <Homie.h>
+
+const int PIN_RELAY = 5;
+
+HomieNode lightNode("light", "switch");
+
+bool lightOnHandler(String value) {
+  if (value == "true") {
+    digitalWrite(PIN_RELAY, HIGH);
+    Homie.setNodeProperty(lightNode, "on", "true"); // Update the state of the light
+    Serial.println("Light is on");
+  } else if (value == "false") {
+    digitalWrite(PIN_RELAY, LOW);
+    Homie.setNodeProperty(lightNode, "on", "false");
+    Serial.println("Light is off");
+  } else {
+    return false;
+  }
+
+  return true;
+}
+
+void setup() {
+  pinMode(PIN_RELAY, OUTPUT);
+  digitalWrite(PIN_RELAY, LOW);
+
+  Homie.setFirmware("awesome-relay", "1.0.0");
+  lightNode.subscribe("on", lightOnHandler);
+  Homie.registerNode(lightNode);
+  Homie.setup();
+}
+
+void loop() {
+  Homie.loop();
+}
+```
+
+Alright, step by step:
+
+1. We create a node with an ID of `light` and a type of `switch` with `HomieNode lightNode("light", "switch")`
+2. We set the name and the version of the firmware with `Homie.setFirmware("awesome-light" ,"1.0.0");`
+3. We want our `light` node to subscribe to the `on` property. We do that with `lightNode.subscribe("on", lightOnHandler);`. The `lightOnHandler` function will be called when the value of this property is changed
+4. We tell Homie for ESP8266 to expose our `light` node by registering it. We do this with `Homie.registerNode(lightNode);`
+5. In the `lightOnHandler` function, we want to update the state of the `light` node. We do this with `Homie.setNodeProperty(lightNode, "on", "true");`
+
+In about thirty SLOC, we have achieved to create a smart light, without any hard-coded credentials, with automatic reconnection in case of network failure, and with OTA support. Not bad, right?
+
+## Creating a sensor node
+
+In the previous example sketch, we were reacting on property changes. But what if we want, for example, to send a temperature every 5 minute? We could do this in the Arduino `loop()` function. But then, we would have to check if we are in `normal` mode, and we would have to ensure the network connection is up before sending any property. Boring.
+
+Fortunately, Homie for ESP8266 provides an easy way to do that.
+
+```c++
+#include <Homie.h>
+
+const int TEMPERATURE_INTERVAL = 300;
+
+unsigned long lastTemperatureSent = 0;
+
+HomieNode temperatureNode("temperature", "temperature");
+
+void setupHandler() {
+  // Do what you want to prepare your sensor
+}
+
+void loopHandler() {
+  if (millis() - lastTemperatureSent >= TEMPERATURE_INTERVAL * 1000UL || lastTemperatureSent == 0) {
+    float temperature = 22; // Fake temperature here, for the example
+    Serial.print("Temperature: ");
+    Serial.print(temperature);
+    Serial.println(" °C");
+    if (Homie.setNodeProperty(temperatureNode, "temperature", String(temperature), true)) {
+      lastTemperatureSent = millis();
+    } else {
+      Serial.println("Sending failed");
+    }
+  }
+}
+
+void setup() {
+  Homie.setFirmware("awesome-temperature", "1.0.0");
+  Homie.registerNode(temperatureNode);
+  Homie.setSetupFunction(setupHandler);
+  Homie.setLoopFunction(loopHandler);
+  Homie.setup();
+}
+
+void loop() {
+  Homie.loop();
+}
+```
+
+The only new things here are the `Homie.setSetupFunction(setupHandler);` and `Homie.setLoopFunction(loopHandler);` calls. The setup function will be called once, when the device is in `normal` mode and the network connection is up. The loop function will be called everytime, when the device is in `normal` mode and the network connection is up. This provides a nice level of abstraction.
+
+Now that you understand the basic usage of Homie for ESP8266, you can head on to the [Advanced usage](3.-Advanced-usage.md) page to learn about more powerful features like input handlers and the event system.