Merge pull request #650 from perdue/perdue/feature/add_local_storage_api_support

Add support for the local storage API

Author: fronzbot

.gitignore

@@ -15,3 +15,5 @@ docs/_build
 *.log
 venv
 .session*
+Pipfile
+Pipfile.lock

README.rst

@@ -183,6 +183,45 @@ Example usage, which downloads all videos recorded since July 4th, 2018 at 9:34a
     blink.download_videos('/home/blink', since='2018/07/04 09:34', delay=2)
 
 
+Sync Module Local Storage
+=========================
+
+Description of how I think the local storage API is used by Blink
+-----------------------------------------------------------------
+
+Since local storage is within a customer's residence, there are no guarantees for latency
+and availability.  As a result, the API seems to be built to deal with these conditions.
+
+In general, the approach appears to be this:  The Blink app has to query the sync
+module for all information regarding the stored clips.  On a click to view a clip, the app asks
+for the full list of stored clips, finds the clip in question, uploads the clip to the
+cloud, and then downloads the clip back from a cloud URL. Each interaction requires polling for
+the response since networking conditions are uncertain.  The app also caches recent clips and the manifest.
+
+API steps
+---------
+1. Request the local storage manifest be created by the sync module.
+
+   * POST **{base_url}/api/v1/accounts/{account_id}/networks/{network_id}/sync_modules/{sync_id}/local_storage/manifest/request**
+   * Returns an ID that is used to get the manifest.
+
+2. Retrieve the local storage manifest.
+
+   * GET **{base_url}/api/v1/accounts/{account_id}/networks/{network_id}/sync_modules/{sync_id}/local_storage/manifest/request/{manifest_request_id}**
+   * Returns full manifest.
+   * Extract the manifest ID from the response.
+
+3. Find a clip ID in the clips list from the manifest to retrieve, and request an upload.
+
+   * POST **{base_url}/api/v1/accounts/{account_id}/networks/{network_id}/sync_modules/{sync_id}/local_storage/manifest/{manifest_id}/clip/request/{clip_id}**
+   * When the response is returned, the upload has finished.
+
+4. Download the clip using the same clip ID.
+
+   * GET **{base_url}/api/v1/accounts/{account_id}/networks/{network_id}/sync_modules/{sync_id}/local_storage/manifest/{manifest_id}/clip/request/{clip_id}**
+
+
+
 .. |Build Status| image:: https://github.com/fronzbot/blinkpy/workflows/build/badge.svg
    :target: https://github.com/fronzbot/blinkpy/actions?query=workflow%3Abuild
 .. |Coverage Status| image:: https://codecov.io/gh/fronzbot/blinkpy/branch/dev/graph/badge.svg

blinkpy/api.py

@@ -1,8 +1,13 @@
 """Implements known blink API calls."""
 
 import logging
+import string
 from json import dumps
-from blinkpy.helpers.util import get_time, Throttle
+from blinkpy.helpers.util import (
+    get_time,
+    Throttle,
+    local_storage_clip_url_template,
+)
 from blinkpy.helpers.constants import DEFAULT_URL, TIMEOUT, DEFAULT_USER_AGENT
 
 _LOGGER = logging.getLogger(__name__)
@@ -21,7 +26,8 @@ def request_login(
 
     :param auth: Auth instance.
     :param url: Login url.
-    :login_data: Dictionary containing blink login data.
+    :param login_data: Dictionary containing blink login data.
+    :param is_retry:
     """
     headers = {
         "Host": DEFAULT_URL,
@@ -296,9 +302,58 @@ def request_motion_detection_disable(blink, network, camera_id):
     return http_post(blink, url)
 
 
-def http_get(blink, url, stream=False, json=True, is_retry=False, timeout=TIMEOUT):
+def request_local_storage_manifest(blink, network, sync_id):
+    """Request creation of an updated manifest of video clips stored in sync module local storage.
+
+    :param blink: Blink instance.
+    :param network: Sync module network id.
+    :param sync_id: ID of sync module.
     """
-    Perform an http get request.
+    url = (
+        f"{blink.urls.base_url}/api/v1/accounts/{blink.account_id}/networks/{network}/sync_modules/{sync_id}"
+        + "/local_storage/manifest/request"
+    )
+    return http_post(blink, url)
+
+
+def get_local_storage_manifest(blink, network, sync_id, manifest_request_id):
+    """Request manifest of video clips stored in sync module local storage.
+
+    :param blink: Blink instance.
+    :param network: Sync module network id.
+    :param sync_id: ID of sync module.
+    :param manifest_request_id: Request ID of local storage manifest (requested creation of new manifest).
+    """
+    url = (
+        f"{blink.urls.base_url}/api/v1/accounts/{blink.account_id}/networks/{network}/sync_modules/{sync_id}"
+        + f"/local_storage/manifest/request/{manifest_request_id}"
+    )
+    return http_get(blink, url)
+
+
+def request_local_storage_clip(blink, network, sync_id, manifest_id, clip_id):
+    """Prepare video clip stored in the sync module to be downloaded.
+
+    :param blink: Blink instance.
+    :param network: Sync module network id.
+    :param sync_id: ID of sync module.
+    :param manifest_id: ID of local storage manifest (returned in the manifest response).
+    :param clip_id: ID of the clip.
+    """
+    url = blink.urls.base_url + string.Template(
+        local_storage_clip_url_template()
+    ).substitute(
+        account_id=blink.account_id,
+        network_id=network,
+        sync_id=sync_id,
+        manifest_id=manifest_id,
+        clip_id=clip_id,
+    )
+    return http_post(blink, url)
+
+
+def http_get(blink, url, stream=False, json=True, is_retry=False, timeout=TIMEOUT):
+    """Perform an http get request.
 
     :param url: URL to perform get request.
     :param stream: Stream response? True/FALSE
@@ -317,8 +372,7 @@ def http_get(blink, url, stream=False, json=True, is_retry=False, timeout=TIMEOU
 
 
 def http_post(blink, url, is_retry=False, data=None, json=True, timeout=TIMEOUT):
-    """
-    Perform an http post request.
+    """Perform an http post request.
 
     :param url: URL to perfom post request.
     :param is_retry: Is this part of a re-auth attempt?

blinkpy/blinkpy.py

@@ -16,6 +16,7 @@
 import os.path
 import time
 import logging
+import datetime
 from shutil import copyfileobj
 
 from requests.structures import CaseInsensitiveDict
@@ -88,12 +89,17 @@ def refresh(self, force=False, force_cache=False):
                 self.setup_post_verify()
 
             self.get_homescreen()
+
             for sync_name, sync_module in self.sync.items():
-                _LOGGER.debug("Attempting refresh of sync %s", sync_name)
+                _LOGGER.debug("Attempting refresh of blink.sync['%s']", sync_name)
                 sync_module.refresh(force_cache=(force or force_cache))
+
             if not force_cache:
                 # Prevents rapid clearing of motion detect property
                 self.last_refresh = int(time.time())
+                last_refresh = datetime.datetime.fromtimestamp(self.last_refresh)
+                _LOGGER.debug(f"last_refresh={last_refresh}")
+
             return True
         return False
 
@@ -114,6 +120,15 @@ def start(self):
             if self.auth.no_prompt:
                 return True
             self.setup_prompt_2fa()
+
+        if not self.last_refresh:
+            # Initialize last_refresh to be just before the refresh delay period.
+            self.last_refresh = int(time.time() - self.refresh_rate * 1.05)
+            _LOGGER.debug(
+                f"Initialized last_refresh to {self.last_refresh} == "
+                + f"{datetime.datetime.fromtimestamp(self.last_refresh)}"
+            )
+
         return self.setup_post_verify()
 
     def setup_prompt_2fa(self):