Home

Awesome

Monitor-Appdaemon-App

hacs_badge

<a href="https://www.buymeacoffee.com/cm5bhML" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-black.png" width="150px" height="35px" alt="Buy Me A Coffee" style="height: 35px !important;width: 150px !important;" ></a>

Appdaemon App for Andrew's Monitor Presence Detection System.

The Monitor Presence Detection system, is a Bash script monitor.sh created by Andrew Freyer, which is designed to run on multiple Linux systems like the Raspberry Pi around the home, to detect if persons are near or not. It is designed to work with 1 or more scripts installed on 1 or more computers (like Raspberry Pi) referred to here as nodes, to detect presence. The node uses the onboard Bluetooth adapter to detect Bluetooth devices (phone/watch/beacon/etc) is near and then reports the state from the device on a person (near or not) to a MQTT Broker. More details about the script, how it functions and setup can be found by following this link.

This App is designed to maximise the use of the detection system, so that the user can easily have it integrated into their automation system comprising of Home Assistant (HA) and AppDaemon (AD), with as less effort as possible no matter the number of users or nodes in place. This app when added to an Appdaemon instance, will help to auto generate entities for presence detection based on the data reported by each node in HA, no matter the number of nodes running in that location or Bluetooth devices to be detected. Added to this, for those that have no Appdaemon running to use this app, this repository also includes a script to easily install both AppDaemona and the Monitor-App in a Linux computer. - contributed by TheStigh

Features

Requirements

Installation

Alternative Installation Methods (Without HACS):

When developing this app, 4 main things were my target:

Example Simple Configuration

home_presence_app:
  module: home_presence_app
  class: HomePresenceApp
  home_gateway_sensors:
    - binary_sensor.main_door_contact
    
  known_devices:
    - xx:xx:xx:xx:xx:xx Odianosen's iPhone
    - xx:xx:xx:xx:xx:xx Nkiruka's iPad

Example Advanced Configuration

home_presence_app:
  module: home_presence_app
  class: HomePresenceApp
  plugin: 
    - HASS
    - MQTT
  #monitor_topic: presence
  #mqtt_event: MQTT
  #user_device_domain: device_tracker
  #everyone_not_home: everyone_not_home
  #everyone_home: everyone_home
  #somebody_is_home: somebody_is_home
  depart_check_time: 30
  depart_scans: 3
  minimum_confidence: 60
  not_home_timeout: 15
  system_check: 30
  system_timeout: 60
  home_gateway_sensors:
    - binary_sensor.main_door_contact

  gateway_scan_interval_delay: 180 # wait for 3 minutes
  gateway_scan_interval: 60 # if after 3 minutes gateway still opended, scan every 1 minute
  
  # reboot the all nodes at 12 midnight on Mondays and Thursdays
  scheduled_restart:
    time: 00:00:01
    days:
      - mon
      - thu
    location: all

  # other location configuration options
    #location: living_room, kitchen

    #location:
    # - living_room
    # - kitchen

  home_motion_sensors:
    - binary_sensor.living_room_motion_sensor_occupancy
    - binary_sensor.kitchen_motion_sensor_occupancy
    - binary_sensor.hallway_motion_sensor_occupancy
    
  #log_level: DEBUG
  known_devices:
    - xx:xx:xx:xx:xx:xx Odianosen's iPhone
    - xx:xx:xx:xx:xx:xx Nkiruka's iPad
  
  known_beacons:
    - xx:xx:xx:xx:xx:xx Odianosen's Car Keys
  
  remote_monitors:
    disable: False
    kitchen:
      auto_reboot_when_offline: True
      host: !secret kitchen_monitor_host
      username: !secret kitchen_monitor_username
      password: !secret kitchen_monitor_password
    
    living_room:
      host: 192.168.1.xxx
      username: !secret living_room_monitor_username
      password: !secret living_room_monitor_password
      reboot_command: sudo /sbin/reboot now
      auto_reboot_when_offline: True
      time: 02:00:01

App Configuration

keyoptionaltypedefaultdescription
moduleFalsestringhome_presence_appThe module name of the app.
classFalsestringHomePresenceAppThe name of the Class.
pluginTruelistThe plugins at if restarted, the app should restart.
monitor_topicTruestringmonitorThe top topic level used by the monitor system. This is also used as the domain for service call
mqtt_eventTruestringMQTT_MESSAGEThe event name, used by the MQTT plugin to send data to the app.
user_device_domainTruestringbinary_sensorThe domain to be used for the sensors generated by the app for each device.
everyone_homeTruestringeveryone_homeBinary sensor name to be used, to indicate everyone is home.
everyone_not_homeTruestringeveryone_not_homeBinary sensor name to be used, to indicate everyone is not home.
somebody_is_homeTruestringsomebody_is_homeBinary sensor name to be used, to indicate someone is home.
depart_check_timeTrueint30Delay in seconds, before depart scan is ran. This depends on how long it takes the user to leave the door and not being picked up by a monitor node.
depart_scansTrueint3The number of times the depart scans should be ran. This useful for those that spend some time within areas the system can still pick them up, even though they have left the house.
minimum_confidenceTrueint50Minimum confidence required across all nodes, for a device to be considered departed.
not_home_timeoutTrueint15Time in seconds a device has to be considered away, before registering it deaprted by the app.
system_checkTrueint30Time in seconds, for the app to check the availability of each monitor node.
system_timeoutTrueint60Time in seconds, for a monitor node not to respond to system check for it to be considered offline.
scheduled_restartTruedictA dictionary specifing the time as str in HH:MM:SS format, first 3 letters of the days as a list and locations as list or str the app should restart the nodes on the network. If remote_monitors specified and disabled is not True, it will lead to a reboot of the node's hardware as specified in location. If no location is specified, it will only restart the script.
remote_monitorsTruedictThe names (locations), login details (host, username and password) optional reboot_command which defaults to sudo reboot now of the nodes to be rebooted. Also a parameter auto_reboot_when_offline can be added, which instructs the app if to reboot the node when offline, and what time to be auto rebooted. If disable is True, the app will not be able to reboot any nodes defined.
home_gateway_sensorsTruelistList of gateway sensors, which can be used by the app to instruct the nodes based on their state if to run a arrive/depart scan. If all home, only depart scan is ran. If all away, arrive scan is ran, and if neither both scans are ran. This accepts any kind of entity, and not limited to binary_sensors
gateway_scan_interval_delayNoneintIf the app is set to scan continously over a given time if any of the gateways are opened, this is used to set the time in seconds for it to wait, before carrying out the scans
gateway_scan_intervalNoneintThis is used to instruct the app to keep running scans, while a gateway is opened. This can be useful if living in a space that keeps the door or something opened for a long time
home_motion_sensorsTruelistList of motion sensors, which can be used by the app to instruct the nodes based on their state if to run rssi scan.
known_devicesTruelistList of known devices that are to be loaded into all the nodes on the network
known_beaconsTruelistList of known beacons that data received from them by the app from the nodes, are to be processed by the app
log_levelTrue'INFO' | 'DEBUG''INFO'Switches log level.

Service Calls:

This app supports the use of some service calls, which can be useful if wanting to use execute some commands in the app from other AD apps. The domain of the service calls, depends on what is specified as the monitor_topic. An example service call is

self.call_service("monitor/remove_known_device", device="xx:xx:xx:xx:xx:xx", namespace=mqtt)

The domain is determined by the specified monitor_topic. Below is listed the supported service calls

remove_known_device

Used to remove a known device from all the nodes. The device's MAC address should be supplied in the service call

self.call_service("monitor/remove_known_device", device="xx:xx:xx:xx:xx:xx", namespace=mqtt)

run_arrive_scan

Used to instruct the app to execute an arrival scan on all nodes

self.call_service("presence/run_arrive_scan", namespace=mqtt)

run_depart_scan

Used to instruct the app to execute a depart scan on all nodes. If wanting to execute it immediately, pass a parameter scan_delay=0 in the call. If not, the defined depart_check_time will be used as the delay before running the scan

# run depart scan in 10 seconds time
self.call_service("presence/run_depart_scan", scan_delay=10, namespace=mqtt)

run_rssi_scan

Used to instruct the app to execute an rssi scan on all nodes

self.call_service("monitor/run_rssi_scan", namespace=mqtt)

restart_device

Used to instruct the app to execute a restart of the monitor script on all nodes. If a node has its login detail in remote_monitors it will attempt to reboot the hardware itself. To reboot a particular node in a location, specify the location parameter. This same location, should be used in defining the node's login details in remote_monitors

# restart the monitor scripts in all nodes
self.call_service("monitor/restart_device", namespace=mqtt)

# reboot the node in the living room's hardware
self.call_service("monitor/restart_device", location="living_room", namespace=mqtt)

reload_device_state

Used to instruct the app to have the nodes report the state of their devices

self.call_service("presence/reload_device_state", namespace=mqtt)

load_known_devices

Used to instruct the app to have the nodes setup the known devices as specified in the app's configuration

self.call_service("presence/load_known_devices", namespace=mqtt)

clear_location_entities

Used to instruct the app to set all entities in a predefined location to 0, indicating that no device is seen by that node. The location parameter must be specified

self.call_service("monitor/clear_location_entities", location="hallway", namespace=mqtt)

clean_devices

Used to instruct the app to clean up old known devices. This is always ran at start-up, so technically should not be a need to be manually ran

self.call_service("monitor/clean_devices", namespace=mqtt)

MQTT Commands:

This app supports the ability to send commands to it over MQTT. This can be very useful, if wanting to execute specific functions from an external system like HA or any hub that supports MQTT. Outline below are the supported MQTT topics and the payload commands:

monitor/run_scan

This topic is listened to by the app, and when a message is received it will execute the required command. Supported commands on this topic are as follows

monitor/location/reboot

This topic is used by the app to reboot a remote monitor node. The location parmeter can be a any of the declared nodes in remote_monitors. So if wanting to say reboot only the living room's node, simply send an empty payload to monitor/living_room/reboot. if the location is all, that is an empty payload is sent to monitor/all/reboot, this will reboot all the declared remote_monitor nodes.

RSSI Tracking:

Within this app, RSSI tracking is also updated regularly on the AppDaemon based entities. I personally use this, for rudimentary home area tracking, aided with the use of motion sensors within the home. To use this feature, it is advised that all monitor systems are setup as monitor.sh -tad -a -b and the PREF_MQTT_REPORT_SCAN_MESSAGES should be set to true in preferences. I also found using this rssi scans only based on motion sensors, does help in keeping my systems reported state updated, with as minimal scans as possible; for example no need scanning at night, when all are sleeping. I am not advising the get motion sensors for this, but in my home I already had motion sensors for lights. So felt I may as well integrate it to improve on reliability.

Hardware Rebooting (WARNING):

This is a feature which allows the app to remotely reboot a node's hardware, and not just the script it is running. It must be noted to make use of this, an external python package in the requirements.txt file most be installed. If using Hass.io, do add it to your python_pakages list in the config. If running on a standalone Linux system and not using the supplied script above, simply run pip3 install -r requirements.txt should install it; depending on which user is running AD. Care should be taken when using this feature, as any device with its details specified within the remote_monitors can be rebooted by the app. The hardware within which this app is running, should never be added to the list. Below is listed the conditions that can lead to a hardware reboot:

It is advisable not to use

<a href="https://www.buymeacoffee.com/cm5bhML" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-black.png" width="200px" height="50px" alt="Buy Me A Coffee" style="height: 35px !important;width: 150px !important;" ></a>