[RF] Proposal fix for issue #2139 + Extra documentation (#2157)

* Refactor announceDeviceTrigger function to improve parameter handling and documentation for optional device information
Fix null pointer references in RFtoMQTTdiscovery and update logging levels for RF signal handling
Refactor RF to MQTT discovery functions for improved clarity and parameter handling

* Update documentation for RF auto discovery and MQTT integration, correcting terminology and enhancing clarity

* Refactor enableRFReceive function to accept parameters for frequency and GPIOs, enhancing flexibility

docs/integrate/home_assistant.md

@@ -5,7 +5,7 @@ Home Assistant provide the [MQTT integration](https://www.home-assistant.io/inte
 Once this integration on home assistant is configured with the same MQTT broker, it is possible to create devices manually or through the autodiscovery function.
 
 
-## Auto discovery
+## Automatic integration with Auto discovery 
 
 From Home Assistant site 
 
@@ -42,7 +42,7 @@ On first and subsequent startups, auto discovery will start. If you want to prev
 Some devices may require a button push or motion/contact event to trigger a message and generate the auto discovery.
 :::
 
-## RTL_433 auto discovery specificity
+### RTL_433 auto discovery specificity
 
 Even if the RTL_433 gateway will create automatically the devices and entities, you may lose the link to them when you change the batteries. This is proper to the RF devices. In this case new device and entities will be created. You may bypass this by creating entities through manual configuration that filter following the device model and other parameters and don't take into account the id.
 Example:
@@ -74,16 +74,119 @@ mqtt:
 
 Alternatively the rssi signal could be used also.
 
-## MQTT Device Trigger and RF
+### RF (RCSwitch based gateway) Auto discovery specificity
+With OpenMQTTGateway [configured to receive RF signals](../setitup/rf.html) messages are transmitted accordingly.
 
-With OpenMQTTGateway [configured to receive RF signals](../setitup/rf.html) the messages are transmitted as indicated by [RCSwitch based gateway](../use/rf.html#rcswitch-based-gateway), so it is possible to receive a pulse every time the sensor discover a signal. 
+As indicated in the [RCSwitch based gateway](../use/rf.html#rcswitch-based-gateway), it is possible to receive a pulse each time the sensor detects a signal. With auto-discovery enabled, you can configure two types of entities in Home Assistant to handle RF signals:
 
-With autodiscovery enabled, HomeAssistant will discover a [MQTT Device Trigger](https://www.home-assistant.io/integrations/device_trigger.mqtt/) identified by the value field given in the mqtt argument. 
 
-## Manual integration examples
-From @123, @finity, @denniz03, @jrockstad, @anarchking, @dkluivingh
+1. An  [MQTT Device Trigger](https://www.home-assistant.io/integrations/device_trigger.mqtt/) which allows actions to be triggered when a specific RF signal is received. 
+2. An  [MQTT Sensor](https://www.home-assistant.io/integrations/sensor.mqtt/) 
+which stores the received RF data as a sensor value.
+
+Below are some examples of both configurations.
+
+#### Example A - RF as MQTT Device Trigger
+If the following parameters are enabled in OpenMQTTGateway:
+- ZgatewayRF="RF"
+- valueAsATopic=true
+- HADiscovery=true
+- RF_on_HAS_as_DeviceTrigger=true
+- RF_on_HAS_as_MQTTSensor=false
+
+Then, each time an RF signal is received by OpenMQTTGateway, two messages are sent to the MQTT broker:
+
+1. A device trigger announcement (used by Home Assistant to recognize the trigger).
+2. The RF signal data on the corresponding MQTT topic.
+
+```
+...
+N: [ OMG->MQTT ] topic: homeassistant/device_automation/246F287AF0C4/15524904/config msg: {"automation_type":"trigger","platform ":"device_automation","type":"Received","subtype":"RF-15524904","device":{"configuration_url":"http://192.168.2.150/","connections":[["mac","246F287AF0C4"]],"identifiers":["246F287AF0C4"],"mf":"OMG_community","mdl":"[\"WebUI\",\"RF\"]","name":"OMG_DEVELOPMENT","sw":"1.8.0-o"},"value_template":"{{trigger.value.raw}}","topic":"home/OMG_DEVELOPMENT/433toMQTT/15524904"}
+T: Dequeue JSON
+N: [ OMG->MQTT ] topic: home/OMG_DEVELOPMENT/433toMQTT/15524904 msg: {"value":15524904,"protocol":1,"length":24,"delay":368,"tre_state":"-","binary":"111011001110010000101000","raw":"11427,1042,407,1039,417,1027,430,302,1148,1019,438,1015,440,295,1152,301,1153,1014,442,1012,441,1008,445,291,1160,293,1158,1011,444,292,1156,296,1157,296,1157,298,1154,1011,442,295,1153,1013,443,293,1157,295,1154,300"}
+...
+```
+
+These messages allow Home Assistant to recognize and integrate the RF signal as a device trigger.
+![MQTTExplorer Show Topic](../img/HASS-RF-DeviceTrigger.png)
+*Example of a detected RF device trigger in Home Assistant: Green shows the real message, Yellow shows the device trigger configuration*
+
+Once this process is completed, Home Assistant detects a new trigger associated with the OpenMQTTGateway device and linked to the received RF signal value.
+This means that Home Assistant can now react to the received RF signal as an automation trigger.
+
+Example of a detected RF trigger in Home Assistant:
+
+![MQTTExplorer Show Topic](../img/HASS-RF-Trigger-example.png)
+*Example of a detected RF trigger in Home Assistant*
+
+
+
+#### Example B - RF As MQTT Sensor
+If the following parameters are enabled in OpenMQTTGateway:
+- ZgatewayRF="RF"
+- HADiscovery=true
+- RF_on_HAS_as_DeviceTrigger=false
+- RF_on_HAS_as_MQTTSensor=true
+
+During any discovery round, a SYS message is sent, setting the MQTT Sensor as a sensor of the OpenMQTTGateway device.
+
+```
+...
+N: [ OMG->MQTT ] topic: homeassistant/sensor/246F287AF0C4-gatewayRF/config msg: {"stat_t":"home/OMG_DEVELOPMENT/433toMQTT/#","avty_t":"home/OMG_DEVELOPMENT/LWT","name":"gatewayRF","uniq_id":"246F287AF0C4-gatewayRF","val_tpl":"{{ value_json.value | is_defined }}","pl_avail":"online","pl_not_avail":"offline","device":{"ids":["246F287AF0C4"],"name":"OMG_DEVELOPMENT","mdl":"[\"WebUI\",\"RF\"]","mf":"OMG_community","cu":"http://192.168.2.150/","sw":"1.8.0-o"}}
+T: Dequeue JSON
+```
+
+Then, each time an RF signal is received by OpenMQTTGateway, the content of messages are sent to the MQTT broker on classic topic:
+
+```
+T: Dequeue JSON
+N: [ OMG->MQTT ] topic: home/OMG_DEVELOPMENT/433toMQTT/15524904 msg: {"value":15524904,"protocol":1,"length":24,"delay":368,"tre_state":"-","binary":"111011001110010000101000","raw":"11404,1045,414,1034,424,1024,430,305,1146,1022,431,1019,436,299,1150,304,1145,1021,432,1017,438,1013,441,295,1156,299,1149,1018,436,300,1149,304,1146,307,1143,310,1141,1025,430,306,1143,1021,432,305,1145,310,1140,309"} 
+
+```
+
+These messages enable Home Assistant to recognize and integrate the RF signal as a sensor.
+
+![MQTTExplorer Show Topic](../img/HASS-RF-MQTTSensor.png)
+*Example of a detected RF sensor in Home Assistant: Yellow the configuration of sensor, Green the real message*
+
+Once this process is completed, Home Assistant detects a device with the new sensor and linked to the received RF signal value.
+This means that Home Assistant can now react to the received RF signal as an sensor event.
+
+Example of a detected RF trigger in Home Assistant:
+
+![MQTTExplorer Show Topic](../img/HASS-RF-Sensor-example.png)
+*Example of a detected RF sensor in Home Assistant: Yellow the real message*
+
+
+
+## Manual integration 
+If you prefer not to use MQTT auto-discovery, you can manually configure Home Assistant to manage MQTT topics. This approach gives you full control over the structure and behavior of your MQTT entities. Below are some examples of how to define your devices, sensors, and switches manually using YAML configuration.
+
+From @123, @finity, @denniz03, @jrockstad, @anarchking, @dkluivingh, @Odyno
+
+
+### Pir Sensor
+This is an example of how to configure a PIR (Passive Infrared) sensor in Home Assistant using MQTT. 
+
+![Pir Sensor](../img/digoo-pir-DG-HOSA.png)
+
+The configuration below sets up a binary sensor that detects motion and sends the state to Home Assistant.
+
+```yaml
+mqtt:
+  binary_sensor:
+    - unique_id: pir.15484294
+      name: "Pir.Mansarda"
+      device_class: motion
+      state_topic: "home/+/433toMQTT/15484294"
+      value_template: "{{ value_json.value }}"
+      payload_on: "15484294"
+      off_delay: 3
+```
+
 
 ### Door sensor
+
 ```yaml
 mqtt:
   binary_sensor: