MQTT docs and presence sensor type #664

dockerfiles/README.md

@@ -72,7 +72,7 @@ These are the most important settings to get at least some output in your Device
 | :------------- | :------------- | :-------------| 
 | arp-scan, nmap-scan | `SCAN_SUBNETS` | See the documentation on how [to setup SUBNETS, VLANs & limitations](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md) |
 | PiHole | `PIHOLE_RUN` | There are 2 approaches how to get PiHole devices imported. Via the PiHole import (`PIHOLE`) plugin or DHCP leases (`DHCPLSS`) plugin. The `PIHOLE` plugin requires you to map the PiHole database, as mentioned above. |
-| dhcp.leases | `DHCPLSS_RUN` | You need to map `:/etc/pihole/dhcp.leases` in the `docker-compose.yml` file if you enable this setting. This path has to be matched with a corresponding `DHCPLSS_paths_to_check` setting entry (If using a PiHole dhcp.leases file the path in the container must contain `pihole` as PiHole uses a different format of the `dhcp.leases` file). |
+| dhcp.leases | `DHCPLSS_RUN` | You need to map `:/etc/myfiles/dhcp.leases` in the `docker-compose.yml` file if you enable this setting. This path has to be matched with a corresponding `DHCPLSS_paths_to_check` setting entry (check the [DHCPLSS plugin readme](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dhcp_leases#overview) for details). |
 
 
 > [!NOTE]

front/plugins/_publisher_mqtt/README.md

@@ -1,13 +1,189 @@
-## Overview
+# Overview
 
-- Feed your data and device changes into [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md) via the MQTT Mosquito broker. (other brokers might work as well)
+- Feed your data and device changes into [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md) via the MQTT Mosquito broker (other brokers might work as well).
 
-### Usage
+# Usage
 
-- Go to settings and fill in relevant details.
+- Go to settings and fill in relevant details. There are 2 types of "devices" generated and sent to the broker. A generic overview device that contains online/down/archived device stats and then the actual devices detected by the application. 
 
 
-### Notes
+
+# Sample Payloads
+
+## Overview device
+
+The below payloads apply to the device showing overall online/down/archived stats. You can toggle them on/off with the `SEND_STATS` setting. 
+
+### MQTT discovery data:
+
+>[!NOTE]
+> You can replace the `netalertx` string of the below topic via the `DEVICE_ID` setting. 
+
+Topic: `homeassistant/sensor/netalertx/online/config`
+
+
+>[!NOTE]
+> You can replace the `"name": "NetAlertX"` string of the below payload via the `DEVICE_NAME` setting. 
+
+Payload:
+
+```json
+{
+  "name": "online",
+  "state_topic": "system-sensors/sensor/netalertx/state",
+  "value_template": "{{value_json.online}}",
+  "unique_id": "netalertx_sensor_online",
+  "device": {
+    "identifiers": [
+      "netalertx_sensor"
+    ],
+    "manufacturer": "NetAlertX",
+    "name": "NetAlertX"
+  },
+  "icon": "mdi:wifi-check",
+  "platform": "mqtt"
+}
+```
+
+### MQTT config data sample:
+
+>[!NOTE]
+> You can replace the `netalertx` string of the below topic via the `DEVICE_ID` setting. 
+
+Topic: `homeassistant/sensor/netalertx/all/config`
+
+Payload:
+
+```json
+{
+  "name": "all",
+  "state_topic": "system-sensors/sensor/netalertx/state",
+  "value_template": "{{value_json.all}}",
+  "unique_id": "netalertx_sensor_all",
+  "device": {
+    "identifiers": [
+      "netalertx_sensor"
+    ],
+    "manufacturer": "NetAlertX",
+    "name": "NetAlertX"
+  },
+  "icon": "mdi:wifi",
+  "platform": "mqtt"
+}
+```
+
+
+### MQTT state data:
+
+>[!NOTE]
+> You can replace the `netalertx` string of the below topic via the `DEVICE_ID` setting. 
+
+Topic: `system-sensors/sensor/netalertx/state`
+
+Payload:
+
+```json
+{
+  "online": 30,
+  "down": 36,
+  "all": 66,
+  "archived": 0,
+  "new": 0,
+  "unknown": 0
+}
+```
+
+
+## Individual devices
+
+The below payloads apply to individual devices. Every device discovered by the application will generate the below messages. You can toggle them on/off with the `SEND_DEVICES` setting. 
+
+### MQTT discovery data:
+
+Topic: `homeassistant/sensor/mac_44_ef_44_ef_44_ef/last_ip/config`
+
+Payload:
+
+```json
+
+{
+  "name": "last_ip",
+  "state_topic": "system-sensors/sensor/mac_44_ef_44_ef_44_ef/state",
+  "value_template": "{{value_json.last_ip}}",
+  "unique_id": "mac_44_ef_44_ef_44_ef_sensor_last_ip",
+  "device": {
+    "identifiers": [
+      "mac_44_ef_44_ef_44_ef_sensor"
+    ],
+    "manufacturer": "NetAlertX",
+    "name": "Camera - E1"
+  },
+  "icon": "mdi:ip-network",
+  "platform": "mqtt"
+}
+
+```
+
+### MQTT state data:
+
+Topic: `system-sensors/sensor/mac_44_ef_44_ef_44_ef/state`
+
+Payload:
+
+```json
+{
+  "last_ip": "192.168.1.33",
+  "is_new": "0",
+  "vendor": "None",
+  "mac_address": "44:ef:44:ef:44:ef"
+}
+```
+
+### Transmitted message examples:
+
+Topic: `homeassistant/binary_sensor/mac_44_ef_44_ef_44_ef/is_present/`
+
+Payload:
+
+```json
+{
+  "name": "is_present",
+  "state_topic": "system-sensors/binary_sensor/mac_44_ef_44_ef_44_ef/state",
+  "value_template": "{{value_json.is_present}}",
+  "unique_id": "mac_44_ef_44_ef_44_ef_sensor_is_present",
+  "device": {
+    "identifiers": [
+      "mac_44_ef_44_ef_44_ef_sensor"
+    ],
+    "manufacturer": "NetAlertX",
+    "name": "Camera - E1"
+  },
+  "icon": "mdi:wifi",
+  "platform": "mqtt"
+}
+```
+
+Topic: `system-sensors/binary_sensor/mac_44_ef_44_ef_44_ef/state`
+
+Payload:
+
+```json
+{
+  "is_present": "OFF"
+}
+```
+
+```json
+{
+  "is_present": "ON"
+}
+```
+
+>[!WARNING]
+> Please check your Home Assistant MQTT broker debug info for the most up-to-date data nad format as the above might be outdated.  
+
+
+## Implementation Notes
 
 The first run will take a while, subsequent should be much faster because new sensors don't have to be created anymore. If the first sync times out, try to increase the timeout setting (default: 10s per device). A bit of background:
 
@@ -22,5 +198,3 @@ The first run will take a while, subsequent should be much faster because new se
 
 
 The state is managed differently, the state of the sensor is not included in the hash. This might be improved upon in later releases. 
-
-

front/plugins/_publisher_mqtt/config.json

@@ -425,36 +425,6 @@
                 "string" : "Nombre de usuario utilizado para iniciar sesión en su instancia de agente de MQTT."
             }]
         },
-        {
-            "function": "DEVICE_ID",
-            "type": "text",
-            "default_value": "netalertx",
-            "options": [],
-            "localized": ["name", "description"],
-            "name" : [{
-                "language_code": "en_us",
-                "string" : "Device ID"
-				}],
-            "description": [{
-                "language_code": "en_us",
-                "string" : "The root path of the sensor"
-				}]
-        },
-        {
-            "function": "DEVICE_NAME",
-            "type": "text",
-            "default_value": "NetAlertX",
-            "options": [],
-            "localized": ["name", "description"],
-            "name" : [{
-                "language_code": "en_us",
-                "string" : "Device name"
-				}],
-            "description": [{
-                "language_code": "en_us",
-                "string" : "The name used for the devices."
-				}]
-        },
         {
             "function": "PASSWORD",
             "type": "password",
@@ -556,6 +526,36 @@
             }
             ]
         },      
+        {
+            "function": "DEVICE_ID",
+            "type": "text",
+            "default_value": "netalertx",
+            "options": [],
+            "localized": ["name", "description"],
+            "name" : [{
+                "language_code": "en_us",
+                "string" : "Device ID"
+				}],
+            "description": [{
+                "language_code": "en_us",
+                "string" : "The root path of the stats overview sensor. Inserted into the <code>system-sensors/sensor/{DEVICE_ID}/state</code> topic."
+				}]
+        },
+        {
+            "function": "DEVICE_NAME",
+            "type": "text",
+            "default_value": "NetAlertX",
+            "options": [],
+            "localized": ["name", "description"],
+            "name" : [{
+                "language_code": "en_us",
+                "string" : "Device name"
+				}],
+            "description": [{
+                "language_code": "en_us",
+                "string" : "The name used for the stats overview device."
+				}]
+        },   
         {
             "function": "SEND_DEVICES",
             "type": "boolean",
@@ -572,6 +572,24 @@
                 "string" : "Check to send individual devices to the broker with details, such as <code>is_new</code>, <code>is_present</code>, or <code>mac_address</code> of the devices."
             }
             ]
+        },
+        {
+            "function": "PRESENCE_SENSOR_TYPE",         
+            "events": [],   
+            "type": "text.select",            
+            "default_value":"binary_sensor",
+            "options": ["binary_sensor", "device_tracker" ],
+            "localized": ["name", "description"],
+            "name" :[{
+                "language_code": "en_us",
+                "string" : "Presence Sensor Type"
+				}],
+            "description": [
+                {
+                "language_code": "en_us",
+                "string" : "The type of the sensor that should be generated for the <code>is_present</code> sensor. Inserted into the <code>homeassistant/{PRESENCE_SENSOR_TYPE}/mac_44_ef_44_ef_44_ef/is_present/</code> topic. See the <a target=\"_blank\" href=\"https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/_publisher_mqtt/README.md#usage\">Plugin readme</a> for details."
+				}
+            ]
         }         
     ]
 }

front/plugins/_publisher_mqtt/mqtt.py

@@ -280,6 +280,7 @@ def mqtt_start(db):
 
     deviceName      = get_setting_value('MQTT_DEVICE_NAME')
     deviceId        = get_setting_value('MQTT_DEVICE_ID')    
+    presenceSenType = get_setting_value('PRESENCE_SENSOR_TYPE')    
     
     # General stats    
 
@@ -324,7 +325,7 @@ def mqtt_start(db):
             deviceNameDisplay = re.sub('[^a-zA-Z0-9-_\s]', '', device["dev_Name"]) 
 
             create_sensor(mqtt_client, deviceId, deviceNameDisplay, 'sensor', 'last_ip', 'ip-network', device["dev_MAC"])
-            create_sensor(mqtt_client, deviceId, deviceNameDisplay, 'binary_sensor', 'is_present', 'wifi', device["dev_MAC"])
+            create_sensor(mqtt_client, deviceId, deviceNameDisplay, presenceSenType, 'is_present', 'wifi', device["dev_MAC"])
             create_sensor(mqtt_client, deviceId, deviceNameDisplay, 'sensor', 'mac_address', 'folder-key-network', device["dev_MAC"])
             create_sensor(mqtt_client, deviceId, deviceNameDisplay, 'sensor', 'is_new', 'bell-alert-outline', device["dev_MAC"])
             create_sensor(mqtt_client, deviceId, deviceNameDisplay, 'sensor', 'vendor', 'cog', device["dev_MAC"])
@@ -340,7 +341,7 @@ def mqtt_start(db):
                 }
             ) 
 
-            publish_mqtt(mqtt_client, 'system-sensors/binary_sensor/'+deviceId+'/state', 
+            publish_mqtt(mqtt_client, f'system-sensors/{presenceSenType}/{deviceId}/state', 
                 { 
                     "is_present": to_binary_sensor(str(device["dev_PresentLastScan"]))
                 }