rc-gateway/README.md

# A gateway for 433 MHz devices
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 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

```
## 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 is used as a serial gateway communicating in JSON format, when connected to a Raspberry Pi running Home Assistant.

### 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
     |
1010|1|101010101|1010101010101|10101
----|-----------|-------------|-----
TYPE|    VALUE  |     VCC     |  ID
```
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,
	HUMIDITY = 5,
	TEMPERATURE = 6,
	CONTACT = 7
};
```
#### Sensors IDs
```C++
enum SensorId : uint8_t {
	WINDOW1 = 1,
	WINDOW2 = 2,
	WATER_SENSOR = 3,
	TEMP_SENSOR = 4,
	LIGHT_SENSOR = 5,
	MOVEMENT_SENSOR = 6,
	OIL_SENSOR = 7
};
```
### Devices
#### [Servers room temperature](./devices/temp_sensor/)
Type: **TEMPERATURE**
##### Value and voltage
```json
{
  "sensor": {
    "id": 4,
    "diagnostic": {
      "voltage": 2.239
    },
    "temperature": 16.2
  }
}
```
##### Value only
```json
{
  "sensor": {
    "id": 4,
    "temperature": 16.2
  }
}
```
#### [Oil tank sensor](./devices/oil_sensor/)
Type: **GENERIC**
##### Value and voltage
```json
{
  "sensor": {
    "id": 7,
    "diagnostic": {
      "voltage": 4.282
    },
    "value": 13
  }
}
```
#### [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
```json
{
  "rcSwitch": {
    "protocol": 1,
    "state": true,
    "group": "1",
    "channel": 1,
    "raw_value": 5571921
  }
}
```
##### OFF
```json
{
  "rcSwitch": {
    "protocol": 1,
    "state": false,
    "group": "1",
    "channel": 1,
    "raw_value": 5571921
  }
}
```

#### Protocol 2
```json
{
  "rcSwitch": {
    "protocol": 2,
    "value": 2650807673
  }
}
```

#### Other protocols
```json
{
  "rcSwitch": {
    "protocol": 4,
    "value": 1234567890
  }
}
```
### DHT
Reads local DHT11 sensor and outputs it into JSON.
```
{
  "dht11": {
    "temperature": 31.9,
    "humidity": 45
  }
}
```
---
## Commands from Home Assistant
It receives commands in JSON format, over serial or MQTT, and executes them.
#### Protocol 1
##### ON
```json
{
  "rcSwitch": {
    "protocol": 1,
    "group": "00001",
    "channel": 1,
    "state": true
  }
}
```
##### OFF
```json
{
  "rcSwitch": {
    "protocol": 1,
    "group": "00001",
    "channel": 1,
    "state": false
  }
}
```

#### Protocol 2
```json
{
  "rcSwitch": {
    "protocol": 2,
    "value": "10010110000000000001110101111001"
  }
}
```

#### Other protocols
```json
{
  "rcSwitch": {
    "protocol": 4,
    "value": "010001101001100101110100"
  }
}
```