From 671a9b84870bf80f806186de949c1a65f02d416a Mon Sep 17 00:00:00 2001
From: Nicu Hodos <nicu@hodos.ro>
Date: Thu, 16 Oct 2025 21:57:48 +0200
Subject: [PATCH] updated documentation to include ESP8266

---
 README.md | 92 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 67 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index d081dc5..2b68c26 100644
--- a/README.md
+++ b/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:
-- serial commands for controlling wall switches - all protocols
-- RC commands from wall switches remotes - protocols 1 and 2
-- sensors states over `Protocol 2`
+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:
+``` C
+#if defined(ESP8266)
+#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.
-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 is used as a serial gateway communicating in JSON format, when connected to a Raspberry Pi running Home Assistant.
 
-## Receive RC
-### Sensors
-Sensors transmit state using `Protocol 2` and the gateway translates them into JSON over serial.
-##### Protocol structure
+### Mode of operation:
+- it receives commands in JSON format over serial 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, and translates them into JSON, which is written on `Serial` to be consumed by HA
+
+## 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
-Gateway receives remote commands over RC Switch and translates them into JSON over serial
+#### [Presence sensor](./devices/presence_sensor/)
+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
-It receives commands over serial, in JSON format, and executes them.
+## Commands from Home Assistant
+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": {