Docs vuepress (#476)

Convert docs to vuepress

.travis.yml

@@ -23,21 +23,38 @@
 #
 # Template #1: General project. Test it using existing `platformio.ini`.
 #
+matrix:
+  include:
+    - language: python
+      python: 2.7
 
-language: python
-python:
-    - "2.7"
+      sudo: false
+      cache:
+            directories:
+            - "~/.platformio"
 
-sudo: false
-cache:
-    directories:
-        - "~/.platformio"
-
-install:
-    - pip install -U platformio
-    - platformio update
-    - rm /home/travis/build/1technophile/OpenMQTTGateway/main//User_config.h
-    - cp /home/travis/build/1technophile/OpenMQTTGateway/test/Test_config.h /home/travis/build/1technophile/OpenMQTTGateway/main//User_config.h
+      install:
+        - pip install -U platformio
+        - platformio update
+        - rm /home/travis/build/1technophile/OpenMQTTGateway/main//User_config.h
+        - cp /home/travis/build/1technophile/OpenMQTTGateway/test/Test_config.h /home/travis/build/1technophile/OpenMQTTGateway/main//User_config.h
 
-script:
-    - platformio run
+      script:
+        - platformio run
+
+    - language: node_js
+      node_js:
+        - lts/*
+      install:
+        - npm install -g vuepress
+      script:
+        - npm run docs:build
+      before_deploy: echo "docs.openmqttgateway.com" >> docs/.vuepress/dist/CNAME
+      deploy:
+        provider: pages
+        skip-cleanup: true
+        local_dir: docs/.vuepress/dist
+        github-token: $GITHUB_TOKEN # a token generated on github allowing travis to push code on you repository
+        keep-history: true
+        on:
+          branch: development

docs/.vuepress/config.js

@@ -0,0 +1,91 @@
+module.exports = {
+    markdown: {
+      lineNumbers: true
+    },
+    title: 'OpenMQTTGateway',
+    description: 'One gateway, many technologies',
+    themeConfig: {
+      smoothScroll: true,
+      repo: '1technophile/OpenMQTTGateway',
+      docsDir: 'docs',
+      docsBranch: 'development',
+      lastUpdated: 'Last Updated',
+      editLinks: true,
+      nav: [
+        { text: 'Blog', link: 'https://1technophile.blogspot.com'},
+        { text: 'Docs', link: '/'},
+        { text: 'Community', link: 'https://community.openmqttgateway.com', target:'_self', rel:''},
+        { text: 'Devices', link: 'https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=2126158079'}
+      ],
+      sidebar: [
+        ['/','0 - What is it for 🏠'],
+        {
+          title: '1 - Prerequisites🧭',   // required
+          path: '/prerequisites/devices/',       // optional, which should be a absolute path.
+          //collapsable: true, // optional, defaults to true
+          sidebarDepth: 1,    // optional, defaults to 1
+          children: [
+            'prerequisites/devices',
+            'prerequisites/board',
+            'prerequisites/broker',
+            'prerequisites/controller']
+        },
+        {
+          title: '2 - Set it up 🔨',   // required
+          path: '/setitup/rf',       // optional, which should be a absolute path.
+          sidebarDepth: 1,    // optional, defaults to 1
+          children: [
+            'setitup/rf',
+            'setitup/ble',
+            'setitup/ir',
+            'setitup/lora',
+            'setitup/gsm',
+            'setitup/sensors',
+            'setitup/actuators'
+          ]
+        },
+        {
+          title: '3 - Upload ➡️',   // required
+          path: '/upload/binaries',       // optional, which should be a absolute path.
+          sidebarDepth: 1,    // optional, defaults to 1
+          children: [
+            'upload/binaries',
+            'upload/pio'
+          ]
+        },
+        {
+          title: '4 - Use ✈️',   // required
+          path: '/use/rf',       // optional, which should be a absolute path.
+          sidebarDepth: 1,    // optional, defaults to 1
+          children: [
+            'use/rf',
+            'use/ble',
+            'use/ir',
+            'use/lora',
+            'use/gsm',
+            'use/rfm69',
+            'use/sensors',
+            'use/actuators'
+          ]
+        },
+        {
+          title: '5 - Integrate 🎉',   // required
+          path: '/integrate/openhab2/',       // optional, which should be a absolute path.
+          sidebarDepth: 1,    // optional, defaults to 1
+          children: [
+            'integrate/openhab2',
+            'integrate/home_assistant',
+            'integrate/node_red'
+          ]
+        },
+        {
+          title: '6 - Participate 💻',   // required
+          sidebarDepth: 1,    // optional, defaults to 1
+          children: [
+            'CONTRIBUTING',
+            ['https://github.com/1technophile/OpenMQTTGateway/blob/development/LICENSE.txt','License']
+          ]
+        }
+    ]
+    }
+  }

docs/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+I like pull requests from everyone. By participating in this project, you
+agree to follow the code of conduct below
+
+[code of conduct]: https://github.com/1technophile/OpenMQTTGateway/blob/master/CODE_OF_CONDUCT.md
+
+Fork the [development branch](https://github.com/1technophile/OpenMQTTGateway/tree/development), then clone the repo
+
+Make your modification,
+* If you want to add a new gateway, name it `ZgatewayXXX`, `XXX` replaced by your gateway communication type, can be more than three letters
+* If you want to add a new sensor, name it `ZsensorYYY`, `YYY` replaced by your sensor type, can be more than three letters
+* If you want to add a new actuator, name it `ZactuatorZZZ`, `ZZZ` replaced by your actuator type, can be more than three letters
+
+Review your code, compile it for Arduino Uno and ESP8266
+
+Test it localy on your hardware config
+
+If you modify `User_config.h` during your developments you need to report your modifications into Test_config.h
+https://github.com/1technophile/OpenMQTTGateway/blob/master/tests/Test_config.h 
+Indeed during the continuous integration process `User_config.h` is replaced by `Test_config.h`. 
+`Test_config.h` as much more gateway/sensors enabled for the test than the default `User_config.h`
+
+Emit a pull request
+
+Verify the travis CI compilation results
+
+Request for review
+
+I may suggest some changes or improvements or alternatives.
+
+Some things that will increase the chance that your pull request is accepted:
+* Comment your code
+* Ask eventually for design guidelines
+* Write a [good commit message][commit].
+
+[commit]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

docs/README.md

@@ -1,55 +1,35 @@
-# OpenMQTTGateway
-
-## Overview
-
-OpenMQTTGateway act as a WIFI or Ethernet gateway between your 433mhz/315mhz/Infrared/BLE/GSM/GPRS devices and a MQTT broker.
-
-The MQTT broker can be connected to your favorite home automation controller (Home Assistant, Openhab, Domoticz) or NodeRED, as long as it supports MQTT, the system can talk to the gateway and by the way your different devices on both directions.
-
-[![](https://github.com/1technophile/OpenMQTTGateway/blob/master/img/OpenMQTTGateway.jpg)](https://github.com/1technophile/OpenMQTTGateway/wiki)
-
-It can be installed on:
-* Arduino uno(limited)/mega(advised) + W5100
-* ESP8266: NodeMCU V1.0 NodeMCU V2.0, NodeMCU V3.0, ESP8266 12F and Wemos D1
-* ESP32
-* Sonoff RF bridge.
-
-  It enables to:
-* Send RF signals corresponding to received MQTT data (MQTT->RF)
-* Publish MQTT data related to a received 433Mhz signal (RF-->MQTT)
-* Send RFM69 signals corresponding to received MQTT data (MQTT->RFM69)
-* Publish MQTT data related to a received RFM69 signal (RFM69-->MQTT)
-* Send IR signal corresponding to received MQTT data (MQTT->IR)
-* Publish MQTT data related to received IR signal (IR-->MQTT)
-* Publish MQTT data related to BLE beacons or Mi flora(BT-->MQTT)
-* Publish MQTT data related to received SMS (2G-->MQTT)
-* Send SMS corresponding to received MQTT data (MQTT->2G)
-
-It supports also sensors; DHT, HC SR501, ADC, I2C bus, INA226, TSL2561
-Or can actutate a relay.
-
-## Functions:
-* Bidirectional, the gateway can send and receive signals, for example if you have RF wall plug you can either control them with your home automation software (MQTT-->RF) or the physical remote control. When you press a button on the physical remote the wall plug will switch ON and the button in your home automation software (RF-->MQTT) will be updated.
-* Signal duplicate removal, with RF of IR we get a lot of duplication, to avoid this the gateway is able to filter the number of code sent to the MQTT broker during a defined time `time_avoid_duplicate`.
-* BLE beacons detection, the gateway publish the beacons detected thanks to an HM-10 module and publish the signal strength of each module address. By this way you can easily address presence detection of people, animals or things.
-* Addons possibility, you could add directly to the gateway any sensor you want, just create a new `Z<addon> .ino` file into the gateway folder with your code and call it after `client.loop();` into `OpenMQTTGateway.ino`. The program is provided with a DHT sensor addon implementation (`ZaddonDHT.ino`)
-* Advanced signal details publication, so as to know the details of what the gateway receive it publish by MQTT to `subject433toMQTTAdvanced` for RF and `subjectIRtoMQTTAdvanced `for IR the details of the signal received (this signal has to be compatible with RCSwitch and IRRemote libraries to be read).
-* Acknowledgement, to be sure that the gateway received the payload from MQTT it sends an acknowledgement on a `user_defined` topic, `subjectGTWRFtoMQTT` for RF or `subjectGTWIRtoMQTT` for IR enabling to update the state of your switch or other component into your home automation.
-* Multi boards compatibility, the gateway has been currently tested with **ESP8266 12F**, **NodeMCU V1**, **NodeMCU V2**, **Wemos D1 mini**, **Arduino Uno**, **ESP32** (RF and BLE gateways) and the **Arduino Mega**.
-* Multi protocols handling, the gateway is based on RCSwitch, NewRemoteSwitch, RFM69, A6lib and IRRemote libraries, you can define the protocol you want to use.
-* Configuration by web portal with **ESP8266** based boards
-
-See the [wiki](https://github.com/1technophile/OpenMQTTGateway/wiki) for more information:  
-https://github.com/1technophile/OpenMQTTGateway/wiki
-
-Download OpenMQTTGateway from the [releases page](https://github.com/1technophile/OpenMQTTGateway/releases)
-
-The reference sheet, with the list of all functions, pinouts is [here](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=0)
-
-A list of supported 433mhz devices (and others) is available [here](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=2126158079), door/window sensors, PIR sensors, smoke detectors, weather stations...
-
-A list of compatible components to build your gateway is available [here](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277), nodemcu, esp32, emitters and receivers...
-
-If you want to buy a coffee or other beverage so as to give me some support, here is a way to do it : 
-
-<a href="https://www.buymeacoffee.com/1technophile" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>
+OpenMQTTGateway project goal is to concentrate in one gateway different technologies, decreasing by the way the number of proprietary gateways needed and hiding the different technologies singularity behind a simple & wide spread communication protocol; [MQTT](http://mqtt.org/).
+
+![Overview](./img/OpenMQTTGateway.png)
+
+OpenMQTTGateway support very mature technologies like basic 433mhz/315mhz protocols & infrared so as to make your old dumb devices "smart" and avoid you to throw then away. These devices have also the advantages of having a lower cost compared to Zwave or more sophisticated protocols.
+And support also up to date technologies like Bluetooth Low Energy or LORA.
+
+To have an overview of the supported PIR, door, water, smoke sensors, sirens, rings, beacons, switchs & weather stations you can take a look to the 
+[compatible devices list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=2126158079)
+
+With MQTT you can connect the compatible software you want, it can be an home automation controller (OpenHAB, Home Assistant, Jeedom, FHEM, Domoticz...) or another software like Node-Red.
+
+# Use cases
+With OpenMQTTGateway and a controller you can for example:
+* Monitor your garden with a Mi Flora sensor and control an irrigation valve depending on the soil moisture,
+* Trigger a fan depending on the temperature and humidity thanks to a Mi Jia sensor,
+* Alert yourself by a controller notification if the temperature of your fridge is too high,
+* Detect your beacon/smartwatch so as to trigger a special scenario when you come home,
+* Detect opened door or windows and alert yourself when leaving home
+* Detect water leakage or smoke
+* Actionate a siren if something is going wrong
+The limit is your imagination 😀
+
+# Functions
+Behind the scene you will find functionnalities dedicated to gateways like:
+* Deduplication
+* Simple and lite API
+* Strong integrations with libraries used
+* Signal forward/repeat
+* First configuration with web portal
+* Whitelist & Blacklist management
+
+::: warning Note
+The material and information contained in this documentation is for general information purposes only. You should not rely upon the material or information on this documentation as a basis for making any business, legal or any other decisions. There is no warranty given on this documentation content. If you decide to follow the informations and materials given it is at your own risk.I will not be liable for any false, inaccurate, inappropriate or incomplete information presented on this website.
+:::

docs/integrate/home_assistant.md

@@ -0,0 +1,98 @@
+# Integrate Home Assistant
+## Auto discovery
+So as to enable HASS auto discovery with MQTT you have to uncomment [ZmqttDiscovery](https://github.com/1technophile/OpenMQTTGateway/blob/0180a0dbd55ed8e0799e30ee84f68070a6f478fa/User_config.h#L99) in user_config.h
+And enable discovery on your MQTT integration definition in HASS.
+
+OMG will use the auto discovery functionality of home assistant to create sensors and gateways into your HASS instance automaticaly.
+
+## Manual integration examples
+From @123, @finity,@denniz03
+
+### Door sensor
+```yaml
+binary_sensor:
+  - platform: mqtt
+    name: "test"
+    state_topic: "home/OpenMQTTGateway/433toMQTT"
+    value_template: >-
+      {% if value_json.value == '7821834' %}
+        {{'ON'}}
+      {% elif value_json.value == '7821838' %}
+        {{'OFF'}}
+      {% else %}
+        {{states('binary_sensor.test') | upper}}
+      {% endif %}
+    qos: 0
+    device_class: opening
+```
+
+```yaml
+binary_sensor:
+  - platform: mqtt
+    name: doorbell
+    state_topic: 'home/OpenMQTTGateway/SRFBtoMQTT'
+    #value_template: "{{ value_json.raw }}"
+    value_template: >- 
+      {% if value_json.value == '14163857' %}
+        {{'ON'}}
+      {% else %}
+        {{states('binary_sensor.doorbell') | upper}}
+      {% endif %}
+    off_delay: 30
+    device_class: 'sound'
+  - binary_sensor:
+    platform: mqtt
+    name: light_back_sensor
+    state_topic: 'home/OpenMQTTGateway/SRFBtoMQTT'
+    #value_template: '{{ value_jason.value }}'
+    value_template: >- 
+      {% if value_json.value == '1213858' %}
+        {{'ON'}}
+      {% else %}
+        {{states('binary_sensor.light_back_sensor') | upper}}
+      {% endif %}
+    off_delay: 5
+  - binary_sensor:
+    platform: mqtt
+    name: rf_outlet_sensor
+    state_topic: 'home/OpenMQTTGateway/SRFBtoMQTT'
+    value_template: >- 
+      {% if value_json.value == '16766303' %}
+        {{'ON'}}
+      {% else %} 
+        {{states('binary_sensor.rf_outlet_sensor') | upper}}
+      {% endif %}
+```
+
+### Motion sensor
+```yaml
+binary_sensor:
+      - platform: mqtt
+        name: "Bewegung_Schlafzimmer"
+        #device_class: motion
+        state_topic: "home/OpenMQTTGateway1/HCSR501toMQTT"
+        value_template: '{{ value_json["hcsr501"] }}'
+        payload_on: "true"
+        payload_off: "false"
+```
+
+### Switches
+
+```yaml
+#switches
+switch:
+- platform: mqtt
+  name: kaku_a2
+  state_topic: "home/OpenMQTTGateway/commands/MQTTto433"
+  command_topic: "home/OpenMQTTGateway/commands/MQTTto433"
+  payload_on: "16405"
+  payload_off: "16404"
+  qos: "0"
+  retain: true
+
+#pushbullet
+notify:
+- platform: pushbullet
+  name: hassio
+  api_key: <api_key>
+```