diff --git a/.travis.yml b/.travis.yml index f204491..90e0170 100644 --- a/.travis.yml +++ b/.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 diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js new file mode 100644 index 0000000..f98e0e6 --- /dev/null +++ b/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'] + ] + } + ] + } + } diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..3ae521a --- /dev/null +++ b/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 diff --git a/docs/README.md b/docs/README.md index 51ed795..e02a9e4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,55 +1,35 @@ -# OpenMQTTGateway +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 +![Overview](./img/OpenMQTTGateway.png) -OpenMQTTGateway act as a WIFI or Ethernet gateway between your 433mhz/315mhz/Infrared/BLE/GSM/GPRS devices and a MQTT broker. +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. -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. +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) -[![](https://github.com/1technophile/OpenMQTTGateway/blob/master/img/OpenMQTTGateway.jpg)](https://github.com/1technophile/OpenMQTTGateway/wiki) +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. -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) +# 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 😀 -It supports also sensors; DHT, HC SR501, ADC, I2C bus, INA226, TSL2561 -Or can actutate a relay. +# 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 -## 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 .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 : - -Buy Me A Coffee +::: 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. +::: diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index c419263..0000000 --- a/docs/_config.yml +++ /dev/null @@ -1 +0,0 @@ -theme: jekyll-theme-cayman \ No newline at end of file diff --git a/img/OMQTTG_8207.JPG b/docs/img/OMQTTG_8207.JPG similarity index 100% rename from img/OMQTTG_8207.JPG rename to docs/img/OMQTTG_8207.JPG diff --git a/img/OMQTTG_8211.JPG b/docs/img/OMQTTG_8211.JPG similarity index 100% rename from img/OMQTTG_8211.JPG rename to docs/img/OMQTTG_8211.JPG diff --git a/img/OMQTTG_8217.JPG b/docs/img/OMQTTG_8217.JPG similarity index 100% rename from img/OMQTTG_8217.JPG rename to docs/img/OMQTTG_8217.JPG diff --git a/img/OpenMQTTGateway.jpg b/docs/img/OpenMQTTGateway.jpg similarity index 100% rename from img/OpenMQTTGateway.jpg rename to docs/img/OpenMQTTGateway.jpg diff --git a/docs/img/OpenMQTTGateway.png b/docs/img/OpenMQTTGateway.png new file mode 100644 index 0000000..330cb56 Binary files /dev/null and b/docs/img/OpenMQTTGateway.png differ diff --git a/img/OpenMQTTGateway_ESP32_breadboard.jpg b/docs/img/OpenMQTTGateway_ESP32_breadboard.jpg similarity index 100% rename from img/OpenMQTTGateway_ESP32_breadboard.jpg rename to docs/img/OpenMQTTGateway_ESP32_breadboard.jpg diff --git a/img/OpenMQTTGateway_Pilight_Digoo-DG-R8S.png b/docs/img/OpenMQTTGateway_Pilight_Digoo-DG-R8S.png similarity index 100% rename from img/OpenMQTTGateway_Pilight_Digoo-DG-R8S.png rename to docs/img/OpenMQTTGateway_Pilight_Digoo-DG-R8S.png diff --git a/img/OpenMQTTGateway_SONOFF_RF_Bridge_FTDI.jpg b/docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_FTDI.jpg similarity index 100% rename from img/OpenMQTTGateway_SONOFF_RF_Bridge_FTDI.jpg rename to docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_FTDI.jpg diff --git a/img/OpenMQTTGateway_SONOFF_RF_Bridge_OTA.png b/docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_OTA.png similarity index 100% rename from img/OpenMQTTGateway_SONOFF_RF_Bridge_OTA.png rename to docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_OTA.png diff --git a/img/OpenMQTTGateway_SONOFF_RF_Bridge_disassembly.jpg b/docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_disassembly.jpg similarity index 100% rename from img/OpenMQTTGateway_SONOFF_RF_Bridge_disassembly.jpg rename to docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_disassembly.jpg diff --git a/img/OpenMQTTGateway_SONOFF_RF_Bridge_green_led.jpg b/docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_green_led.jpg similarity index 100% rename from img/OpenMQTTGateway_SONOFF_RF_Bridge_green_led.jpg rename to docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_green_led.jpg diff --git a/img/OpenMQTTGateway_SONOFF_RF_Bridge_serial_and_broker.png b/docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_serial_and_broker.png similarity index 100% rename from img/OpenMQTTGateway_SONOFF_RF_Bridge_serial_and_broker.png rename to docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_serial_and_broker.png diff --git a/img/OpenMQTTGateway_SONOFF_RF_Bridge_user_config.png b/docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_user_config.png similarity index 100% rename from img/OpenMQTTGateway_SONOFF_RF_Bridge_user_config.png rename to docs/img/OpenMQTTGateway_SONOFF_RF_Bridge_user_config.png diff --git a/img/OpenMQTTGateway_arduino_esp32_sketchbook_folder.png b/docs/img/OpenMQTTGateway_arduino_esp32_sketchbook_folder.png similarity index 100% rename from img/OpenMQTTGateway_arduino_esp32_sketchbook_folder.png rename to docs/img/OpenMQTTGateway_arduino_esp32_sketchbook_folder.png diff --git a/docs/img/OpenMQTTGateway_boards-removebg-preview.png b/docs/img/OpenMQTTGateway_boards-removebg-preview.png new file mode 100644 index 0000000..a59c03a Binary files /dev/null and b/docs/img/OpenMQTTGateway_boards-removebg-preview.png differ diff --git a/docs/img/OpenMQTTGateway_boards.png b/docs/img/OpenMQTTGateway_boards.png new file mode 100644 index 0000000..ad51fb4 Binary files /dev/null and b/docs/img/OpenMQTTGateway_boards.png differ diff --git a/docs/img/OpenMQTTGateway_boards_sonoff-removebg-preview.png b/docs/img/OpenMQTTGateway_boards_sonoff-removebg-preview.png new file mode 100644 index 0000000..d066ee1 Binary files /dev/null and b/docs/img/OpenMQTTGateway_boards_sonoff-removebg-preview.png differ diff --git a/docs/img/OpenMQTTGateway_boards_sonoff.png b/docs/img/OpenMQTTGateway_boards_sonoff.png new file mode 100644 index 0000000..a50e2ac Binary files /dev/null and b/docs/img/OpenMQTTGateway_boards_sonoff.png differ diff --git a/img/OpenMQTTGateway_breadboard.jpg b/docs/img/OpenMQTTGateway_breadboard.jpg similarity index 100% rename from img/OpenMQTTGateway_breadboard.jpg rename to docs/img/OpenMQTTGateway_breadboard.jpg diff --git a/docs/img/OpenMQTTGateway_controllers.png b/docs/img/OpenMQTTGateway_controllers.png new file mode 100644 index 0000000..1da58ca Binary files /dev/null and b/docs/img/OpenMQTTGateway_controllers.png differ diff --git a/docs/img/OpenMQTTGateway_devices_ble.png b/docs/img/OpenMQTTGateway_devices_ble.png new file mode 100644 index 0000000..77a5c59 Binary files /dev/null and b/docs/img/OpenMQTTGateway_devices_ble.png differ diff --git a/docs/img/OpenMQTTGateway_devices_rf1.png b/docs/img/OpenMQTTGateway_devices_rf1.png new file mode 100644 index 0000000..4666e0b Binary files /dev/null and b/docs/img/OpenMQTTGateway_devices_rf1.png differ diff --git a/docs/img/OpenMQTTGateway_devices_rf2.png b/docs/img/OpenMQTTGateway_devices_rf2.png new file mode 100644 index 0000000..4dae908 Binary files /dev/null and b/docs/img/OpenMQTTGateway_devices_rf2.png differ diff --git a/docs/img/OpenMQTTGateway_devices_rf3.png b/docs/img/OpenMQTTGateway_devices_rf3.png new file mode 100644 index 0000000..0e920db Binary files /dev/null and b/docs/img/OpenMQTTGateway_devices_rf3.png differ diff --git a/img/OpenMQTTGateway_multiple_install.png b/docs/img/OpenMQTTGateway_multiple_install.png similarity index 100% rename from img/OpenMQTTGateway_multiple_install.png rename to docs/img/OpenMQTTGateway_multiple_install.png diff --git a/img/OpenMQTTGateway_serial1.jpg b/docs/img/OpenMQTTGateway_serial1.jpg similarity index 100% rename from img/OpenMQTTGateway_serial1.jpg rename to docs/img/OpenMQTTGateway_serial1.jpg diff --git a/img/OpenMQTTGateway_serial2.jpg b/docs/img/OpenMQTTGateway_serial2.jpg similarity index 100% rename from img/OpenMQTTGateway_serial2.jpg rename to docs/img/OpenMQTTGateway_serial2.jpg diff --git a/img/OpenMQTTGateway_serial3.jpg b/docs/img/OpenMQTTGateway_serial3.jpg similarity index 100% rename from img/OpenMQTTGateway_serial3.jpg rename to docs/img/OpenMQTTGateway_serial3.jpg diff --git a/img/OpenMQTTGateway_serial_2G_1.jpg b/docs/img/OpenMQTTGateway_serial_2G_1.jpg similarity index 100% rename from img/OpenMQTTGateway_serial_2G_1.jpg rename to docs/img/OpenMQTTGateway_serial_2G_1.jpg diff --git a/img/OpenMQTTGateway_serial_2G_2.jpg b/docs/img/OpenMQTTGateway_serial_2G_2.jpg similarity index 100% rename from img/OpenMQTTGateway_serial_2G_2.jpg rename to docs/img/OpenMQTTGateway_serial_2G_2.jpg diff --git a/img/OpenMQTTgateway_Arduino_Addon_BT.fzz b/docs/img/OpenMQTTgateway_Arduino_Addon_BT.fzz similarity index 100% rename from img/OpenMQTTgateway_Arduino_Addon_BT.fzz rename to docs/img/OpenMQTTgateway_Arduino_Addon_BT.fzz diff --git a/img/OpenMQTTgateway_Arduino_Addon_BT.png b/docs/img/OpenMQTTgateway_Arduino_Addon_BT.png similarity index 100% rename from img/OpenMQTTgateway_Arduino_Addon_BT.png rename to docs/img/OpenMQTTgateway_Arduino_Addon_BT.png diff --git a/img/OpenMQTTgateway_Arduino_Addon_DHT.fzz b/docs/img/OpenMQTTgateway_Arduino_Addon_DHT.fzz similarity index 100% rename from img/OpenMQTTgateway_Arduino_Addon_DHT.fzz rename to docs/img/OpenMQTTgateway_Arduino_Addon_DHT.fzz diff --git a/img/OpenMQTTgateway_Arduino_Addon_DHT.png b/docs/img/OpenMQTTgateway_Arduino_Addon_DHT.png similarity index 100% rename from img/OpenMQTTgateway_Arduino_Addon_DHT.png rename to docs/img/OpenMQTTgateway_Arduino_Addon_DHT.png diff --git a/img/OpenMQTTgateway_Arduino_Addon_IR.fzz b/docs/img/OpenMQTTgateway_Arduino_Addon_IR.fzz similarity index 100% rename from img/OpenMQTTgateway_Arduino_Addon_IR.fzz rename to docs/img/OpenMQTTgateway_Arduino_Addon_IR.fzz diff --git a/img/OpenMQTTgateway_Arduino_Addon_IR.png b/docs/img/OpenMQTTgateway_Arduino_Addon_IR.png similarity index 100% rename from img/OpenMQTTgateway_Arduino_Addon_IR.png rename to docs/img/OpenMQTTgateway_Arduino_Addon_IR.png diff --git a/img/OpenMQTTgateway_Arduino_Addon_RF.fzz b/docs/img/OpenMQTTgateway_Arduino_Addon_RF.fzz similarity index 100% rename from img/OpenMQTTgateway_Arduino_Addon_RF.fzz rename to docs/img/OpenMQTTgateway_Arduino_Addon_RF.fzz diff --git a/img/OpenMQTTgateway_Arduino_Addon_RF.png b/docs/img/OpenMQTTgateway_Arduino_Addon_RF.png similarity index 100% rename from img/OpenMQTTgateway_Arduino_Addon_RF.png rename to docs/img/OpenMQTTgateway_Arduino_Addon_RF.png diff --git a/img/OpenMQTTgateway_Arduino_AllInOne_IR-RF-BT-DHT.fzz b/docs/img/OpenMQTTgateway_Arduino_AllInOne_IR-RF-BT-DHT.fzz similarity index 100% rename from img/OpenMQTTgateway_Arduino_AllInOne_IR-RF-BT-DHT.fzz rename to docs/img/OpenMQTTgateway_Arduino_AllInOne_IR-RF-BT-DHT.fzz diff --git a/img/OpenMQTTgateway_Arduino_AllInOne_IR-RF-BT-DHT.png b/docs/img/OpenMQTTgateway_Arduino_AllInOne_IR-RF-BT-DHT.png similarity index 100% rename from img/OpenMQTTgateway_Arduino_AllInOne_IR-RF-BT-DHT.png rename to docs/img/OpenMQTTgateway_Arduino_AllInOne_IR-RF-BT-DHT.png diff --git a/docs/img/OpenMQTTgateway_ESP32_Addon_IR.fzz b/docs/img/OpenMQTTgateway_ESP32_Addon_IR.fzz new file mode 100644 index 0000000..07159f6 Binary files /dev/null and b/docs/img/OpenMQTTgateway_ESP32_Addon_IR.fzz differ diff --git a/docs/img/OpenMQTTgateway_ESP32_Addon_IR.png b/docs/img/OpenMQTTgateway_ESP32_Addon_IR.png new file mode 100644 index 0000000..9d94465 Binary files /dev/null and b/docs/img/OpenMQTTgateway_ESP32_Addon_IR.png differ diff --git a/img/OpenMQTTgateway_ESP32_Addon_RF.fzz b/docs/img/OpenMQTTgateway_ESP32_Addon_RF.fzz similarity index 96% rename from img/OpenMQTTgateway_ESP32_Addon_RF.fzz rename to docs/img/OpenMQTTgateway_ESP32_Addon_RF.fzz index 5a83fa1..722e746 100644 Binary files a/img/OpenMQTTgateway_ESP32_Addon_RF.fzz and b/docs/img/OpenMQTTgateway_ESP32_Addon_RF.fzz differ diff --git a/img/OpenMQTTgateway_ESP32_Addon_RF.png b/docs/img/OpenMQTTgateway_ESP32_Addon_RF.png similarity index 100% rename from img/OpenMQTTgateway_ESP32_Addon_RF.png rename to docs/img/OpenMQTTgateway_ESP32_Addon_RF.png diff --git a/docs/img/OpenMQTTgateway_ESP32_binary_flash.png b/docs/img/OpenMQTTgateway_ESP32_binary_flash.png new file mode 100644 index 0000000..a3288a0 Binary files /dev/null and b/docs/img/OpenMQTTgateway_ESP32_binary_flash.png differ diff --git a/docs/img/OpenMQTTgateway_ESP32_binary_flash2.png b/docs/img/OpenMQTTgateway_ESP32_binary_flash2.png new file mode 100644 index 0000000..83ab713 Binary files /dev/null and b/docs/img/OpenMQTTgateway_ESP32_binary_flash2.png differ diff --git a/img/OpenMQTTgateway_ESP8266_Addon_2G.fzz b/docs/img/OpenMQTTgateway_ESP8266_Addon_2G.fzz similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_2G.fzz rename to docs/img/OpenMQTTgateway_ESP8266_Addon_2G.fzz diff --git a/img/OpenMQTTgateway_ESP8266_Addon_2G.png b/docs/img/OpenMQTTgateway_ESP8266_Addon_2G.png similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_2G.png rename to docs/img/OpenMQTTgateway_ESP8266_Addon_2G.png diff --git a/img/OpenMQTTgateway_ESP8266_Addon_BT.fzz b/docs/img/OpenMQTTgateway_ESP8266_Addon_BT.fzz similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_BT.fzz rename to docs/img/OpenMQTTgateway_ESP8266_Addon_BT.fzz diff --git a/img/OpenMQTTgateway_ESP8266_Addon_BT.png b/docs/img/OpenMQTTgateway_ESP8266_Addon_BT.png similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_BT.png rename to docs/img/OpenMQTTgateway_ESP8266_Addon_BT.png diff --git a/img/OpenMQTTgateway_ESP8266_Addon_DHT.fzz b/docs/img/OpenMQTTgateway_ESP8266_Addon_DHT.fzz similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_DHT.fzz rename to docs/img/OpenMQTTgateway_ESP8266_Addon_DHT.fzz diff --git a/img/OpenMQTTgateway_ESP8266_Addon_DHT.png b/docs/img/OpenMQTTgateway_ESP8266_Addon_DHT.png similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_DHT.png rename to docs/img/OpenMQTTgateway_ESP8266_Addon_DHT.png diff --git a/img/OpenMQTTgateway_ESP8266_Addon_I2C.fzz b/docs/img/OpenMQTTgateway_ESP8266_Addon_I2C.fzz similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_I2C.fzz rename to docs/img/OpenMQTTgateway_ESP8266_Addon_I2C.fzz diff --git a/img/OpenMQTTgateway_ESP8266_Addon_I2C.png b/docs/img/OpenMQTTgateway_ESP8266_Addon_I2C.png similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_I2C.png rename to docs/img/OpenMQTTgateway_ESP8266_Addon_I2C.png diff --git a/img/OpenMQTTgateway_ESP8266_Addon_IR.fzz b/docs/img/OpenMQTTgateway_ESP8266_Addon_IR.fzz similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_IR.fzz rename to docs/img/OpenMQTTgateway_ESP8266_Addon_IR.fzz diff --git a/img/OpenMQTTgateway_ESP8266_Addon_IR.png b/docs/img/OpenMQTTgateway_ESP8266_Addon_IR.png similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_IR.png rename to docs/img/OpenMQTTgateway_ESP8266_Addon_IR.png diff --git a/img/OpenMQTTgateway_ESP8266_Addon_RF.fzz b/docs/img/OpenMQTTgateway_ESP8266_Addon_RF.fzz similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_RF.fzz rename to docs/img/OpenMQTTgateway_ESP8266_Addon_RF.fzz diff --git a/img/OpenMQTTgateway_ESP8266_Addon_RF.png b/docs/img/OpenMQTTgateway_ESP8266_Addon_RF.png similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_RF.png rename to docs/img/OpenMQTTgateway_ESP8266_Addon_RF.png diff --git a/img/OpenMQTTgateway_ESP8266_Addon_RFM69.fzz b/docs/img/OpenMQTTgateway_ESP8266_Addon_RFM69.fzz similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_RFM69.fzz rename to docs/img/OpenMQTTgateway_ESP8266_Addon_RFM69.fzz diff --git a/img/OpenMQTTgateway_ESP8266_Addon_RFM69.png b/docs/img/OpenMQTTgateway_ESP8266_Addon_RFM69.png similarity index 100% rename from img/OpenMQTTgateway_ESP8266_Addon_RFM69.png rename to docs/img/OpenMQTTgateway_ESP8266_Addon_RFM69.png diff --git a/img/OpenMQTTgateway_ESP8285_Addon_IR.fzz b/docs/img/OpenMQTTgateway_ESP8285_Addon_IR.fzz similarity index 100% rename from img/OpenMQTTgateway_ESP8285_Addon_IR.fzz rename to docs/img/OpenMQTTgateway_ESP8285_Addon_IR.fzz diff --git a/img/OpenMQTTgateway_ESP8285_Addon_IR.png b/docs/img/OpenMQTTgateway_ESP8285_Addon_IR.png similarity index 100% rename from img/OpenMQTTgateway_ESP8285_Addon_IR.png rename to docs/img/OpenMQTTgateway_ESP8285_Addon_IR.png diff --git a/docs/img/OpenMQTTgateway_NodeMCU_PyFlasher.png b/docs/img/OpenMQTTgateway_NodeMCU_PyFlasher.png new file mode 100644 index 0000000..9029c36 Binary files /dev/null and b/docs/img/OpenMQTTgateway_NodeMCU_PyFlasher.png differ diff --git a/img/OpenMQTTgateway_SONOFF_RFBRIDGE_Upload_Parameters.png b/docs/img/OpenMQTTgateway_SONOFF_RFBRIDGE_Upload_Parameters.png similarity index 100% rename from img/OpenMQTTgateway_SONOFF_RFBRIDGE_Upload_Parameters.png rename to docs/img/OpenMQTTgateway_SONOFF_RFBRIDGE_Upload_Parameters.png diff --git a/img/OpenMQTTgateway_SONOFF_RFBRIDGE_results.png b/docs/img/OpenMQTTgateway_SONOFF_RFBRIDGE_results.png similarity index 100% rename from img/OpenMQTTgateway_SONOFF_RFBRIDGE_results.png rename to docs/img/OpenMQTTgateway_SONOFF_RFBRIDGE_results.png diff --git a/img/OpenMQTTgateway_miflora_results.png b/docs/img/OpenMQTTgateway_miflora_results.png similarity index 100% rename from img/OpenMQTTgateway_miflora_results.png rename to docs/img/OpenMQTTgateway_miflora_results.png diff --git a/img/Openmqttgateway_logo.png b/docs/img/Openmqttgateway_logo.png similarity index 100% rename from img/Openmqttgateway_logo.png rename to docs/img/Openmqttgateway_logo.png diff --git a/img/Openmqttgateway_logo_micro.png b/docs/img/Openmqttgateway_logo_micro.png similarity index 100% rename from img/Openmqttgateway_logo_micro.png rename to docs/img/Openmqttgateway_logo_micro.png diff --git a/img/Openmqttgateway_logo_mini.png b/docs/img/Openmqttgateway_logo_mini.png similarity index 100% rename from img/Openmqttgateway_logo_mini.png rename to docs/img/Openmqttgateway_logo_mini.png diff --git a/img/Openmqttgateway_logo_mini_512.png b/docs/img/Openmqttgateway_logo_mini_512.png similarity index 100% rename from img/Openmqttgateway_logo_mini_512.png rename to docs/img/Openmqttgateway_logo_mini_512.png diff --git a/img/Wiki_module_BT.png b/docs/img/Wiki_module_BT.png similarity index 100% rename from img/Wiki_module_BT.png rename to docs/img/Wiki_module_BT.png diff --git a/img/Wiki_module_DHT.png b/docs/img/Wiki_module_DHT.png similarity index 100% rename from img/Wiki_module_DHT.png rename to docs/img/Wiki_module_DHT.png diff --git a/img/Wiki_module_I2C.png b/docs/img/Wiki_module_I2C.png similarity index 100% rename from img/Wiki_module_I2C.png rename to docs/img/Wiki_module_I2C.png diff --git a/img/Wiki_module_IR.png b/docs/img/Wiki_module_IR.png similarity index 100% rename from img/Wiki_module_IR.png rename to docs/img/Wiki_module_IR.png diff --git a/img/Wiki_module_RF.png b/docs/img/Wiki_module_RF.png similarity index 100% rename from img/Wiki_module_RF.png rename to docs/img/Wiki_module_RF.png diff --git a/img/Wiki_module_RFM69.png b/docs/img/Wiki_module_RFM69.png similarity index 100% rename from img/Wiki_module_RFM69.png rename to docs/img/Wiki_module_RFM69.png diff --git a/img/arduino-esp32-sketchbook.png b/docs/img/arduino-esp32-sketchbook.png similarity index 100% rename from img/arduino-esp32-sketchbook.png rename to docs/img/arduino-esp32-sketchbook.png diff --git a/docs/img/domoticz-logo.jpg b/docs/img/domoticz-logo.jpg new file mode 100644 index 0000000..1607411 Binary files /dev/null and b/docs/img/domoticz-logo.jpg differ diff --git a/docs/img/fhem_logo.png b/docs/img/fhem_logo.png new file mode 100644 index 0000000..e9ba39d Binary files /dev/null and b/docs/img/fhem_logo.png differ diff --git a/docs/img/home-assistant-logo.png b/docs/img/home-assistant-logo.png new file mode 100644 index 0000000..ba31199 Binary files /dev/null and b/docs/img/home-assistant-logo.png differ diff --git a/docs/img/jeedom-logo.png b/docs/img/jeedom-logo.png new file mode 100644 index 0000000..dcb9720 Binary files /dev/null and b/docs/img/jeedom-logo.png differ diff --git a/docs/img/node-red-logo.png b/docs/img/node-red-logo.png new file mode 100644 index 0000000..898c242 Binary files /dev/null and b/docs/img/node-red-logo.png differ diff --git a/docs/img/openhab-logo.png b/docs/img/openhab-logo.png new file mode 100644 index 0000000..cd63463 Binary files /dev/null and b/docs/img/openhab-logo.png differ diff --git a/docs/integrate/home_assistant.md b/docs/integrate/home_assistant.md new file mode 100644 index 0000000..4896e0a --- /dev/null +++ b/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: +``` \ No newline at end of file diff --git a/docs/integrate/node_red.md b/docs/integrate/node_red.md new file mode 100644 index 0000000..21c4197 --- /dev/null +++ b/docs/integrate/node_red.md @@ -0,0 +1,246 @@ +# Integrate Node Red +Here is a simple set of flows for integrating OpenMQTTGateway with NodeRED via an ESP8266 module. + +In this example I have used a Wemos D1 Mini with some cheap RF modules. + +![](https://i.imgur.com/z2RFvUw.jpg) + +A flow to receive 433MHz signals into NodeRED (you will need to update the IP address of your broker) + +![](https://i.imgur.com/2UWYzHg.jpg) + +```json +[ + { + "id": "6d1b2915.7ce798", + "type": "mqtt in", + "z": "a9a9b76b.e69998", + "name": "433MQTT", + "topic": "home/OpenMQTTGateway/433toMQTT", + "qos": "2", + "broker": "4572f098.cc1", + "x": 80, + "y": 740, + "wires": [ + [ + "fe53b819.4f9568" + ] + ] + }, + { + "id": "fe53b819.4f9568", + "type": "debug", + "z": "a9a9b76b.e69998", + "name": "", + "active": true, + "tosidebar": true, + "console": false, + "tostatus": false, + "complete": "payload", + "x": 290, + "y": 740, + "wires": [] + }, + { + "id": "4572f098.cc1", + "type": "mqtt-broker", + "z": "", + "name": "", + "broker": "192.168.0.56", + "port": "1883", + "clientid": "", + "usetls": false, + "compatmode": true, + "keepalive": "60", + "cleansession": true, + "willTopic": "", + "willQos": "0", + "willRetain": "false", + "willPayload": "", + "birthTopic": "", + "birthQos": "0", + "birthRetain": "false", + "birthPayload": "" + } +] +``` + +A flow to send 433MHz signals from NodeRED + +![](https://i.imgur.com/PMlWyii.jpg) + +```json +[ + { + "id": "ff924d56.459d6", + "type": "mqtt out", + "z": "a9a9b76b.e69998", + "name": "MQTTto433", + "topic": "home/OpenMQTTGateway/commands/MQTTto433", + "qos": "", + "retain": "", + "broker": "4572f098.cc1", + "x": 610, + "y": 860, + "wires": [] + }, + { + "id": "6c25a2d4.6c733c", + "type": "inject", + "z": "a9a9b76b.e69998", + "name": "", + "topic": "", + "payload": "On", + "payloadType": "str", + "repeat": "", + "crontab": "", + "once": false, + "onceDelay": 0.1, + "x": 90, + "y": 840, + "wires": [ + [ + "7689fe88.45679" + ] + ] + }, + { + "id": "a76d2f03.5f3", + "type": "change", + "z": "a9a9b76b.e69998", + "name": "", + "rules": [ + { + "t": "set", + "p": "payload", + "pt": "msg", + "to": "5510487", + "tot": "str" + } + ], + "action": "", + "property": "", + "from": "", + "to": "", + "reg": false, + "x": 380, + "y": 840, + "wires": [ + [ + "ff924d56.459d6" + ] + ] + }, + { + "id": "7689fe88.45679", + "type": "switch", + "z": "a9a9b76b.e69998", + "name": "", + "property": "payload", + "propertyType": "msg", + "rules": [ + { + "t": "eq", + "v": "On", + "vt": "str" + }, + { + "t": "eq", + "v": "Off", + "vt": "str" + } + ], + "checkall": "true", + "repair": false, + "outputs": 2, + "x": 210, + "y": 860, + "wires": [ + [ + "a76d2f03.5f3" + ], + [ + "6a7c2c3a.567794" + ] + ] + }, + { + "id": "7e52ec9.00dde14", + "type": "inject", + "z": "a9a9b76b.e69998", + "name": "", + "topic": "", + "payload": "Off", + "payloadType": "str", + "repeat": "", + "crontab": "", + "once": false, + "onceDelay": 0.1, + "x": 90, + "y": 880, + "wires": [ + [ + "7689fe88.45679" + ] + ] + }, + { + "id": "6a7c2c3a.567794", + "type": "change", + "z": "a9a9b76b.e69998", + "name": "", + "rules": [ + { + "t": "set", + "p": "payload", + "pt": "msg", + "to": "4527444", + "tot": "str" + } + ], + "action": "", + "property": "", + "from": "", + "to": "", + "reg": false, + "x": 380, + "y": 880, + "wires": [ + [ + "ff924d56.459d6" + ] + ] + }, + { + "id": "20991aea.cca8a6", + "type": "comment", + "z": "a9a9b76b.e69998", + "name": "Set you RF codes here.", + "info": "", + "x": 380, + "y": 800, + "wires": [] + }, + { + "id": "4572f098.cc1", + "type": "mqtt-broker", + "z": "", + "name": "", + "broker": "192.168.0.56", + "port": "1883", + "clientid": "", + "usetls": false, + "compatmode": true, + "keepalive": "60", + "cleansession": true, + "willTopic": "", + "willQos": "0", + "willRetain": "false", + "willPayload": "", + "birthTopic": "", + "birthQos": "0", + "birthRetain": "false", + "birthPayload": "" + } +] +``` diff --git a/docs/integrate/openhab2.md b/docs/integrate/openhab2.md new file mode 100644 index 0000000..6f15266 --- /dev/null +++ b/docs/integrate/openhab2.md @@ -0,0 +1,103 @@ +# Integrate OPENHAB2 + +## MQTT 2 manual setup >=Openhab2.4 +You should have a mqtt broker installed (either mosquitto or the OpenHAB2 embedded one) + +In paper UI +* In bindings add the MQTT Things binding +* Inbox > MQTT Things binding > Add manualy >MQTT Broker : configure your borker +* Inbox > MQTT Things binding > Add manualy >Generic MQTT Thing : select your previously configured broker as a bridge and enter your thing definition (example RF plug, weather station, PIR sensor) +* Configuration > Things > "Your thing" : click on + and add one channel for each thing parameter (example for a weather station, you will have one channel for the temperature, one channel for the humidity etc..) +* For a state channel define the MQTT topic like this: + +## For a mi flora or mi jia temperature : + +`home/+/BTtoMQTT/C47C9999D1B8` + +* Click on show more + +* And add in "Incoming values transformation" + +`JSONPATH:$.tem` + +* Click on Save + +* Repeat for each channels and each things +* Configuration > Things > "Your thing" : click on a channel and add 1 or several items per channel defining what you want to display in the sitemap +or +* Define your items in an item file like this by refering to your mqtt things channels: +For a mi flora and mi jia + +```java +// MI JIA +Number humidity "Humidité air[%.1f %%]" {channel="mqtt:topic:dc2222e6:humidite-mijia"} +Number temperature "Température[%.1f °C]" {channel="mqtt:topic:dc2222e6:temperature-mijia"} +Number battery "Batterie capteur[%.1f %]" {channel="mqtt:topic:dc2222e6:batterie-mijia"} + +// MI FLORA +Number humidity_P "Hygrométrie plante[%.1f %%]" {channel="mqtt:topic:1fb33334:humidite-miflora"} +Number temperature_P "Température plante[%.1f °C]" {channel="mqtt:topic:1fb33334:temperature-miflora"} +Number fertility_P "Fertilité plante[%.1f uS/cm]" {channel="mqtt:topic:1fb33334:fertilite-miflora"} +Number lux_P "Luminiosité plante[%.1f lux]" {channel="mqtt:topic:1fb33334:lux-miflora"} +``` +## For a switch channel, add a channel by choosing the type "On/Off switch" + + define the MQTT state topic like this: +`home/+/433toMQTT` + +* Click on show more + +* add in "Incoming values transformation" +`JSONPATH:$.value` + +* define the command topic like this: +`home/+/commands/MQTTto433` + +* add the value corresponding to ON state and to OFF state +1312081 +1312084 + +* Click on Save + +* Repeat for each channels and each things + +* Configuration > Things > "Your thing" : click on a channel and add 1 or several switch per channel +or +* Define your items in an item file like this by refering to your mqtt thing channel: + +`Switch OMGSwitch "Prise 1" {channel="mqtt:topic:08998877:Power1"}` + + +# Presence detection (from @rickitaly) + +in thing file: + +```java +Thing mqtt:topic:omgentrance (mqtt:broker:localBroker) { +Channels: + Type string : blepresence "People Presence" [ stateTopic="home/home_presence/OpenMQTTGatewayEntrance"] +} +``` + +in item file + +```java +String OMG_BLE_Entrance "BLE Entrance Detector" { channel="mqtt:topic:omgentrance:blepresence" } +Switch Presence_Keys_Rick "Rick's Keys" (People, gKeys) {expire="240s,OFF"} +``` + +In rule file: + +```java +rule "BLE Presence Detector" +when +Item OMG_BLE_Entrance received update +then +val String msg = (OMG_BLE_Entrance.state as StringType).toString +val String id = transform("JSONPATH", "$.id", msg).toString +if(id == "xx:xx:xx:xx:xx:xx") + Presence_Keys_Rick.postUpdate(ON) +end +``` + + diff --git a/docs/prerequisites/board.md b/docs/prerequisites/board.md new file mode 100644 index 0000000..bdb8fc6 --- /dev/null +++ b/docs/prerequisites/board.md @@ -0,0 +1,37 @@ +# Board +OpenMQTTGateway is not closed to one board or type of board, by using the power of the Arduino framework and libraries that are cross compatibles it let you many choice of hardware, from an Arduino UNO to an ESP32. + +You can take a look to the components sheet to have a view of [supported boards and components](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277) + +Moreover it supports also sensors; DHT, HC SR501, ADC, I2C bus, INA226, TSL2561 +Or can actutate things (LED chipsets, relays). + +Here is some information to find the board suitable for your need, you have the choice between wifi, ethernet and off the shelves devices: + +Off the shelves wifi +* SONOFF RF Bridge +* Sonoff RFR3 +* Sonoff Basic +* Wifi RF Gateway + +![boards](../img/OpenMQTTGateway_boards_sonoff.png) + +Wifi/Ethernet: +* ESP8266 +* ESP32 +* Arduino Mega with an ethernet shield +* Arduino Uno with an ethernet shield + +![boards](../img/OpenMQTTGateway_boards.png) + +Arduino + ethernet shields enables faster responsiveness of the gateway and a reliable connection. + +The ESP platform is more flexible in term of installation (no need of an ethernet cable) but is less reliable in term of communication. Thanks to its higher memory and processing power it has more modules or possibilities compared to arduino Uno & Mega. + +Choosing your board depends heavily on the technologies you want to use with it. +To have a good overview of the compatibilities per board you can refer to [this sheet](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1098440301). + +The choice between these boards will depend on your knowledge and your requirements in terms of reliability, situation, modules wanted and devices you already have. + + + diff --git a/docs/prerequisites/broker.md b/docs/prerequisites/broker.md new file mode 100644 index 0000000..81739af --- /dev/null +++ b/docs/prerequisites/broker.md @@ -0,0 +1,20 @@ +# Broker +The broker will act as an intermediary between OpenMQTTGateway and your [controller](/prerequisites/controller), it can be seen as a centralized hub at the heart of your automation system. It carry on messages following a publish / subscribe mechanism. + +All the events or commands could pass by the broker. + +There is many choice of brokers, here is some of the most populars: +* [Mosquitto](https://mosquitto.org/) (Open source) +* [Moquette](https://moquette-io.github.io/moquette/) (Open source) +* [HiveMQ](https://www.hivemq.com/hivemq/features/) +* Embedded MQTT brokers (Home Assistant and OpenHAB) + +This [wikipedia list](https://en.wikipedia.org/wiki/Comparison_of_MQTT_implementations) gives you more details about the different choices you have. +This [github list](https://github.com/mqtt/mqtt.github.io/wiki/libraries) seems to be the most exhaustive ones. +Here is also some [idea of criterias](https://www.hivemq.com/blog/top-10-mqtt-broker-criteria/) from HiveMQ. + +Once your broker installed it can be interesting to see the traffic passing to it and to publish data, so as to do that there is several tools available: +* [MQTT Explorer](http://mqtt-explorer.com/) +* [HIVE MQ Web client](https://github.com/hivemq/hivemq-mqtt-web-client) +* [MQTT FX](https://mqttfx.jensd.de/) + diff --git a/docs/prerequisites/controller.md b/docs/prerequisites/controller.md new file mode 100644 index 0000000..edbaf03 --- /dev/null +++ b/docs/prerequisites/controller.md @@ -0,0 +1,15 @@ +# Controller +MQTT enables you to connect easily a controller so as to monitor, control and automate scenarios. + +The following controllers (and many other software) are compatible with MQTT: + +![controllers](../img/OpenMQTTGateway_controllers.png) + +OpenMQTTGateway is independant from these projets, you have the liberty of choice among all the compatibles software. + +* [OpenHAB2](https://www.openhab.org) +* [Home Assistant](https://www.home-assistant.io) +* [Domoticz](https://www.domoticz.com) +* [Jeedom](https://www.jeedom.com) +* [Node Red](https://nodered.org) +* [FHEM](https://fhem.de) \ No newline at end of file diff --git a/docs/prerequisites/devices.md b/docs/prerequisites/devices.md new file mode 100644 index 0000000..1fa97e3 --- /dev/null +++ b/docs/prerequisites/devices.md @@ -0,0 +1,22 @@ +# Devices +A list of verified compatible devices is maintained [here](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit?usp=sharing). + +Added to that is an overview of devices supported by OpenMQTTGateway: +* For radio frequency devices OpenMQTTGateway can support a wide range of 433mhz/315mhz devices, all the ones with SC5262 / SC5272, HX2262 / HX2272, PT2262 / PT2272, EV1527, RT1527, FP1527, HS1527 chipset are supported by the RF gateway. Added to that RF2 support Kaku and Pilight an [huge list](https://wiki.pilight.org/devices). Note that for the moment RF, RF2 and Pilight can not be activated on the same boards together. + +![boards](../img/OpenMQTTGateway_devices_rf1.png ':size=250%') +![boards](../img/OpenMQTTGateway_devices_rf2.png ':size=250%') +![boards](../img/OpenMQTTGateway_devices_rf3.png ':size=250%') + +* For BLE devices OpenMQTTGateway is able to scan all the BLE devices that advertise their data so as to do presence detection. Added to that it reads values coming from : +** Mi Flora (temperature/moisture/luminance/fertility) +** Mi Jia (temperature/humidity) +** Clear Grass (temperature/humidity) +** LYWDS02 Clock (temperature/humidity) +** Mi Scale (weight) + +![boards](../img/OpenMQTTGateway_devices_ble.png ':size=250%') + +* For infrared IR devices the list of supported brand is [here](https://github.com/1technophile/OpenMQTTGateway/blob/d2dd6138558909b71cc44f69665340247bd5f356/main/config_IR.h#L52), as there is also the possibility of using raw and global caché sending the possibilities of this gateway is huge! + +* LORA is more dedicated at this moment for tinkering and DIY and there is no Off the shelves devices compatible to my knowledge with this gateway. diff --git a/docs/setitup/actuators.md b/docs/setitup/actuators.md new file mode 100644 index 0000000..7fdfa25 --- /dev/null +++ b/docs/setitup/actuators.md @@ -0,0 +1,17 @@ +# Actuators +## Compatible parts +|Module|Purpose|Where to Buy| +|-|-|-| +|LED|Basic led|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|FASTLED|RGB Leds management|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|BUZZER|-|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|RELAY|Switch power circuit|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| + +## Pinout +|Module| Boards| +|-|-| +|RELAY|all output compatible pins| +|FASTLED|all output compatible pins| + +Vcc pin of the board and the Module to a 5V supply source +Ground pins of the board and the Module to the ground of the supply source. diff --git a/docs/setitup/ble.md b/docs/setitup/ble.md new file mode 100644 index 0000000..146d93b --- /dev/null +++ b/docs/setitup/ble.md @@ -0,0 +1,27 @@ +# BLE gateway +## Compatible parts +The ESP32 has an integrated BLE module, with this board the BLE gateway don't need any additional hardware. Making it the **advised board for BLE**. + +For Arduino and ESP8266 you can use an HM10 or HM11 below. +|Module|Purpose|Where to Buy| +|-|-|-| +|HM 10 Keyes bluetooth module|Bluetooth|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| + +## Pinout +|Module Pin|Board RX Pin|Board TX Pin| +|-|:-:|:-:| +|Arduino|D6 to HM10 TX|D5 to HM10 RX| +|ESP8266|D6 to HM10 TX|D7 to HM10 RX| + +Vcc pin of the board and the HM10 Module to a 5V supply source. +Ground pins of the board and the HM10 Module to the ground of the supply source. +The HM10/11 firmware version must be >= v601. +The baud rate of the HM10/11 module must be set to 9600 bauds. + +## Arduino Hardware setup +![BLE Arduino](../img/OpenMQTTgateway_Arduino_Addon_BT.png) + +## ESP8266 Hardware setup +![BLE ESP8266](../img/OpenMQTTgateway_ESP8266_Addon_BT.png) + + diff --git a/docs/setitup/gsm.md b/docs/setitup/gsm.md new file mode 100644 index 0000000..f8186c0 --- /dev/null +++ b/docs/setitup/gsm.md @@ -0,0 +1,24 @@ +# GSM 2G gateway +## Compatible parts + +|Module|Purpose|Where to Buy| +|-|-|-| +|A6|GSM GPRS module|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|A7|GSM GPRS module with GPS|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| + +## Hardware setup + +|Module Pin|NodeMCU / ESP8266 Pin| +|-|:-:| +|H_RXD|D6| +|H_TXD|D7| +|GND|GND| +|VCC5|MOSFET driven by D5| + +For VCC5 you can power it directly all the time with an USB cable or use a MOSFET like [here](https://gitlab.com/stavros/A6-ESP8266-breakout/raw/master/images/schematic.png) + +Don't use the nodemcu/wemos 5V pin for the A6/7 power, use a dedicated power supply for both or dedicated to the A6/7 with at least 2 amps ability. + +So as to start your A6/7 module press the red button for 4 seconds, or link the PWR_KEY pin to VCC5.0 for the same time. + +![Addon_2G](../img/OpenMQTTgateway_ESP8266_Addon_2G.png) diff --git a/docs/setitup/ir.md b/docs/setitup/ir.md new file mode 100644 index 0000000..5670029 --- /dev/null +++ b/docs/setitup/ir.md @@ -0,0 +1,29 @@ +# IR gateway +## Compatible parts +|Module|Purpose|Where to Buy| +|-|-|-| +|IR diode|Emitting|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|IR receiver|Receiving|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|transistor 2N2222|Amplify uC signal for the IR diode|-| +|330 ohms resistor|-|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|220 ohms resistor|limit current to LED|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| + +The IR setup can work with bc547 and a 4x3 LED-Matrix. + +## Pinout +|Board| Receiver Pin| Emitter Pin| +|-|:-:|:-:| +|Arduino UNO|D2|D9| +|ESP8266|D4|D0| +|ESP32|27/**26**|14| + +Connect the Emitter and Receiver to a 5V supply source, and the ground of your supply source to the ground of your board. + +## Arduino Hardware setup +![IR](../img/OpenMQTTgateway_Arduino_Addon_IR.png) + +## ESP8266 Hardware setup +![IR](../img/OpenMQTTgateway_ESP8266_Addon_IR.png) + +## ESP32 Hardware setup +![IR](../img/OpenMQTTgateway_ESP32_Addon_IR.png) diff --git a/docs/setitup/lora.md b/docs/setitup/lora.md new file mode 100644 index 0000000..1308272 --- /dev/null +++ b/docs/setitup/lora.md @@ -0,0 +1,6 @@ +# LORA gateway +## Compatible parts +An ESP32 board with a LORA module. +Idealy a TTGO board with LORA module included see [compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277) + +With this kind of board there is no hadware modification needed. diff --git a/docs/setitup/rf.md b/docs/setitup/rf.md new file mode 100644 index 0000000..d0edc1b --- /dev/null +++ b/docs/setitup/rf.md @@ -0,0 +1,44 @@ +# RF gateway (433mhz/315mhz) +## Compatible parts +|Module|Purpose|Where to Buy| +|-|-|-| +|SRX882 (recommended)|433Mhz Receiver|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|STX882 (recommended)|433Mhz Transmitter|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|XD RF 5V|433Mhz Receiver|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|FS1000A|433Mhz Transmitter|[compatible parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| + +## Pinout +|Board| Receiver Pin| Emitter Pin| +|-|:-:|:-:| +|Arduino UNO|D3|D4| +|ESP8266|D2/**D3**/D1/D8|**RX**/D2| +|ESP32|**27**/26|12| +|RF BRIDGE|-|-| +|RF BRIDGE [DIRECT HACK](https://github.com/xoseperez/espurna/wiki/Hardware-Itead-Sonoff-RF-Bridge---Direct-Hack)|4|5| +|SONOFF RFR3|4|-| +|RF WIFI GATEWAY|5|-| + +Connect the Emitter and Receiver to a 5V supply source, and the ground of your supply source to the ground of your board. + +## Arduino Hardware setup +![RF](../img/OpenMQTTgateway_Arduino_Addon_RF.png) + +## ESP8266 Hardware setup +If the gateway works only when serial monitor is connected don't use D3 use D2 instead (gpio 4) and modify config_RF.h accordingly. + +With SRX882 some users reported that D3 is not working use D1 instead in this case and modify config_RF.h accordingly. + +![Addon_RF](../img/OpenMQTTgateway_ESP8266_Addon_RF.png) + +## ESP32 Hardware setup +![Addon_RF](../img/OpenMQTTgateway_ESP32_Addon_RF.png) + +## SONOFF RF Bridge Hardware setup +Per default there is no need on modifying the RF Bridge hardware, unless you don't want to use the provided RF controller (EFM8BB1). Indeed if you want to extend the protocols supported by the bridge you can [bypass this controller](https://github.com/xoseperez/espurna/wiki/Hardware-Itead-Sonoff-RF-Bridge---Direct-Hack) and use the ESP8255 capacities to decode RF Signal. +The RF processing can be achieved after the modification by either RF, RF2 or Pilight gateways. + +## SONOFF RFR3 Hardware setup +[Connect GPIO4 of the ESP8255 to the pin D0 of SYN470](https://1technophile.blogspot.com/2019/08/new-sonoff-rfr3-as-433tomqtt-gateway.html) + +## WIFI RF GATEWAY Hardware setup +This board doesn't require any hardware modifications. diff --git a/docs/setitup/sensors.md b/docs/setitup/sensors.md new file mode 100644 index 0000000..f7d394c --- /dev/null +++ b/docs/setitup/sensors.md @@ -0,0 +1,31 @@ +# Sensors +## Compatible sensors +|Module|Purpose|Where to Buy| +|-|-|-| +|DHT11|Temperature and Humidity|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|DHT22|Temperature and Humidity|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|HCSR501|PIR|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|BH1750|Digital light|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|BME280|Temperature, Humidity and pressure|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|GPIO Input|Inputs|-| +|GPIO KeyCode|Keycode|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|INA226|Current and voltage|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| +|TSL2561|Luminiosity|[parts list](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1323184277)| + +## Pinout +|Module|Arduino Pin| ESP8266 Pin|ESP32 Pin| +|-|-|-|-| +|DHT11/22|D8|D1|16| +|HC-SR501/HC-SR505|7|D5|5| +|Analog reading|A0|A0|A0| +|BH1750 SDA|A4|D2|21| +|BH1750 SCL|A5|D1|22| +|BME280 SDA|A4|D2|21| +|BME280 SCL|A5|D1|22| +|INA226 SDA|A4|D2|21| +|INA226 SCL|A5|D1|22| +|TSL2561 SDA|A4|D2|21| +|TSL2561 SCL|A5|D1|22| + +Vcc pin of the board and the Module to a 5V supply source +Ground pins of the board and the Module to the ground of the supply source. diff --git a/docs/upload/binaries.md b/docs/upload/binaries.md new file mode 100644 index 0000000..5ff03ed --- /dev/null +++ b/docs/upload/binaries.md @@ -0,0 +1,51 @@ +# Upload Binaries +This section is usefull if you want to directly flash your ESP from your desktop. Once flashed you can change wifi and broker settings. +Nevertheless you will not be able to change advanced parameters, if you want to do so refer to [Upload from PlatformIO][pio] section. + +Download the binary corresponding to your board and gateway [here](https://github.com/1technophile/OpenMQTTGateway/releases) from github and uncompress it. + +## ESP32 +* Download the flash tool utility from espressif: +https://www.espressif.com/en/products/hardware/esp32/resources +* Uncompress the package +* Execute `flash_download_tools` +* Choose ESP32 DownloadTool +* Set the files and the adress as below: +![Flash download tool](../img/OpenMQTTgateway_ESP32_binary_flash.png) +And set the parameters used by arduino IDE, we are able to upload to ESP32 a binary file containing OpenMQTTGateway. +* Set the config as above +* Connect your ESP32 board and select the COM port +* Click on start +The upload details appears in the rear shell windows, you can see also the progress bar changing +* Once done the flash tool display "FINISH" like below +![Flash download tool 2](../img/OpenMQTTgateway_ESP32_binary_flash2.png) + +## ESP8266 +* Download the NodeMCU Py Flasher tool : +https://github.com/marcelstoer/nodemcu-pyflasher/releases +* Execute `NodeMCU-PyFlasher` +* Set the files and parameters as below: +![](../img/OpenMQTTgateway_NodeMCU_PyFlasher.png) +* Connect your board and select the COM port +* Click on *FlashNodeMCU* +The upload details appears. + +Note that to reset the wifi and mqtt settings you can check *yes, wipes all data* + +Once loaded into your board you have to set your network parameters with wifi manager portal +From your smartphone search for your OpenMQTTGateway wifi network and connect to it, a web page will appear +* Select your wifi +* Set your wifi password +* Set your MQTT Server IP +* Set your MQTT Server username (not compulsory) +* Set your MQTT Server password (not compulsory) + +The ESP restart and connect to your network. Note that your credentials are saved into the ESP memory, if you want to redo the configuration you have to erase the ESP memory with the flash download tool. + +_The default password for wifi manager is "your_password"_ + +Once done the gateway should connect to your network and your broker, you should see it into the broker in the form of the following messages: +``` +home/OpenMQTTGateway/LWT Online +home/OpenMQTTGateway/version +``` diff --git a/docs/upload/pio.md b/docs/upload/pio.md new file mode 100644 index 0000000..6b05368 --- /dev/null +++ b/docs/upload/pio.md @@ -0,0 +1,113 @@ +# Upload with PlatformIO +This section is usefull if you want to do advanced configuration of your project or if you choose an Arduino. Indeed the ESP family can be loaded directly without any configuration from your desktop. +Advanced configurations means changing the default used pins, the MQTT subjects and all the expert parameters that you can find in [user_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h) and in all [config_XX.h](https://github.com/1technophile/OpenMQTTGateway/tree/development/main). +If you don't have to change the default parameters except wifi and broker setting you can go directly to the [Load](load) section. + +Download the [CODE](https://github.com/1technophile/OpenMQTTGateway/releases) from github. + +So as to configure OpenMQTTGateway you have the choice between 2 development environments: +* [Arduino IDE](https://www.arduino.cc/en/Main/Software) +* [PlatformIO](https://platformio.org/) + +I advise to use PlatformIO, this way you will not have to search for all the necessary libraries and adequate forks/revisions. If you really want to use Arduino you need to download the libraries listed [here](https://github.com/1technophile/OpenMQTTGateway/blob/d2dd6138558909b71cc44f69665340247bd5f356/platformio.ini#L55) at the version or revision specified. + +With PlatformIO +* Open the folder named "OpenMQTTGateway" +* Open the platformio.ini file and uncomment the default_envs line corresponding to your board and choosen module like below. + +``` ini +;default_envs = sonoff-basic-rfr3 +;default_envs = rfbridge +;default_envs = esp32dev-all +default_envs = esp32dev-rf +;default_envs = esp32dev-ir +;default_envs = esp32dev-ble +;default_envs = ttgo-lora32-v1 +``` + +If you don't know which env to activate you can refer to [devices](prerequisites/devices). + +The different listed configurations represents some standard environments, to overload them with special parameters or modules you can modify the config files. The definitions coming from [platformio.ini](https://github.com/1technophile/OpenMQTTGateway/blob/development/platformio.ini) file and config files are cumulative. +The main config file is [user_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h), added to it you have one config file per gateway, sensor or actuator, you will find them in the [main](https://github.com/1technophile/OpenMQTTGateway/tree/development/main) folder. + +If you want to add more sensors or gateways to one `default_envs` you can uncomment them into [user_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/d2dd6138558909b71cc44f69665340247bd5f356/main/User_config.h#L84) or add the modules directly into your environment definition of your .ini files. + +Example to add IR to `esp32dev-rf` add the `build_flags` below to the env definition: +``` ini + '-DZgatewayIR="IR"' +``` + +``` ini +[env:esp32dev-rf] +platform = ${com.esp32_platform} +board = esp32dev +lib_deps = + ${com-esp.lib_deps} + ${libraries.rc-switch} +build_flags = + ${com-esp.build_flags} + '-DZgatewayRF="RF"' + '-DZgatewayIR="IR"' + '-DGateway_Name="OpenMQTTGateway_ESP32_RF_IR"' +``` + +You can define your environment into an additionnal `production_env.ini` file than `platformio.ini`, when building PIO will scan for all the +``` ini +*_env.ini +``` +This way when updating the code your environments definition will not be overwritten. + +Once your configuration is done you can upload the program to your board by clicking on the white arrow at the blue bottom bar of your PIO editor or with the following command: +`pio run --target upload` + +PIO will download the necessaries platform and libraries with the correct versions, build the code and upload it. + +If you encounter errors the first thing to do is to clean your environment by using the white dust bin in the blue bottom bar. + +With some ESP it could be necessary to push the reset button when the upload begin. + +If you want to erase the settings stored in the ESP memory use: +`pio run --target erase` + +Once done the gateway should connect to your network and your broker, you should see it into the broker in the form of the following messages: +``` +home/OpenMQTTGateway/LWT Online +home/OpenMQTTGateway/version +``` + +# API +With the V0.9 we added the support of json for receiving and publishing. +Per default Json reception and Json publication is activated, the previous simple reception mode is also activated to avoid regression on commands. + +You can deactivate Json or simple mode following theses instructions: +```C++ +#define jsonPublishing true //comment if you don't want to use Json publishing (one topic for all the parameters) +//example home/OpenMQTTGateway_ESP32_DEVKIT/BTtoMQTT/4XXXXXXXXXX4 {"rssi":-63,"servicedata":"fe0000000000000000000000000000000000000000"} +//#define simplePublishing true //comment if you don't want to use simple publishing (one topic for one parameter) +//example +// home/OpenMQTTGateway_ESP32_DEVKIT/BTtoMQTT/4XXXXXXXXXX4/rssi -63.0 +// home/OpenMQTTGateway_ESP32_DEVKIT/BTtoMQTT/4XXXXXXXXXX4/servicedata fe0000000000000000000000000000000000000000 +#define simpleReceiving true //comment if you don't want to use old way reception analysis +#define jsonReceiving true //comment if you don't want to use Json reception analysis +``` + +If you are using platformio you can also comment the definitions above and define your parameters into platformio.ini file by setting the following `build_flags`: +```C++ + '-DjsonPublishing=true' + '-DjsonReceiving=true' + '-DsimpleReceiving=true' + '-DsimplePublishing=true' +``` + +Note that depending on the environment the default platformio.ini has common option defined see sections: +``` +[com-arduino] +[com-esp] +``` + +If you want to use HASS MQTT discovery you need to have +`#define jsonPublishing true` +& +`#define ZmqttDiscovery "HADiscovery"` +uncommented. +Added to that auto discovery box should be selected into your Home Assistant MQTT integration configuration. diff --git a/docs/use/actuators.md b/docs/use/actuators.md new file mode 100644 index 0000000..76b12fb --- /dev/null +++ b/docs/use/actuators.md @@ -0,0 +1,17 @@ +# Actuators +## ON OFF +This module enables to actuate things by giving to a PIN a HIGH or LOW value corresponding to an MQTT topic. +Example usage: Connect a transistor to power a relay, connect a led... + +So as to pilot the pin use the following commands: + +OFF command: +`mosquitto_pub -t home/OpenMQTTGateway_MEGA/commands/MQTTtoONOFF -m OFF` + +ON command +`mosquitto_pub -t home/OpenMQTTGateway_MEGA/commands/MQTTtoONOFF -m ON` + +## FASTLED + + + diff --git a/docs/use/ble.md b/docs/use/ble.md new file mode 100644 index 0000000..261dd8c --- /dev/null +++ b/docs/use/ble.md @@ -0,0 +1,80 @@ +# BLE gateway +## Receiving signals from BLE beacon devices for Presence detection + +Subscribe to all the messages with mosquitto or open your MQTT client software: + +` sudo mosquitto_sub -t +/# -v` + +_NOTE: HM-10 or HM-11 module needed if you are not using ESP32; configure in `user_config.h`_ + +The BT gateway module for OpenMQTTGateway enables the detection of BLE beacons and their signal strength. Generally BLE devices will not broadcast if they are paired so you may need to ensure your beacons is unpaired before it will be seen by the gateway. + +If beacons are detected the gateway will periodically publish messages to MQTT (beacons must not be paired, see above): + +``` +home/OpenMQTTGateway/BTtoMQTT/45E174126E00 {"id":"45:e1:74:12:6e:00","rssi":-89,"distance":21.51847,"servicedata":"fe0000000000000000000000000000000000000000"} +``` +``` +home/OpenMQTTGateway/BTtoMQTT/C7FaaD132C00 {"id":"c7:fa:ad:13:2c:00","rssi":-68,"distance":2.799256,"servicedata":"drfgdrgdsrgesrdgdrgdregesrgtrhtyhtfyhdtyhh"} +``` + +The subtopic after `home/BTtoMQTT/` is the MAC address of the Bluetooth low energy beacon. The rssi value is the [RSSI signal level](https://www.metageek.com/training/resources/understanding-rssi.html) from which you may deduce the relative distance to the device. +Consider the distance as a beta featuer as currently we are not retrieving the emitting power of the beacon to make it more accurate. + +Note that you can find apps to simulate beacons and do some tests like [Beacon simulator](https://play.google.com/store/apps/details?id=net.alea.beaconsimulator) + +IOS version >=10 devices advertise without an extra app a mac address, nevertheless this address [changes randomly](https://github.com/1technophile/OpenMQTTGateway/issues/71) and cannot be used for presence detection. You must install an app to advertise a fixed MAC address. + + +## Receiving signals Mi Flora/ Mi jia device/ LYWDS02, ClearGrass or Mi scale +So as to receive BLE sensors data you need either a simple ESP32 either an ESP8266/arduino + HM10/11 with firmware >= v601 +The mi flora supported firmware is >3.1.8 + +Verify that your sensor is working with the App and update it with the last software version. +You should see in your MQTT broker the following data: +![](../img/OpenMQTTgateway_miflora_results.png) + +Note that the gateway return one or two measurement value each time. The different measures depending on the devices are: +* Lux +* Temperature +* Moisture +* Fertilization +* Weight +* Impedance +* Battery (mi jia only) + +The infos will appear like this on your MQTT broker: + +`home/OpenMQTTGateway/BTtoMQTT/4C33A6603C79 {"hum":"52.6","tem":"19.2"}` + +More info are available on [my blog](https://1technophile.blogspot.fr/2017/11/mi-flora-integration-to-openmqttgateway.html) (especially about how it was implemented with HM10) + +## Setting a white or black list +A black list is a list of mac adresses that will never be published by OMG +to set black list +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/set -m '{"black-list":["012314551615","4C6577889C79","4C65A6663C79"]}'` + +A white list is a list of mac adresses permitted to be published by OMG +to set white list +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/set -m '{"white-list":["012314551615","4C65A5553C79","4C65A6663C79"]}'` + +Note: if you want to filter (white or black list) on BLE sensors that are auto discovered, you need to wait for the discovery before applying the white or black list + +## Setting the time between scans and force a scan + +If you want to change the time between readings you can change the interval by MQTT, if you want the BLE scan every 66seconds: + +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/set -m '{"interval":66000}'` + +you can also force a scan to be done by the following command: + +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/set -m '{"interval":0}'` + +Once done the previous value of interval will be recovered. + +## Other + +To check your hm10 firmware version upload a serial sketch to the nodemcu (this will enable communication directly with the hm10) and launch the command: +`AT+VERR?` + +More info about HM-10 is [available here](http://www.martyncurrey.com/hm-10-bluetooth-4ble-modules/) diff --git a/docs/use/gsm.md b/docs/use/gsm.md new file mode 100644 index 0000000..e2faa5d --- /dev/null +++ b/docs/use/gsm.md @@ -0,0 +1,25 @@ +# GSM 2G gateway +## Receiving SMS from 2G + +Subscribe to all the messages with mosquitto or open your MQTT client software: +`mosquitto_sub -t +/# -v` + +Generate your SMS by sending an SMS to the phone number of the A6/A7 SIM card you will see : + +``` +home/OpenMQTTGateway/2GtoMQTT {"phone":"+33123456789","date":"2018/04/22,16:17:51+02","message":"Hello OpenMQTTGateway"} +``` + +## Send data by MQTT to send an SMS message with A6/7 + +`sudo mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTto2G -m '{"phone":"+33123456789","date":"2018/04/22,16:17:51+02","message":"hello"}'` + +This command will send by SMS the sentence "hello" and use the phone number 0123456789 + +Arduino IDE serial data received when publishing data by MQTT + +![](../img/OpenMQTTGateway_serial_2G_1.jpg) + +Arduino IDE serial data received when receiving SMS + +![](../img/OpenMQTTGateway_serial_2G_2.jpg) diff --git a/docs/use/ir.md b/docs/use/ir.md new file mode 100644 index 0000000..a0d5567 --- /dev/null +++ b/docs/use/ir.md @@ -0,0 +1,120 @@ +# IR gateway +There is two methods for finding the IR codes you want to replicate: +1. Point the remote control to an IR receiver see [Receiving data from IR signal](#receiving-data-from-ir-signal) & [Send data by MQTT to convert it on IR signal](#send-data-by-mqtt-to-convert-it-on-ir-signal) +2. Find the code corresponding to your devices with IR global cache database https://irdb.globalcache.com/ see [Send data by MQTT from Global cache database to convert it on IR signal](#send-data-by-mqtt-from-global-cach%C3%A9-database-to-convert-it-on-ir-signal) + +Here is the [List of protocols](https://docs.google.com/spreadsheets/d/1rTDZIG8rm0dSf4vP7HdTdM4-aRY1nDWH4jK28_WRwHQ/edit?usp=sharing) supported by OMG, even if your device brand is not in the list you can still use raw IR data or GlobalCache database. + +## Receiving data from IR signal +Subscribe to all the messages with mosquitto or open your MQTT client software: +`mosquitto_sub -t +/# -v` +And press your IR remote control in front of the receiver led you should see the following messages for example: + +``` +home/OpenMQTTGateway/IRtoMQTT {"value":875849879,"protocol":7,"bits":32,"raw":"4534,4432,612,518,614,516,616,1618,618,1616,618,512,618,1618,608,524,612,518,616,514,618,512,616,1618,616,1618,618,514,616,1618,616,514,616,514,618,512,616,1618,618,1618,618,514,610,1622,616,514,618,514,614,516,616,1618,618,512,618,512,618,1616,550,580,618,1616,612,1624,618,1616,618"} +``` + +To receive big dump of raw data you need first to modify the [config_IR.h](https://github.com/1technophile/OpenMQTTGateway/blob/091b317660fd201a30e2cd0e15424a13c5a6bd71/config_IR.h#L41) and uncomment DumpMode true + +To know the name of the protocol corresponding to the number X (X=7 in our case), go to IRRemote header file definition and go to the protocol number X, RC5 = 1, RC6 = 2... +[For ESP8266](https://github.com/markszabo/IRremoteESP8266/blob/master/src/IRremoteESP8266.h) +[For Arduino](https://github.com/z3t0/Arduino-IRremote/blob/master/IRremote.h) +For number 7 it is samsung protocol + +Unknown protocols are filtered by default, if you want to see the unknown protocols set into [config_IR.h](https://github.com/1technophile/OpenMQTTGateway/blob/master/config_IR.h) +`#define pubIRunknownPrtcl true` instead of false + +![](https://github.com/1technophile/OpenMQTTGateway/blob/master/img/OpenMQTTGateway_serial3.jpg) + +You can take this code and try to reproduce it with the gateway either by using [decimal value](#send-data-by-mqtt-to-convert-it-on-ir-signal) or the [raw value](#send-raw-ir-data-by-mqtt). + +## Send data by MQTT to convert it on IR signal +With the IR gateway you need to put on the topic the protocol you want to use to send the signal, the different protocols implemented are the following, the MQTT keyword to include is between "": +* IR_GC +* IR_Sony +* IR_COOLIX +* IR_Whynter +* IR_NEC +* IR_DISH +* IR_Sharp +* IR_SAMSUNG +* IR_RC5 +* IR_RC6 (ESP8266 only) +* IR_MITSUBISHI (ESP8266 only) +* IR_GICABLE (ESP8266 only) +* IR_MITSUBISHI2 (ESP8266 only) +* IR_LASERTAG (ESP8266 only) +* IR_CARRIER_AC (ESP8266 only) +* IR_MIDEA (ESP8266 only) +* IR_NIKAI (ESP8266 only) +* IR_SHERWOOD (ESP8266 only) +* IR_DENON (ESP8266 only) +* IR_AIWA_RC_T501 (ESP8266 only) +* IR_JVC (ESP8266 only) + +Exhaustive list [here](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=1910001295) + +For example if I want to send a command to a sony TV you can use the following command: + +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoIR -m '{"value":551489775,"protocol_name":"IR_Sony "}'` + +The code after the -m represent the payload you want to send. + +If you don’t want to use special parameters for IR just use value key, the protocol per default is IR_NEC + +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoIR -m '{"value":551489775}'` + +NOTE: on arduino Uno most of the protocols are not enable per default due to memory constraints (it is not the case for MEGA), to enable them go to [user_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/master/main/User_config.h) and uncomment the #define corresponding the protocols you want: + +```C++ +//#define IR_COOLIX +//#define IR_Whynter +//#define IR_LG +//#define IR_Sony +//#define IR_DISH +//#define IR_RC5 +//#define IR_Sharp +#define IR_SAMSUNG +``` +## Send data by MQTT from Global Caché database to convert it on IR signal + +The website https://irdb.globalcache.com/ contains an important database of IR codes of various devices brand. By registering and asking the code you will receive a code as the example below: + +``` +code1: sendir,1:1,1,38000,1,69,340,169,20,20,20,20,20,64,20,20,20,20,20,20,20,20,20,20,20,64,20,64,20,20,20,64,20,64,20,64,20,64,20,64,20,64,20,64,20,20,20,20,20,20,20,20,20,20,20,20,20,20,20,20,20,64,20,64,20,64,20,64,20,64,20,64,20,1544,340,85,20,3663 +``` + +Extract this part of the code: +``` +38000,1,69,340,169,20,20,20,20,20,64,20,20,20,20,20,20,20,20,20,20,20,64,20,64,20,20,20,64,20,64,20,64,20,64,20,64,20,64,20,64,20,20,20,20,20,20,20,20,20,20,20,20,20,20,20,20,20,64,20,64,20,64,20,64,20,64,20,64,20,1544,340,85,20,3663 +``` + +and publish it to mqtt with the a subject containing IR_GC: +``` +mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoIR -m '{"raw":"38000,1,1,171,171,21,64,21,21,21,21,21,21,21,21,21,21,21,21,21,64,21,64,21,21,21,21,21,21,21,21,21,21,21,21,21,64,21,21,21,21,21,21,21,64,21,21,21,21,21,21,21,21,21,64,21,64,21,64,21,21,21,64,21,64,21,64,21,64,21,1114","protocol_name":"IR_GC"}' +``` + +You should be able to command your devices without having listened with the IR receiver or if your protocol is unknown by the IRremote library + +## Send data by MQTT with advanced IR parameters +IR sending support two advanced parameters; bits length and repeat number. + +The example below will send the following advanced parameters bits: 14 and repeat:4 times for a sony protocol: +``` +mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoIR -m '{"value":551489775,"protocol_name":"IR_NEC","repeat":4,"bits":14}' +``` + +## Send raw IR data by MQTT + +2) If you use an arduino UNO enable `IR_Raw` by uncommenting the line 129 in user_config.h +`#define IR_Raw` +If you are using the uno you will have to comment other gateway like ZgatewayRF, ZgatewayBT and ZgatewayIR to keep enough memory + +3) publish your code like below +``` +mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoIR -m '{"raw":"8850,4450,600,550,550,550,600,1600,600,550,600,500,600,500,600,550,600,500,600,1650,600,1600,600,550,600,1600,600,1650,600,1600,600,1650,600,1600,600,550,600,500,600,550,550,1650,600,500,600,550,600,500,600,550,550,1650,600,1650,550,1650,600,550,550,1650,600,1650,550,1650,600,1650,600","protocol_name":"IR_Raw"}' +``` + +## Repeat the IR signal OpenMQTTGateway receive +So as to repeat the IR signal received by the gateway once set the following parameter to true in [config_IR.h](https://github.com/1technophile/OpenMQTTGateway/blob/091b317660fd201a30e2cd0e15424a13c5a6bd71/config_IR.h#L37) +`#define repeatIRwMQTT true` diff --git a/docs/use/lora.md b/docs/use/lora.md new file mode 100644 index 0000000..bdda03c --- /dev/null +++ b/docs/use/lora.md @@ -0,0 +1,36 @@ +# LORA gateway +## Receiving data from LORA signal + +Subscribe to all the messages with mosquitto or open your MQTT client software: + +` sudo mosquitto_sub -t +/# -v` + +Generate your LORA signals by using another TTGO LORA module, you can flash the sender program from [this repository](https://github.com/LilyGO/TTGO-LORA32-V2.0) + +Once one board flashed with OMG and the other with the sender program you should receive regular packets. + +## Send data by MQTT to convert it on LORA signal +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoLORA -m '{"message":"test8"}'` + +This command will send by LORA the message "test8" and use the default parameters defined in [config_LORA.h](https://github.com/1technophile/OpenMQTTGateway/blob/4b8d28179b63ae3f3d454da57ec8c109c159c386/config_LORA.h#L32) + +If you want to test that your sending works you can use another TTGO LORA module, you can flash the receiver program from [this repository](https://github.com/LilyGO/TTGO-LORA32-V2.0) + +## Send data by MQTT with advanced LORA parameters + +LORA sending support the following parameters that should be specified in the json message; +* txpower: 2 to 20 +* spreadingfactor: 6 to 12. If a spreading factor of 6 is set, implicit header mode must be used to transmit and receive * * packets. +* frequency: 433E6, 866E6, 915E6 +* signalbandwidth: 7.8E3, 10.4E3, 15.6E3, 20.8E3, 31.25E3, 41.7E3, 62.5E3, 125E3, and 250E3 +* codingrate: 5 to 8 +* preamblelength: 6 to 65535 +* syncword: byte +* enablecrc: boolean + +More info on where the LORA library is born [@sandeepmistry](https://github.com/sandeepmistry/arduino-LoRa/blob/master/API.md#radio-parameters) + +Example: +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoLORA -m '{"message":"test8","txpower":17,}'` + +will make LORA use the a txpower of 17 when sending the message "test8" diff --git a/docs/use/rf.md b/docs/use/rf.md new file mode 100644 index 0000000..8da5641 --- /dev/null +++ b/docs/use/rf.md @@ -0,0 +1,151 @@ + +# RF gateways (433mhz/315mhz) + +Note that for the moment RF, RF2 and Pilight can not be activated on the same boards together. + +## RCSwitch based gateway + +### Receiving data from RF signal + +Subscribe to all the messages with mosquitto or open your MQTT client software: + +` sudo mosquitto_sub -t +/# -v` + +Generate your RF signals by pressing a remote button or other and you should see : + +`home/OpenMQTTGateway/433toMQTT {"value":1315156,"protocol":1,"length":24,"delay":317}` + +### Send data by MQTT to convert it on RF signal + +`mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTto433" -m '{"value":1315156}'` + +This command will send by RF the code 1315156 and use the default parameters (protocol 1, delay 350) + +Arduino IDE serial data received when publishing data by MQTT + +![](../img/OpenMQTTGateway_serial1.jpg) + +We see that the Arduino receive the value 1315156 on the MQTT subject "MQTTto433" and send the data by RF + +Arduino IDE serial data received when receiving data by 433Mhz + +![](../img/OpenMQTTGateway_serial2.jpg) + +### Send data by MQTT with advanced RF parameters + +RF sending support three advanced parameters; bits length, RF protocol and RF pulselength +if you want to use a different RCswitch protocol put inside your payload the protocol number 2, "protocol":2. + +if you want to use a pulselength 315 put inside your topic "delay":315 + +if you want to use a bits number different than 24 put inside your topic "length":24 for example + +Example: +`mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTto433" -m '{"value":1315156,"protocol":2,"length":24,"delay":315}'` +will make RCSwitch use the protocol 2 with a pulselength of 315ms and a bits number of 24 + +### Repeat the RF signal OpenMQTTGateway receive +So as to repeat the RF signal received by the gateway once set the following parameter to true in config_RF.h + +`#define repeatRFwMQTT true` + +### Repeat the RF signal several times +You can add a "repeat" key/value to the MQTTto433 JSON message to override the default number of repeats. + +Example: +`home/OpenMQTTGateway/commands/MQTTto433 {"value":1315156,"protocol":1,"length":24,"delay":317, "repeat":10}` + +## Pilight gateway + +### Receiving data from RF signal + +Subscribe to all the messages with mosquitto or open your MQTT client software: + +` sudo mosquitto_sub -t +/# -v` + +Generate your RF signals by pressing a remote button or other and you will see : + +![](../img/OpenMQTTGateway_Pilight_Digoo-DG-R8S.png) + +### Send data by MQTT to convert it on RF signal +**ON** + +`mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoPilight" -m '{"message":"{\"systemcode\":12,\"unitcode\":22,\"on\":1}","protocol":"elro_400_switch"}'` + +**OFF** + +`mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoPilight" -m '{"message":"{\"systemcode\":12,\"unitcode\":22,\"off\":1}","protocol":"elro_400_switch"}'` + +Theses commands will send by RF the signals to actuate an elro_400 switch + +## RF with SONOFF RF BRIDGE +### Receiving data from RF signal + +Subscribe to all the messages with mosquitto or open your MQTT client software: + +` sudo mosquitto_sub -t +/# -v` + +Generate your RF signals by pressing a remote button or other and you will see: +``` +home/OpenMQTTGateway/SRFBtoMQTT {"raw":"2B660186042E00E7E5","value":"59365","delay":"1111","val_Thigh":"390","val_Tlow":"1070"} +``` + +The first parameter is the raw value extracted from the RF module of the Sonoff bridge. The data are in hexadecimal and correspond to the details below: +https://www.itead.cc/wiki/images/5/5e/RF_Universal_Transeceive_Module_Serial_Protocol_v1.0.pdf +OpenMQTTGateway process the raw value to extract the other decimal values that can be reused to reproduce a signal (raw value can also be reused). + +NOTE: currently the device doesn't receive correct values from Switches remote control + +### Send data by MQTT to convert it on RF signal +`mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoSRFB" -m '{"value":1315156}'` + +This command will send by RF the code 1315156 and use the default parameters: +Repeat = 1 +Low time= 320 +High time= 900 +SYNC = 9500 + +### Send data by MQTT with advanced RF parameters + +RF bridge sending support four advanced parameters; Repeat, Low time, High time & Sync +if you want to repeat your signal sending put into your json payload "repeat":2, 2 means 2 repetitions of signal + +if you want to use a low time of 315 put inside your json payload "Tlow":315 + +if you want to use a high time of 845 put inside your json payload "Thigh":845 + +if you want to use a sync time of 9123 put inside your json payload "Tsyn":9123 + +Example: +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoSRFB/Tlow_315/Thigh_845/Tsyn_9123 -m '{"value":"33151562","delay":"9123","val_Thigh":"845","val_Tlow":"315"}'` +will make RF Bridge send a signal with the use of listed parameters 315, 845, 9123... + +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoSRFB/Raw -m '{"raw":"267A013603B6140551"}'` +will make RF Bridge send a signal with the use of advanced parameters defined in the raw string + +## RF2 gateway KAKU +RF2 gateway enables to send command to RF devices with the KAKU protocol. DIO chacon devices are an example. +It uses the same pinout as the RF gateway and both gateways can be used on the same setup. + +Receiving RF codes with the KAKU protocol is not compatible with ZgatewayRF , so as to get the code of your remotes you should comment ZgatewayRF in user_config.h. +Transmitting can be done with both ZgatewayRF and ZgatewayRF2 + +### Receiving data from KAKU signal + +Subscribe to all the messages with mosquitto or open your MQTT client software: + +` sudo mosquitto_sub -t +/# -v` + +Generate your RF signals by pressing a remote button or other and you will see : + +`home/OpenMQTTGateway/RF2toMQTT {"unit":0,"groupBit":0,"period":273,"address":8233228,"switchType":0}` + +### Send data by MQTT to convert it on KAKU signal + +Once you get the infos publish the parameters with mqtt like that for off: + +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoRF2 -m "{"unit":0,"groupBit":0,"period":273,"address":8233228,"switchType":0}"` + +for on: + +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoRF2 -m "{"unit":0,"groupBit":0,"period":273,"adress":8233228,"switchType":1}"` diff --git a/docs/use/rfm69.md b/docs/use/rfm69.md new file mode 100644 index 0000000..3f1975a --- /dev/null +++ b/docs/use/rfm69.md @@ -0,0 +1,37 @@ +# RFM69 gateway + +The RFM69 gateway enables to send and receive signal from/to another RFM69 module. It is based on the work of @bbx10 https://github.com/bbx10/nanohab + +### Receiving data from RFM signal + +Subscribe to all the messages with mosquitto or open your MQTT client software: + +` sudo mosquitto_sub -t +/# -v` + +Generate your RF signals with an Moteino on other RFM69 based devices, you will receive : + +`home/OpenMQTTGateway/RFM69toMQTT 60,-98,0` + +In this case "60,-98,0" is the signal sent by another RFM69 + a wemos D1 with the sample sketch [rfm69send](https://github.com/1technophile/rfm69send/blob/master/rfm69send.ino) loaded in it. + +### Send data by MQTT to convert it on RFM69 signal +`mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoPilight" -m '{"data":"test"}'` + +This command will send by RFM69 the string *test* to the default receiver id 99 + +### Send data by MQTT with advanced RFM69 parameters + +RFM69 sending support one advanced parameters the target receiver ID. + +Example: +SimplePublishing +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoRFM69/RCV_34 -m 33151562` +will make the gateway send to the receiver ID 34 (node number) instead of 99 + +JsonPublishing +`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoRFM69 -m '{"data":1315156,"receiverid":34}'` +This command will send by RFM69 the string *test* to the receiver id 34 instead of 99 + +### RFM69 acknowledgment +Unlike RF or IR RFM69 as a complete acknowledgment mechanism. When a signal is sent the RFM69 can acknowledge the fact that the recipient received the message. +In this case the gateway will publish the sent message to the topic defined by subjectGTWRFM69toMQTT macro. diff --git a/docs/use/sensors.md b/docs/use/sensors.md new file mode 100644 index 0000000..07caac5 --- /dev/null +++ b/docs/use/sensors.md @@ -0,0 +1,15 @@ +# Sensors +Subscribe to all the messages with mosquitto or open your MQTT client software: + +` sudo mosquitto_sub -t +/# -v` + +### ADC +The value is between 0 and 1024 and is tranmitted via Mqtt when it changes. +`home/OpenMQTTGateway/DHTtoMQTT {"value":543}` + +### DHT +You will receive every TimeBetweenReadingDHT (set into config_DHT.h) the DHT measurement (30s per default). + +`home/OpenMQTTGateway/DHTtoMQTT {"temp":21,"hum":51}` + +If you want to don't resend value when it is the same you can set dht_always = false in config_DHT.h \ No newline at end of file diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..4cb7abb --- /dev/null +++ b/package-lock.json @@ -0,0 +1,181 @@ +{ + "requires": true, + "lockfileVersion": 1, + "dependencies": { + "argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "requires": { + "sprintf-js": "~1.0.2" + } + }, + "balanced-match": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz", + "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=" + }, + "brace-expansion": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", + "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "requires": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=" + }, + "entities": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/entities/-/entities-1.1.2.tgz", + "integrity": "sha512-f2LZMYl1Fzu7YSBKg+RoROelpOaNrcGmE9AZubeDfrCEia483oW4MI4VyFd5VNHIgQ/7qm1I0wUHK1eJnn2y2w==" + }, + "esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" + }, + "fs.realpath": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", + "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=" + }, + "glob": { + "version": "7.1.5", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.5.tgz", + "integrity": "sha512-J9dlskqUXK1OeTOYBEn5s8aMukWMwWfs+rPTn/jn50Ux4MNXVhubL1wu/j2t+H4NVI+cXEcCaYellqaPVGXNqQ==", + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + }, + "inflight": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", + "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=", + "requires": { + "once": "^1.3.0", + "wrappy": "1" + } + }, + "inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==" + }, + "js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "requires": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + } + }, + "linkify-it": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-2.2.0.tgz", + "integrity": "sha512-GnAl/knGn+i1U/wjBz3akz2stz+HrHLsxMwHQGofCDfPvlf+gDKN58UtfmUquTY4/MXeE2x7k19KQmeoZi94Iw==", + "requires": { + "uc.micro": "^1.0.1" + } + }, + "lodash.escaperegexp": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/lodash.escaperegexp/-/lodash.escaperegexp-4.1.2.tgz", + "integrity": "sha1-ZHYsSGGAglGKw99Mz11YhtriA0c=" + }, + "lodash.sortby": { + "version": "4.7.0", + "resolved": "https://registry.npmjs.org/lodash.sortby/-/lodash.sortby-4.7.0.tgz", + "integrity": "sha1-7dFMgk4sycHgsKG0K7UhBRakJDg=" + }, + "lodash.startcase": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/lodash.startcase/-/lodash.startcase-4.4.0.tgz", + "integrity": "sha1-lDbjTtJgk+1/+uGTYUQ1CRXZrdg=" + }, + "markdown-it": { + "version": "8.4.2", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-8.4.2.tgz", + "integrity": "sha512-GcRz3AWTqSUphY3vsUqQSFMbgR38a4Lh3GWlHRh/7MRwz8mcu9n2IO7HOh+bXHrR9kOPDl5RNCaEsrneb+xhHQ==", + "requires": { + "argparse": "^1.0.7", + "entities": "~1.1.1", + "linkify-it": "^2.0.0", + "mdurl": "^1.0.1", + "uc.micro": "^1.0.5" + } + }, + "markdown-it-meta": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/markdown-it-meta/-/markdown-it-meta-0.0.1.tgz", + "integrity": "sha1-11to8RVlnK9WjkrUPLRgpHEkjDk=", + "requires": { + "js-yaml": "^3.8.1" + } + }, + "mdurl": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz", + "integrity": "sha1-/oWy7HWlkDfyrf7BAP1sYBdhFS4=" + }, + "minimatch": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", + "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", + "requires": { + "brace-expansion": "^1.1.7" + } + }, + "once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=", + "requires": { + "wrappy": "1" + } + }, + "path-is-absolute": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", + "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=" + }, + "sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw=" + }, + "uc.micro": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", + "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==" + }, + "vuepress-bar": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/vuepress-bar/-/vuepress-bar-0.1.1.tgz", + "integrity": "sha512-lHxQEk+sp7O/8OCqIJ2+I7t7PDWURgOzb7BccyOMYacKyYFLxEG9RR7g0O+PBXreI6nlvBBGIr1moMJlIC+A0w==", + "requires": { + "glob": "^7.1.4", + "lodash.escaperegexp": "^4.1.2", + "lodash.sortby": "^4.7.0", + "lodash.startcase": "^4.4.0", + "markdown-it": "^8.4.2", + "markdown-it-meta": "0.0.1" + } + }, + "wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=" + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..7ada235 --- /dev/null +++ b/package.json @@ -0,0 +1,6 @@ +{ + "scripts": { + "docs:dev": "vuepress dev docs", + "docs:build": "vuepress build docs" + } + } \ No newline at end of file