Initial commit

Author: thus

.gitignore

@@ -0,0 +1 @@
+*.swp

README.md

@@ -0,0 +1,82 @@
+# Tracker
+
+Device tracking for home automation (e.g home assistant), running as an external
+service, and reporting status to a MQTT broker.
+
+Tracking is configured per device, using a set of pre-defined modules. As of
+now, only the *deepsleep* module is implemented.
+
+![Image of Tracker from Paw Patrol](images/tracker.png)
+
+*(Image source: https://pawpatrol.fandom.com/wiki/Tracker)*
+
+## Modules
+
+### Deepsleep
+
+This module works by sending a UDP packet on port 5353 (used by multicast DNS)
+with whatever payload to a device, and then checking the host machines ARP table
+to see if it contains an entry for the device we are tracking.
+
+This module enables us to track newer iPhones, which are hard to track, since
+they disconnect from WiFi when the screen is locked. This method probably works
+for other devices as well.
+
+This module basically uses the same detection strategy as implemented by Magnus
+Nyström (mudape) in [iphonedetect](https://github.com/mudape/iphonedetect).
+I had to do my own implementation, since I wanted to track devices on an other
+subnet then the Home Assistant server, which would not work with iphonedetect,
+since the server was not getting ARP table entries for the devices.
+
+## Use together with Home Assistant
+
+### Install Mosquitto broker
+In this example, we use the Mosquitto MQTT broker from the Home Assistant add-on
+store. Feel free to use any MQTT broker you like.
+
+Start by installing the Mosquitto broker from the add-on store and add a local
+user to the configuration file (Supervisor → Mosquitto broker → Configuration),
+e.g:
+
+```yaml
+logins:
+  - username: tracker
+    password: some-awesome-random-generated-password
+```
+
+The broker needs to be restarted before we are able to log in with the new user.
+
+### Add device_tracker config to configuration.yaml
+
+To actually track the device, we have to add some configuration to
+/config/configuration.yaml (or maybe in another location if HASSOS is not used).
+This can be done using SSH or using the *File Editor* add-on.
+
+The following configuration tracks the device *my_iphone* using the
+*tracker/location/my_iphone* MQTT topic:
+
+```yaml
+device_tracker:
+  - platform: mqtt
+    devices:
+      my_iphone: tracker/location/my_iphone
+```
+
+Home Assistant should be restarted after modifying *configuration.yaml*.
+
+This means that every time Tracker publishes something on that MQTT topic, it is
+picked up by Home Assistant.
+
+### Configure Tracker
+
+The following should be added to the configuration file of Tracker (default
+path: */etc/tracker.yaml*) to track the device configured in the previous step:
+
+```yaml
+device_track:
+  - my_iphone:
+    module: deepsleep
+    ip: 1.2.3.4  # add the IP address of your device here
+```
+
+Now start Tracker to start tracking your device.

example.yaml

@@ -0,0 +1,51 @@
+# Example configuration file for Tracker
+---
+
+# Configure logging (uses logging.config.dictConfig)
+logging:
+  version: 1
+  formatters:
+    standard:
+      format: '%(asctime)s (%(levelname)s) %(message)s'
+  handlers:
+    default:
+      class: logging.StreamHandler
+      level: INFO
+      formatter: standard
+  loggers:
+    '':
+      level: INFO
+      handlers:
+        - default
+
+# Default state
+state:
+  home: "home"
+  not_home: "not_home"
+
+# Default module config
+module:
+  deepsleep:
+    # How often to check device (in seconds)
+    interval: 5
+
+    # When a iPhone is locked we often have to try multiple times before
+    # we get an answer.
+    max_retries: 10
+
+    # How to long to wait between the retries (in seconds)
+    retry_interval: 2
+
+# MQTT config
+mqtt:
+  broker: "mqtt.local"
+  port: 1883
+  username: "tracker"
+  password: "some-awesome-random-generated-password"
+  topic_prefix: "tracker/location/"
+
+# List of devices to track
+device_track:
+  - my_iphone:
+      module: deepsleep
+      ip: 1.2.3.4

images/tracker.png

@@ -0,0 +1 @@
+-r requirements/prod.txt

requirements.txt

@@ -0,0 +1 @@
+-r prod.txt

requirements/dev.txt

@@ -0,0 +1,3 @@
+paho-mqtt
+PyYAML
+pyroute2

requirements/prod.txt

@@ -0,0 +1,3 @@
+-r prod.txt
+
+pytest

requirements/test.txt

@@ -0,0 +1,23 @@
+try:
+    from setuptools import setup
+except ImportError:
+    from distutils.core import setup
+
+
+setup(
+    name='tracker',
+    version='1.0.0',
+    description="Device tracking for home automation",
+    author="Mats Klepsland",
+    author_email='mats.klepsland@gmail.com',
+    packages=[
+        'tracker',
+    ],
+    package_dir={'tracker':
+                 'tracker'},
+    include_package_data=True,
+    install_requires=[],
+    zip_safe=False,
+    keywords='tracker',
+    test_suite='tests',
+)

setup.py

@@ -0,0 +1,36 @@
+"""
+Copyright (C) 2020 Mats Klepsland <mats.klepsland@gmail.com>
+
+This file is part of Tracker.
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <http://www.gnu.org/licenses/>.
+"""
+
+import argparse
+
+DEFAULT_CONFIG_FILE = "/etc/tracker.yaml"
+
+
+def read_args():
+    """Read command-line arguments.
+
+    Returns:
+      Parsed arguments.
+
+    """
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-c", "--config-file",
+                        default=DEFAULT_CONFIG_FILE, metavar="FILE")
+    args = parser.parse_args()
+
+    return args

tracker/__init__.py

@@ -0,0 +1,119 @@
+"""
+Copyright (C) 2020 Mats Klepsland <mats.klepsland@gmail.com>
+
+This file is part of Tracker.
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <http://www.gnu.org/licenses/>.
+"""
+
+import sys
+import yaml
+
+DEFAULT_STATE_HOME = "home"
+DEFAULT_STATE_NOT_HOME = "not_home"
+DEFAULT_MQTT_BROKER = "localhost"
+DEFAULT_MQTT_PORT = "1833"
+DEFAULT_MQTT_TOPIC_PREFIX = "tracker/location/"
+
+
+def _dict_nested_set(d, keys, value):
+    """Set a nested key in a dictionary.
+
+    Args:
+      d (dict):    The dictionary.
+      keys (list): The nested key.
+      value:       The value to set the key to.
+
+    """
+    for key in keys[:-1]:
+        d = d.setdefault(key, {})
+    d[keys[-1]] = value
+
+
+def _dict_nested_isset(d, keys):
+    """Check if nested key is set in dictionary.
+
+    Args:
+      d (dict):    The dictionary.
+      keys (list): The nested key.
+
+    Returns:
+      True if key is set, False otherwise.
+
+    """
+    _d = d
+
+    for key in keys:
+        try:
+            _d = _d[key]
+        except KeyError:
+            return False
+
+    return True
+
+
+def config_apply_defaults(conf):
+    """Apply defaults to the config where key is not set.
+
+    Args:
+      conf (dict): The loaded config.
+
+    Returns:
+      Dictionary containing config, with added defaults.
+
+    """
+
+    if not _dict_nested_isset(conf, ["state", "home"]):
+        _dict_nested_set(conf, ["state", "home"], DEFAULT_STATE_HOME)
+
+    if not _dict_nested_isset(conf, ["state", "not_home"]):
+        _dict_nested_set(conf, ["state", "not_home"], DEFAULT_STATE_NOT_HOME)
+
+    if not _dict_nested_isset(conf, ["mqtt", "broker"]):
+        _dict_nested_set(conf, ["mqtt", "broker"], DEFAULT_MQTT_BROKER)
+
+    if not _dict_nested_isset(conf, ["mqtt", "port"]):
+        _dict_nested_set(conf, ["mqtt", "port"], DEFAULT_MQTT_PORT)
+
+    if not _dict_nested_isset(conf, ["mqtt", "topic_prefix"]):
+        _dict_nested_set(conf, ["mqtt", "topic_prefix"],
+                         DEFAULT_MQTT_TOPIC_PREFIX)
+
+    return conf
+
+
+def config_load(config_file):
+    """Load configuration file (YAML).
+
+    Args:
+      config_file (str): Configuration file.
+
+    Returns:
+      Dictionary containing config.
+
+    """
+    try:
+        with open(config_file, "r") as f:
+            conf = yaml.safe_load(f)
+    except yaml.YAMLError as ex:
+        sys.exit("ERROR: could not parse config file '%s': %s" %
+                 (config_file, ex))
+    except FileNotFoundError:
+        sys.exit("ERROR: could not find config file '%s'" % config_file)
+
+    config_apply_defaults(conf)
+
+    if "device_track" not in conf:
+        sys.exit("Config does not contain any devices to track. Exiting.")
+
+    return conf