Add README.md file to firmware

firmware/README.md

@@ -0,0 +1,61 @@
+# øko weatherstatiøn firmware
+
+## How to get started with Arduino
+
+https://git.okoyono.de/oko/weatherstation/wiki#flashing-the-firmware
+
+* Install Arduino IDE: https://www.arduino.cc/en/Guide/HomePage#install
+* Install ESP in Arduino IDE board manager: https://github.com/esp8266/Arduino#installing-with-boards-manager
+* Select `LOLIN(WEMOS) D1 R2 & mini` as Board
+* Set Sketch location (File -> Preferences -> Sketchbook Location) to this folder (not `libraries/`)
+* Copy `user_config.h` and adjust the values
+
+## FAQ
+
+### Why bundle external libs?
+
+We decided to put these libs inside the project folder, because we have a lot
+of issues with finding the right libs (some libs need a specific version, some
+libs have no unique name, some libs are broken, ...). This is not a fine
+software engineering practice, but it was too much of a hassle to get this
+right, so we decided to put everything in version control. This way, we also
+can control the version of the lib, which makes the build process of this
+project more robust to changes.
+
+You can update the libs using the Arduino IDE.
+
+### How to fix error: Can't find file `config_user.h`?
+
+If you compile the source code and it can't find this file, this is intentional
+:) You need to create a `config_user.h` with your own settings. Use the
+`config_user.h.example` as a starting point.
+
+### How to fix java exception on Serial Port open?
+
+That can happen with openjdk 8. Try a newer openjdk version (>9)
+
+### How can I add a new Sensor?
+
+* Create a file `sensor_$sensorname.ino`
+* Add flag to `config_user.h` (don't forget to update `config_user.h.example`
+* Add initialization method of sensor (should be named `sensor_$sensorname_begin()` to `setup()` in `firmware.ino` guarded with preprocessor flag
+* Create method without parameters returning a float and safe function reference into `sensors` array
+
+### Whats wrong with all the NaN's?
+
+If a sensor does not produce a value the sensor value is Not a Number (`NaN`).
+InfluxDB client will filter NaN values before sending the data.
+
+`nanf()` returns a `float NaN`. The argument can be used by library
+implementations to distinguish different NaN values in a
+implementation-specific manner.
+
+## Wishlist
+
+- Webserver for /metrics endpoint (Prometheus)
+- Push sensor values to various 3rd party services (https://openweathermap.org/, http://www.weewx.com/)
+- MQTT
+- Buffer sensor values if there is no WIFI connection
+- Configure weather station over http web interface
+- OTA firmware update
+- evaluate https://sminghub.github.io/Sming/about/ or https://github.com/marvinroger/homie-esp8266

firmware/firmware.ino

@@ -5,47 +5,16 @@
 #include <DNSServer.h>
 #include <ESP8266WebServer.h>
 
-// External libs
-// We decided to put these libs inside the project folder, because we have a lot
-// of issues with finding the right libs (some libs need a specific version, some
-// libs have no unique name, some libs are broken, ...). This is not a fine
-// software engineering practice, but it was too much of a hassle to get this right,
-// so we decided to put everything in version control. This way, we also can control
-// the version of the lib, which makes the build process of this project more
-// robust to changes.
-// IMPORTANT: You need to set the sketch location of your Arduino IDE to the firmware
-// folder in order to use the libs. (File -> Preferences -> Sketchbook Location)
 #include <WiFiClient.h>          // WiFiClient
 #include <WiFiManager.h>         // WiFiManager
 
 // Project includes
 #include "config.h"
 
-// IMPORTANT: If you compile the sourcecode and it can't find this file, this is
-// intentional :) You need to create a config_user.h with your own settings. Use the
-// config_user.h.example as a starting point.
 #include "config_user.h"
 
 //*************************************************************************//
 
-/**
- * Whishlist:
- * - Webserver for /metrics endpoint (Prometheus)
- * - Show current sensor values over simple webpage
- * - Push sensor values to various 3rd party services (https://openweathermap.org/)
- * - MQTT?
- *
- * - Buffer sensor values if there is no WIFI connection
- * - Configure weather station over http webinterface
- * - OTA firmware update
- *
- * TODO:
- * - https://sminghub.github.io/Sming/about/
- * - https://github.com/marvinroger/homie-esp8266
- */
-
-//*************************************************************************//
-
 const uint8_t VALUES = 8;
 float currentSensorData[VALUES] = {nanf("no value"), nanf("no value"), nanf("no value"), nanf("no value"), nanf("no value"), nanf("no value"), nanf("no value"), nanf("no value")};
 float (*sensors[VALUES])() = {};