README Rework

Documentation/Changelog.md

@@ -0,0 +1,66 @@
+
+# Changelog
+
+<br>
+
+## Version 2
+
+**When:** `January 2020` <br>
+**What:**     `Removes Wunderground Support`
+
+<br>
+
+### Wunderground ➞ OpenWeatherMap
+
+*Weather Data Provider Replacement*
+
+<br>
+
+**Wunderground**, the weather information provider <br>
+we used so far, [stopped their free tier][No Free] without notice <br>
+on `May 15, 2018` .
+
+This release adds support for `OpenWeatherMap.com` , an <br>
+alternate provider with a free tier for weather information.
+
+The `WeatherStationDemo` has been adapted to use <br>
+this new **API** through the `OpenWeatherMapCurrent` <br>
+and `OpenWeatherMapForecast` **REST** clients.
+
+<br>
+
+*Sadly **OpenWeatherMap** provides less* <br>
+*information than **Wunderground** does.*
+
+<br>
+
+If you are missing attributes in the response docs <br>
+then please contact the **[OpenWeatherMap]** team.
+
+<br>
+<br>
+
+### OLED Library Upgrade
+
+<br>
+
+The **ESP8266 OLED Library** changed <br>
+a lot with the latest release of `v3.0.0` .
+
+We fixed many bugs, changed the **API** <br>
+a little bit and improved performance.
+
+This means that you might have to adapt <br>
+your ***Weather Station Code*** if you created <br>
+it using older `2.x.x` versions.
+
+Either compare your code to the updated <br>
+**WeatherStationDemo** or read the guide <br>
+on how to **[Upgrade]**.
+
+
+<!----------------------------------------------------------------------------->
+
+[Upgrade]: https://github.com/ThingPulse/esp8266-oled-ssd1306/blob/master/UPGRADE-3.0.md
+[OpenWeatherMap]:    https://openweathermap.desk.com/customer/portal/emails/new
+[No Free]:           https://thingpulse.com/weather-underground-no-longer-providing-free-api-keys/

Documentation/Design.md

@@ -0,0 +1,29 @@
+
+## Why A Library?
+
+I realized that more and more the **Weather Station** <br>
+was becoming a general framework for displaying <br>
+data over **WiFi** to one of these pretty displays.
+
+<br>
+
+#### What Was Needed
+
+However everyone would have different ways or <br>
+sources for data and as such, the important part <br>
+of the library would rather be the classes that <br>
+fetch the data, than the main class.
+
+<br>
+
+#### Data Fetchers
+
+In case you wrote a data fetcher that might be <br>
+of interest to others and you would like it to be <br>
+integrated in this library, simply contact me.
+
+Otherwise you might also want to offer your code <br>
+as extension library yourself and call it something <br>
+like `ESP8266-Weather-Station-< Your Service >`
+
+***We will gladly list it as third party library.***

Documentation/Install.md

@@ -0,0 +1,89 @@
+
+# Installation
+
+<br>
+
+## Arduino IDE
+
+### Setup
+
+Make sure you use a version of the **Arduino IDE** <br>
+which is supported by the **ESP8266** platform.
+
+Please follow the **[Tutorial]** on our website.
+
+<br>
+
+### Libraries
+
+Please install the following libraries:
+
+- `ESP8266 Weather Station`
+- `JSON Streaming Parser by Daniel Eichhorn`
+- `ESP8266 OLED Driver for SSD1306 display by Daniel Eichhorn`
+
+    *Please use `v3.0.0+`*
+
+##### How To
+
+<kbd>**Sketch**</kbd> <br>
+ › <kbd>**Include Library**</kbd> <br>
+ › <kbd>**Manage Libraries**</kbd>
+
+<br>
+
+### Preparation
+
+1. *[Create An API Key][API Key]* for **OpenWeatherMap**.
+
+2. Open the demo.
+
+    <kbd>**File**</kbd> <br>
+     › <kbd>**Examples**</kbd> <br>
+     › <kbd>**ESP8266 Weather Station**</kbd> <br>
+     › <kbd>**Weather Station Demo**</kbd>
+
+3. Insert the **OpenWeatherMap API Key**.
+
+4. Insert your **WiFi Credentials**.
+
+5. Adjust the location according to **OpenWeatherMap**.
+
+    ↳ `Zurich, CH`
+
+6. Adjust the **UTC** offset.
+
+
+<br>
+
+---
+
+<br>
+
+## PlatformIO
+
+### Setup
+
+1. Choose one of the available IDE integration or the Atom based IDE.
+
+2. Install libraries:
+    - `561`
+    - `562`
+    - `563`
+
+    With:
+
+    ```sh
+    platformio lib install
+    ```
+
+3. Adapt the [`WeatherStationDemo.ino`][Example] file to your<br>
+   needs as show in the **Arduino** preparations.
+
+
+<!----------------------------------------------------------------------------->
+
+[Tutorial]: https://docs.thingpulse.com/how-tos/Arduino-IDE-for-ESP8266/
+[API Key]:  https://docs.thingpulse.com/how-tos/openweathermap-key/
+[Example]:  examples/WeatherStationDemo/WeatherStationDemo.ino
+

Documentation/Modules.md

@@ -0,0 +1,68 @@
+
+# Modules
+
+*Modules Available In This Library*
+
+<br>
+
+## Time Client
+
+A simple class that uses the header <br>
+date and time to set the clock.
+
+<br>
+
+## NTP Client
+
+A **NTP** based time class written by `Fabrice Weinberg`.
+
+<br>
+
+## OpenWeatherMap Client
+
+A **REST** client for the `OpenWeatherMap.com` <br>
+service, providing weather information.
+
+<br>
+
+## Aeris Client
+
+A client for the service provided by `aerisweather.com`.
+
+*Fully functional initial version.*
+
+After the [Wunderground Incident][Changelog] we first targeted <br>
+**Aeris** before we settled with **OpenWeatherMap**.
+
+*This code is **unmaintained** but will,* <br>
+*for now, remain part of this library.*
+
+<br>
+
+## Thingspeak Client
+
+Fetches data from **Thingspeak** which you might have <br>
+collected with another sensor node and posted there.
+
+<br>
+
+## Astronomy
+
+Algorithms to calculate current lunar phase and illumination.
+
+<br>
+
+## SunMoonCalc
+
+A calculator for sun / moon properties <br>
+for a given date, time and location.
+
+*This implementation is port of a* ***Java*** <br>
+*class by [T. Alonso Albi] from :es: **OAN**.*
+
+
+<!----------------------------------------------------------------------------->
+
+[Changelog]: Changelog.md
+
+[T. Alonso Albi]: http://conga.oan.es/~alonso/doku.php?id=blog:sun_moon_position