updated documentation to include ESP8266

README.md

@@ -1,20 +1,39 @@
 # A gateway for 433 MHz devices
-It uses [rc_switch](https://github.com/sui77/rc-switch) library for controlling wall sockets.
+It uses [rc_switch](https://github.com/sui77/rc-switch) library for controlling wall sockets and receiving data from sensors. The library supports multiple protocols, the ones used by this gateway are:
+- Protocol 1, 2, 4, and 5 for wall switches
+- Protocol 2 for sensors
+- It can be extended to support more protocols
 
-It supports receiving:
+It works with 2 possible hardwares: Arduino Pro Mini and ESP8266 (currently in use). The code specific to each microcontroller is activated using `#define` directive:
-- serial commands for controlling wall switches - all protocols
+``` C
-- RC commands from wall switches remotes - protocols 1 and 2
+#if defined(ESP8266)
-- sensors states over `Protocol 2`
+#include "huzzah.h"
+#else
+#include "pro-mini.h"
+#endif
 
-It acts as a serial gateway, communicating in JSON format, and it is connected to a Raspberry Pi running Home Assistant.
+```
+## Serial communication using Arduino Pro Mini
+It works with an Arduino Pro Mini 5v 16 Mhz, where the original bootloader has been replaced with Optiboot using this tutorial: https://andreasrohner.at/posts/Electronics/How-to-make-the-Watchdog-Timer-work-on-an-Arduino-Pro-Mini-by-replacing-the-bootloader/
 
-It uses an Arduino Pro Mini 5v 16 Mhz.
+It is used as a serial gateway communicating in JSON format, when connected to a Raspberry Pi running Home Assistant.
-The original bootloader has been replaced with Optiboot using this tutorial: https://andreasrohner.at/posts/Electronics/How-to-make-the-Watchdog-Timer-work-on-an-Arduino-Pro-Mini-by-replacing-the-bootloader/
 
-## Receive RC
+### Mode of operation:
-### Sensors
+- it receives commands in JSON format over serial and translates them into RC commands to be sent to wall switches: ON/OFF
-Sensors transmit state using `Protocol 2` and the gateway translates them into JSON over serial.
+- it receives sates from sensors, or RC commands from RC remotes, and translates them into JSON, which is written on `Serial` to be consumed by HA
-##### Protocol structure
+
+## MQTT communication using ESP8266
+It works with any ESP8266 board, an [Adafruit Huzzah](https://learn.adafruit.com/adafruit-huzzah-esp8266-breakout) in this case.
+
+It is used as a gateway communicating in JSON format with Home Assistant, by publishing and subscribing to topics on MQTT. Devices on Home Assistant side are configured automatically using [MQTT discovery](https://www.home-assistant.io/integrations/mqtt/#configuration-via-mqtt-discovery).
+
+### Mode of operation:
+- it receives commands over MQTT and translates them into RC commands to be sent to wall switches: ON/OFF
+- it receives sates from sensors, or RC commands from RC remotes, translates them into JSON and updates devices in HA by publishing messages on MQTT
+
+## Sensors
+Sensors transmit state using `Protocol 2`, a 32 bit unsigned number.
+#### Protocol structure
 ```
    STATE
      |
@@ -22,7 +41,13 @@ Sensors transmit state using `Protocol 2` and the gateway translates them into J
 ----|-----------|-------------|-----
 TYPE|    VALUE  |     VCC     |  ID
 ```
-##### Sensors types
+where:
+- **ID**: uniquely identifies a sensor
+- **TYPE**: the type of the sensor, see bellow
+- **VALUE**: used for _GENERIC_, _HUMIDITY_ and _TEMPERATURE_ sensors
+- **STATE**: used for _CONTACT_ sensor only; since it doesn't conflict with other sensor types, it uses one bit from **VALUE**
+- **VCC**: battery voltage, used to detect when batteries need to be replaced
+#### Sensors types
 ```C++
 enum SensorType : uint8_t {
 	GENERIC = 4,
@@ -31,7 +56,7 @@ enum SensorType : uint8_t {
 	CONTACT = 7
 };
 ```
-##### Sensors IDs
+#### Sensors IDs
 ```C++
 enum SensorId : uint8_t {
 	WINDOW1 = 1,
@@ -43,7 +68,9 @@ enum SensorId : uint8_t {
 	OIL_SENSOR = 7
 };
 ```
-#### Stairs temperature
+### Devices
+#### [Servers room temperature](./devices/temp_sensor/)
+Type: **TEMPERATURE**
 ##### Value and voltage
 ```json
 {
@@ -65,7 +92,8 @@ enum SensorId : uint8_t {
   }
 }
 ```
-#### Oil sensor
+#### [Oil tank sensor](./devices/oil_sensor/)
+Type: **GENERIC**
 ##### Value and voltage
 ```json
 {
@@ -78,10 +106,24 @@ enum SensorId : uint8_t {
   }
 }
 ```
-### Switches
+#### [Presence sensor](./devices/presence_sensor/)
-Gateway receives remote commands over RC Switch and translates them into JSON over serial
+Type: **CONTACT**
+##### Value and voltage
+```json
+{
+  "sensor": {
+    "id": 8,
+    "diagnostic": {
+      "voltage": 3.28
+    },
+    "value": 1
+  }
+}
+```
+## Switches
+Gateway receives remote commands over RC Switch and translates them into JSON.
 #### Protocol 1
-##### on
+##### ON
 ```json
 {
   "rcSwitch": {
@@ -93,7 +135,7 @@ Gateway receives remote commands over RC Switch and translates them into JSON ov
   }
 }
 ```
-##### off
+##### OFF
 ```json
 {
   "rcSwitch": {
@@ -126,7 +168,7 @@ Gateway receives remote commands over RC Switch and translates them into JSON ov
 }
 ```
 ### DHT
-Reads local DHT11 sensor and outputs JSON over serial
+Reads local DHT11 sensor and outputs it into JSON.
 ```
 {
   "dht11": {
@@ -136,10 +178,10 @@ Reads local DHT11 sensor and outputs JSON over serial
 }
 ```
 ---
-## Receive commands
+## Commands from Home Assistant
-It receives commands over serial, in JSON format, and executes them.
+It receives commands in JSON format, over serial or MQTT, and executes them.
 #### Protocol 1
-##### on
+##### ON
 ```json
 {
   "rcSwitch": {
@@ -150,7 +192,7 @@ It receives commands over serial, in JSON format, and executes them.
   }
 }
 ```
-##### off
+##### OFF
 ```json
 {
   "rcSwitch": {