diff --git a/dockerfiles/README.md b/dockerfiles/README.md index 3bfd3046..64e07c4c 100755 --- a/dockerfiles/README.md +++ b/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] diff --git a/front/plugins/_publisher_mqtt/README.md b/front/plugins/_publisher_mqtt/README.md index f24cf631..78c7e350 100755 --- a/front/plugins/_publisher_mqtt/README.md +++ b/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. - - diff --git a/front/plugins/_publisher_mqtt/config.json b/front/plugins/_publisher_mqtt/config.json index 18a8a826..17593f99 100755 --- a/front/plugins/_publisher_mqtt/config.json +++ b/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", @@ -555,7 +525,37 @@ "string" : "Check to send overal device stats, such as number of Online and Offline devices." } ] - }, + }, + { + "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 system-sensors/sensor/{DEVICE_ID}/state 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 is_new, is_present, or mac_address 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 is_present sensor. Inserted into the homeassistant/{PRESENCE_SENSOR_TYPE}/mac_44_ef_44_ef_44_ef/is_present/ topic. See the Plugin readme for details." + } + ] } ] } diff --git a/front/plugins/_publisher_mqtt/mqtt.py b/front/plugins/_publisher_mqtt/mqtt.py index fadd2274..41fbf74d 100755 --- a/front/plugins/_publisher_mqtt/mqtt.py +++ b/front/plugins/_publisher_mqtt/mqtt.py @@ -278,8 +278,9 @@ def mqtt_start(db): mqtt_client = mqtt_create_client() - deviceName = get_setting_value('MQTT_DEVICE_NAME') - deviceId = get_setting_value('MQTT_DEVICE_ID') + 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"])) }