[LORA] Improvements, change frequency, webUI, Oled support, add boards (

1technophile#1742)

* [LORA] Capability to change LORA frequency and Add OLED

Merge of the 2 environments for TTGO V1

* Merge messages keys with upper level json

* Id as a sub topic

* Add display and state measures

* Add frequency configuration through WebUI

* Add parameters

* Add auto discovery

* Add node example for ttgo lora32 v1

* Add environments and fix scope

* Support for sync word as a byte

* Fix TX Power setting

* Add LoRa gateway description

* Add onlyknown filter

.github/workflows/build.yml

@@ -44,11 +44,10 @@ jobs:
           - "lilygo-ble"
           - "esp32dev-multi_receiver"
           - "tinypico-ble"
-          - "ttgo-lora32-v1-868"
-          - "ttgo-lora32-v1-915"
+          - "ttgo-lora32-v1"
+          - "ttgo-lora32-v21"
           - "ttgo-t-beam"
-          - "heltec-wifi-lora-32-868"
-          - "heltec-wifi-lora-32-915"
+          - "heltec-wifi-lora-32"
           - "shelly-plus1"
           - "nodemcuv2-all-test"
           - "nodemcuv2-fastled-test"

docs/use/lora.md

@@ -1,34 +1,64 @@
 ---
 title: LORA MQTT Gateway
-description: Explore the LORA MQTT gateway, designed for integration with devices utilizing LORA technology, including the MakerFab soil and moisture sensor. Unlock long range communication with the power of LORA..
+description: Explore the LORA MQTT gateway, designed for integration with devices utilizing LORA technology, including the MakerFab soil and moisture sensor, devices from PricelessTookit. Unlock long range communication with the power of LORA..
 ---
 # LORA gateway
 
-Tutorial on how to leverage LORA for a mailbox sensor from [PricelessToolkit](https://www.youtube.com/channel/UCz75N6inuLHXnRC5tqagNLw):
-<iframe width="560" height="315" src="https://www.youtube.com/embed/6DftaHxDawM" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
+## What is a LORA gateway
+A LoRa (Long Range) gateway is a device that facilitates communication between LoRa nodes and networks, enabling the transmission and reception of data over long distances using the LoRa modulation technique. It's designed to work with devices that utilize LoRa technology, such as the MakerFab soil and moisture sensor, devices from PricelessTookit and DIY sensors.
+
+The primary distinction between a LoRa gateway and a LoRaWAN gateway lies in the protocol and network architecture:
+
+LoRa Gateway: Focuses solely on the physical layer, utilizing the LoRa modulation for communication. It's responsible for receiving and transmitting raw LoRa signals without concerning itself with network protocols or data handling at higher layers. Being focused solely on the physical layer, a LoRa Gateway offers greater flexibility for customization and experimentation. The OpenMQTTGateway LoRa gateway receives raw LoRa signals, processes them, and publishes the data to an MQTT topic. Conversely, it can subscribe to MQTT topics and send commands to LoRa devices. This gateway is particularly useful for DIY projects, home automation enthusiasts, and scenarios where direct integration of LoRa devices with MQTT is desired.
+
+LoRaWAN Gateway: Operates at a higher layer and is part of the LoRaWAN network architecture. LoRaWAN is a protocol specification built on top of the LoRa technology, providing features like adaptive data rate, encryption, and multi-channel/multi-modulation. A LoRaWAN gateway handles the data from multiple LoRa nodes, forwards it to a centralized network server, which then manages the data and communicates back to the nodes.
+
+In essence, while both gateways utilize LoRa technology for communication, a LoRaWAN gateway is more sophisticated, offering advanced features and integration with the LoRaWAN network infrastructure. The LoRa gateway, with its simpler architecture, is ideal for small networks of nodes, offering easier setup and configuration, making it an interesting choice for users keen on experimenting with LoRa technology.
+
+## Configuring the LORA gateway
+
+The LORA gateway can be configured by MQTT commands or by using the WebUI, here are the parameters available, they can be combined with the key "save" or "erase":
+* txpower: 0 to 14
+* spreadingfactor: 7 to 12
+* frequency: 433000000, 868000000, 915000000
+* signalbandwidth: 7800, 10400, 15500, 20800, 31250, 41700, 62500, 125000, and 250000
+* codingrate: 5 to 8
+* preamblelength: 6 to 65535
+* syncword: byte
+* enablecrc: boolean
+* invertiq: boolean
+* onlyknown: boolean
+
+With the WebUI:
+![LORA configuration page](../img/OpenMQTTGateway_LORA_Configuration.png)
+
+With MQTT commands:
+`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoLORA/config -m '{"frequency":"433000000","save":true}'`
 
 ## 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) and the SSD1306 library [there](https://github.com/ThingPulse/esp8266-oled-ssd1306)
-
-![TTGO Lora sending packets](../img/OpenMQTTGateway_TTGO32_LORA_Send.jpg)
+Generate your LORA signals by using another LORA module, you can flash the sender program from [this example](../../examples/LoraTemperature/) to an ESP32 LORA board, this sample node will generate a LORa signal containing the ESP32 internal temperature. 
 
-Once one board flashed with OMG and the other with the sender program you should receive regular packets into `home/OpenMQTTGateway_ESP32_LORA_TEST/LORAtoMQTT` like below:
+Once one board flashed with OMG and the other with the sender program you should receive regular packets into `home/OpenMQTTGateway_ESP32_LORA_TEST/LORAtoMQTT/AABBCCDDEEFF` like below:
 
 ```json
-{"rssi":-16,"snr":9.25,"pferror":-3598,"packetSize":9,"message":"hello 35"}
-{"rssi":-26,"snr":9,"pferror":-3598,"packetSize":9,"message":"hello 36"}
-{"rssi":-16,"snr":9.5,"pferror":-3581,"packetSize":9,"message":"hello 37"}
+{"id":"AA:BB:CC:DD:EE:FF","rssi":-16,"snr":9.25,"pferror":-3598,"packetSize":9,"tempc":"55.3"}
+{"id":"AA:BB:CC:DD:EE:FF","rssi":-26,"snr":9,"pferror":-3598,"packetSize":9,"tempc":"55.4"}
+{"id":"AA:BB:CC:DD:EE:FF","rssi":-16,"snr":9.5,"pferror":-3581,"packetSize":9,"tempc":"57"}
 ```
 
+![LORA board receiving data](../img/OpenMQTTgateway_ESP32_LORA_MSG.png)
+
 Messages that contain non-printable characters will be converted to hexadecimal and look like this:
 ```json
 {"rssi":-121,"snr":-11.75,"pferror":-29116,"packetSize":3,"hex":"C0FFEE"}
 ```
+They can be filtered by setting the "onlyknown" command to `true` or by an activation into the WebUI or Home Assistant.
+
 And from a supported device (in this case, a WiPhone), looks like this:
 ```json
 {"rssi":-50,"snr":9.25,"pferror":20728,"packetSize":30,"from":"123ABC","to":"000000","message":"Hi from WiPhone","type":"WiPhone"}
@@ -44,23 +74,14 @@ If you want to test that your sending works you can use another TTGO LORA module
 
 ## 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)
-
-Examples:
-
 * Plain text message: `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"
 * Binary message: `mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoLORA" -m '{"hex":"01C0FFEE"}'`\
 will send binary 0x01C0FFEE
 * WiPhone message: `mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoLORA" -m '{"message":"test","type":"WiPhone","to":"123ABC","from":"FFFFFF"}'`\
 will send "test" to a WiPhone with chip ID 123ABC
+
+More info on where the LORA library is born [@sandeepmistry](https://github.com/sandeepmistry/arduino-LoRa/blob/master/API.md#radio-parameters)
+
+Tutorial on how to leverage LORA for a mailbox sensor from [PricelessToolkit](https://www.youtube.com/channel/UCz75N6inuLHXnRC5tqagNLw):
+<iframe width="560" height="315" src="https://www.youtube.com/embed/6DftaHxDawM" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>

environments.ini

@@ -869,33 +869,50 @@ board_build.flash_mode = dio
 custom_description = BLE gateway
 custom_hardware = ESP32 TinyPICO
 
-[env:ttgo-lora32-v1-868]
+[env:ttgo-lora32-v1]
 platform = ${com.esp32_platform}
 board = ttgo-lora32-v1
 lib_deps =
   ${com-esp32.lib_deps}
+  ${libraries.ssd1306}
   ${libraries.lora}
 build_flags =
   ${com-esp32.build_flags}
   '-DZgatewayLORA="LORA"'
   '-DLORA_BAND=868E6'
+  '-DZdisplaySSD1306="LilyGo_SSD1306"'
+  '-DSDA_OLED=4'
+  '-DSCL_OLED=15'
+  '-DRST_OLED=16'
+  '-DWIFI_LoRa_32=true'
   '-DGateway_Name="OMG_ESP32_LORA"'
-custom_description = LORA communication 868Mhz using arduino-LoRA
+custom_description = LORA communication using arduino-LoRA configurable frequency
 custom_hardware= ESP32 TTGO LORA V1
 
-[env:ttgo-lora32-v1-915]
+[env:ttgo-lora32-v21]
 platform = ${com.esp32_platform}
-board = ttgo-lora32-v1
+board = ttgo-lora32-v21
 lib_deps =
   ${com-esp32.lib_deps}
+  ${libraries.ssd1306}
   ${libraries.lora}
 build_flags =
   ${com-esp32.build_flags}
-  '-DZgatewayLORA="LORA"'
-  '-DLORA_BAND=915E6'
+; *** OpenMQTTGateway Config ***
+  ;'-UZmqttDiscovery'          ; disables MQTT Discovery
   '-DGateway_Name="OMG_ESP32_LORA"'
-custom_description = LORA communication 915Mhz using arduino-LoRA
-custom_hardware= ESP32 TTGO LORA V1
+; *** OpenMQTTGateway Modules ***
+  '-DZgatewayLORA="LORA"'
+; *** ssd1306 Display Options ***
+  '-DZdisplaySSD1306="LilyGo_SSD1306"'
+;  '-DLOG_TO_OLED=true'         ; Enable log to OLED
+;  '-DJSON_TO_OLED=true'
+;  '-DLOG_LEVEL_OLED=LOG_LEVEL_NOTICE'
+;  '-DDISPLAY_IDLE_LOGO=false'
+;  '-DDISPLAY_BRIGHTNESS=80'
+;  '-DDISPLAY_METRIC=false'
+custom_description = For ESP32, Gateway using LORA
+custom_hardware = ESP32 LILYGO LoRa32 V2.1
 
 [env:ttgo-t-beam]
 # See version pinout differences here
@@ -928,7 +945,7 @@ build_flags =
 custom_description = BLE gateway with battery holder
 custom_hardware = TTGO T BEAM
 
-[env:heltec-wifi-lora-32-868]  ; Heltec ESP32 Board with SSD1306 display
+[env:heltec-wifi-lora-32]  ; Heltec ESP32 Board with SSD1306 display
 platform = ${com.esp32_platform}
 board = heltec_wifi_lora_32
 lib_deps =
@@ -952,34 +969,7 @@ build_flags =
 ;  '-DDISPLAY_IDLE_LOGO=false'
 ;  '-DDISPLAY_BRIGHTNESS=80'
 ;  '-DDISPLAY_METRIC=false'
-custom_description = LORA communication 868Mhz using arduino-LoRA
-custom_hardware = ESP32 HELTEC LORA32
-
-[env:heltec-wifi-lora-32-915]   ; Heltec ESP32 Board with SSD1306 display
-platform = ${com.esp32_platform}
-board = heltec_wifi_lora_32
-lib_deps =
-  ${com-esp32.lib_deps}
-  ${libraries.lora}
-  ${libraries.ssd1306}
-build_flags =
-  ${com-esp32.build_flags}
-; *** OpenMQTTGateway Modules ***
-  '-DZgatewayLORA="LORA"'
-  '-DLORA_BAND=915E6'
-  '-DGateway_Name="OMG_ESP32_LORA"'
-  '-DLED_SEND_RECEIVE=25'
-  '-DTimeLedON=0.1'
-  '-DLED_SEND_RECEIVE_ON=1'
-; *** ssd1306 Display Options ***
-  '-DZdisplaySSD1306="HELTEC_SSD1306"'
-;  '-DLOG_TO_OLED=true'         ; Enable log to OLED
-;  '-DJSON_TO_OLED=true'
-;  '-DLOG_LEVEL_OLED=LOG_LEVEL_NOTICE'
-;  '-DDISPLAY_IDLE_LOGO=false'
-;  '-DDISPLAY_BRIGHTNESS=80'
-;  '-DDISPLAY_METRIC=false'
-custom_description = LORA communication 915Mhz using arduino-LoRA
+custom_description = LORA communication using arduino-LoRA
 custom_hardware = ESP32 HELTEC LORA32
 
 ; For testing only, not for production use

examples/LoraTemperature/.gitignore

@@ -0,0 +1,5 @@
+.pio
+.vscode/.browse.c_cpp.db*
+.vscode/c_cpp_properties.json
+.vscode/launch.json
+.vscode/ipch

examples/LoraTemperature/README.md

@@ -0,0 +1,59 @@
+# OpenMQTTGateway LoRa Node Example
+This repository contains an example of a LoRa node program designed for the ESP32 platform. The program reads the internal temperature of the ESP32, packages the data into a JSON format, and sends it over LoRa.
+
+## Features:
+* Uses an SX12XX LoRa module.
+* Displays packet sending status and temperature data on an SSD1306 OLED display.
+* Sends the ESP32's MAC address as the node ID.
+* Sends temperature data in Celsius.
+
+## Hardware Requirements:
+* ESP32 development board.
+* SX12XX LoRa module.
+* SSD1306 OLED display.
+
+## Pin Configuration:
+* SCK  - GPIO5
+* MISO - GPIO19
+* MOSI - GPIO27
+* SS   - GPIO18
+* RST  - GPIO14
+* DI0  - GPIO26
+
+## Setup:
+### Hardware Setup:
+
+Connect the SX1278 LoRa module and the SSD1306 OLED display to the ESP32 according to the pin configuration.
+Ensure that the OLED display is powered correctly.
+
+### Software Setup:
+
+* Clone this repository.
+* Open the provided node program with PlatformIO
+* Upload the program to your ESP32.
+
+## Usage:
+Power on the ESP32.
+The OLED display will show the status of the packet being sent and the current temperature reading.
+The built-in LED on the ESP32 will blink once every time a packet is sent.
+Monitor the serial output (at 115200 baud rate) to see the JSON formatted data being sent.
+
+## Data Format:
+The data is sent in the following JSON format:
+
+```json
+{
+  "model": "ESP32TEMP",
+  "id": "ESP32_MAC_ADDRESS",
+  "tempc": "TEMPERATURE_IN_CELSIUS"
+}
+```
+
+## Troubleshooting:
+LoRa Initialization Failed: Ensure that the SX1278 LoRa module is connected correctly and powered on.
+OLED Display Not Working: Check the connections and ensure that the display is powered correctly.
+No Temperature Data: Ensure that the ESP32's internal temperature sensor is functional.
+Contributing:
+Feel free to contribute to this example by opening issues or submitting pull requests. Any feedback or improvements are welcome!
+
+I hope this README helps users understand and use your program! Adjustments can be made as necessary to fit any additional details or changes.

examples/LoraTemperature/platformio.ini

@@ -0,0 +1,36 @@
+; PlatformIO Project Configuration File
+;
+;   Build options: build flags, source filter
+;   Upload options: custom upload port, speed and extra flags
+;   Library options: dependencies, extra library storages
+;   Advanced options: extra scripting
+;
+; Please visit documentation for the other options and examples
+; https://docs.platformio.org/page/projectconf.html
+
+[env:ttgo-lora32-v1]
+platform = espressif32
+board = ttgo-lora32-v1
+framework = arduino
+lib_deps =
+    https://github.com/sandeepmistry/arduino-LoRa.git#f4a1d27
+    https://github.com/ThingPulse/esp8266-oled-ssd1306.git#f96fd6a
+monitor_speed = 115200
+
+[env:ttgo-lora32-v21]
+platform = espressif32
+board = ttgo-lora32-v21
+framework = arduino
+lib_deps =
+    https://github.com/sandeepmistry/arduino-LoRa.git#f4a1d27
+    https://github.com/ThingPulse/esp8266-oled-ssd1306.git#f96fd6a
+monitor_speed = 115200
+
+[env:heltec-wifi-lora-32]  ; Heltec ESP32 Board with SSD1306 display
+platform = ${com.esp32_platform}
+board = heltec_wifi_lora_32
+framework = arduino
+lib_deps =
+    https://github.com/sandeepmistry/arduino-LoRa.git#f4a1d27
+    https://github.com/ThingPulse/esp8266-oled-ssd1306.git#f96fd6a
+monitor_speed = 115200