Merge pull request #9 from bpowers/bpowers/local-sensors-api

ahayworth · web-flow · commit 78607e71546b · 2020-09-16T11:35:45.000-05:00
local sensors API support
diff --git a/.gitignore b/.gitignore
@@ -104,3 +104,6 @@ venv.bak/
 .mypy_cache/
 
 script/
+
+# PyCharm/IntelliJ project directory
+/.idea
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -140,3 +140,61 @@ Fetching data from a different time
           print(f"{sensor}: {round(value, 2)}")
           if sensor in datum.indices:
             print(f"  awair index: {datum.indices[sensor]}")
+
+Sample local sensors program
+=================================
+
+Awair recently added the `local sensors API`_, where you can retrieve current (and only current)
+air data from devices on your local network over HTTP.
+
+.. _`local sensors API`: https://docs.google.com/document/d/1001C-ro_ig7aEyz0GiWUiiJn0M6DLj47BYWj31acesg/edit
+
+.. code:: python
+
+  import asyncio
+  import aiohttp
+  from python_awair import AwairLocal
+
+  async def data():
+      async with aiohttp.ClientSession() as session:
+          # Instantiate a client with your access token, and an asyncio session:
+          client = AwairLocal(
+              session=session, device_addrs=["AWAIR-ELEM-1419E1.local"]
+          )
+
+          # List the local devices:
+          devices = await client.devices()
+
+          # Get some air quality data for a user's device:
+          data = await devices[0].air_data_latest()
+
+          # Print things out!
+          print(f"Device: {devices[0]}")
+
+          # You can access sensors as dict items:
+          for sensor, value in data.sensors.items():
+              print(f"  {sensor}: {round(value, 2)}")
+
+          # Or, as attributes:
+          print(f"  temperature again: {round(data.sensors.temperature, 2)}")
+
+  asyncio.run(data())
+
+Running this sample prints::
+
+  $ python awair_local_demo.py
+  Device: <AwairDevice: uuid=awair-element_5366 model=Awair Element>
+    dew_point: 10.81
+    abs_humid: 9.59
+    co2_est: 461
+    voc_baseline: 2536742680
+    voc_h2_raw: 27
+    voc_ethanol_raw: 39
+    pm10_est: 3
+    temperature: 19.16
+    humidity: 58.46
+    carbon_dioxide: 438
+    volatile_organic_compounds: 384
+    particulate_matter_2_5: 2
+    temperature again: 19.16
+
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-awair"
-version = "0.1.1"
+version = "0.2.0"
 description = "asyncio client for the Awair GraphQL API"
 authors = ["Andrew Hayworth <ahayworth@gmail.com>"]
 license = "MIT"
@@ -61,8 +61,8 @@ commands = poetry run pytest {posargs}
 whitelist_externals = poetry
 commands =
   poetry run black . --check
-  poetry run isort -c
-  poetry run flake8
+  poetry run isort --check python_awair/ tests/
+  poetry run flake8 python_awair/ tests/
   poetry run pylint python_awair/ tests/
   poetry run mypy python_awair/ tests/
 
diff --git a/python_awair/__init__.py b/python_awair/__init__.py
@@ -10,13 +10,15 @@
 .. _`developer console`: https://developer.getawair.com
 """
 
-from typing import Optional
+from asyncio import gather
+from typing import List, Optional
 
 from aiohttp import ClientSession
 
 from python_awair import const
 from python_awair.auth import AccessTokenAuth, AwairAuth
 from python_awair.client import AwairClient
+from python_awair.devices import AwairLocalDevice
 from python_awair.exceptions import AwairError
 from python_awair.user import AwairUser
 
@@ -69,3 +71,39 @@ async def user(self) -> AwairUser:
         """
         response = await self.client.query(const.USER_URL)
         return AwairUser(client=self.client, attributes=response)
+
+
+class AwairLocal:
+    """Entry class for the local sensors Awair API."""
+
+    client: AwairClient
+    """AwairClient: The instantiated AwairClient
+        that will be used to fetch API responses and
+        check for HTTP errors.
+    """
+
+    _device_addrs: List[str]
+    """IP or DNS addresses of Awair devices with the local sensors API enabled."""
+
+    def __init__(self, session: ClientSession, device_addrs: List[str]) -> None:
+        """Initialize the Awair local sensors API wrapper."""
+        self._device_addrs = device_addrs
+        if len(device_addrs) > 0:
+            self.client = AwairClient(AccessTokenAuth(""), session)
+        else:
+            raise AwairError("No local Awair device addresses supplied!")
+
+    async def devices(self) -> List[AwairLocalDevice]:
+        """Return a list of local awair devices."""
+        responses = await gather(
+            *(
+                self.client.query(f"http://{addr}/settings/config/data")
+                for addr in self._device_addrs
+            )
+        )
+        return [
+            AwairLocalDevice(
+                client=self.client, device_addr=self._device_addrs[i], attributes=device
+            )
+            for i, device in enumerate(responses)
+        ]
diff --git a/python_awair/devices.py b/python_awair/devices.py
@@ -1,8 +1,9 @@
 """Class to describe an Awair device."""
 
 import urllib
+from abc import ABC, abstractmethod
 from datetime import datetime, timedelta
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union, cast
 
 import voluptuous as vol
 
@@ -13,7 +14,7 @@
 AirDataParam = Union[datetime, bool, int, None]
 
 
-class AwairDevice:
+class AwairBaseDevice(ABC):
     """An Awair device.
 
     This class serves two purposes - it provides metadata about
@@ -336,17 +337,25 @@ async def air_data_raw(self, **kwargs: AirDataParam) -> List[AirData]:
         """
         return await self.__get_airdata("raw", **kwargs)
 
+    @abstractmethod
+    def _get_airdata_base_url(self) -> str:
+        """Get the base URL to use for airdata."""
+        raise TypeError("expected subclass to define override")
+
+    @abstractmethod
+    def _extract_airdata(self, response: Any) -> List[Any]:
+        """Get the data object out of a response."""
+        raise TypeError("expected subclass to define override")
+
     async def __get_airdata(self, kind: str, **kwargs: AirDataParam) -> List[AirData]:
         """Call one of several varying air-data API endpoints."""
-        url = "/".join(
-            [const.DEVICE_URL, self.device_type, str(self.device_id), "air-data", kind]
-        )
+        url = "/".join([self._get_airdata_base_url(), "air-data", kind])
 
         if kwargs is not None:
             url += self._format_args(kind, **kwargs)
 
         response = await self.client.query(url)
-        return [AirData(data) for data in response.get("data", [])]
+        return [AirData(data) for data in self._extract_airdata(response)]
 
     @staticmethod
     def _format_args(kind: str, **kwargs: AirDataParam) -> str:
@@ -407,3 +416,70 @@ def validate_hours(params: Dict[str, Any]) -> Dict[str, Any]:
             return "?" + urllib.parse.urlencode(args)
 
         return ""
+
+
+class AwairDevice(AwairBaseDevice):
+    """A cloud-based Awair device."""
+
+    def _get_airdata_base_url(self) -> str:
+        """Get the base URL to use for airdata."""
+        return "/".join([const.DEVICE_URL, self.device_type, str(self.device_id)])
+
+    def _extract_airdata(self, response: Any) -> List[Any]:
+        """Get the data object out of a response."""
+        return cast(List[Any], response.get("data", []))
+
+
+class AwairLocalDevice(AwairBaseDevice):
+    """A local Awair device."""
+
+    device_addr: str
+    """The DNS or IP address of the device."""
+
+    def __init__(
+        self, client: AwairClient, device_addr: str, attributes: Dict[str, Any]
+    ):
+        """Initialize an awair local device from API attributes."""
+        # the format of the config endpoint for local sensors is different than
+        # the cloud API.
+        device_uuid: str = attributes["device_uuid"]
+        [device_type, device_id_str] = device_uuid.split("_", 1)
+        device_id = int(device_id_str)
+        attributes["deviceId"] = device_id
+        attributes["deviceUUID"] = device_uuid
+        attributes["deviceType"] = device_type
+        attributes["macAddress"] = attributes.get("wifi_mac", None)
+        super().__init__(client, attributes)
+        self.device_addr = device_addr
+
+    def _get_airdata_base_url(self) -> str:
+        """Get the base URL to use for airdata."""
+        return f"http://{self.device_addr}"
+
+    def _extract_airdata(self, response: Any) -> List[Any]:
+        """Get the data object out of a response."""
+        # reformat local sensors response to match the cloud API
+        top_level = {"timestamp", "score"}
+        sensors = [
+            {"comp": k, "value": response[k]}
+            for k in response.keys()
+            if k not in top_level
+        ]
+        data = {
+            "timestamp": response["timestamp"],
+            "score": response["score"],
+            "sensors": sensors,
+        }
+
+        return [data]
+
+    @staticmethod
+    def _format_args(kind: str, **kwargs: AirDataParam) -> str:
+        if "fahrenheit" in kwargs:
+            if kwargs["fahrenheit"]:
+                raise ValueError("fahrenheit is not supported for local sensors yet")
+            # if we pass any URL parameters with local sensors, it causes the
+            # timestamp to be the empty string.
+            del kwargs["fahrenheit"]
+
+        return AwairBaseDevice._format_args(kind, **kwargs)
diff --git a/tests/const.py b/tests/const.py
@@ -30,3 +30,13 @@
     "deviceUUID": "awair-glow_1405",
 }
 MOCK_USER_ATTRS = {"id": "32406"}
+MOCK_ELEMENT_DEVICE_A_ATTRS = {
+    "deviceId": 6049,
+    "deviceType": "awair-element",
+    "deviceUUID": "awair-element_6049",
+}
+MOCK_ELEMENT_DEVICE_B_ATTRS = {
+    "deviceId": 5366,
+    "deviceType": "awair-element",
+    "deviceUUID": "awair-element_5366",
+}
diff --git a/tests/fixtures/cassettes/latest_local.yaml b/tests/fixtures/cassettes/latest_local.yaml
@@ -0,0 +1,48 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Content-Type:
+      - application/json
+      authorization:
+      - fake_token
+    method: GET
+    uri: http://awair-elem-1419e1.local/settings/config/data
+  response:
+    body:
+      string: '{"device_uuid":"awair-element_5366","wifi_mac":"70:88:6B:14:19:E1","ssid":"morpac-east","ip":"192.168.1.225","netmask":"255.255.255.0","gateway":"none","fw_version":"1.1.5","timezone":"America/Los_Angeles","display":"co2","led":{"mode":"manual","brightness":73},"voc_feature_set":"Unknown"}'
+    headers:
+      Access-Control-Allow-Origin: '*'
+      Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
+      Connection: Keep-Alive
+      Content-Type: application/json
+      Pragma: no-cache
+      Transfer-Encoding: chunked
+    status:
+      code: 200
+      message: OK
+    url: http://awair-elem-1419e1.local/settings/config/data
+- request:
+    body: null
+    headers:
+      Content-Type:
+      - application/json
+      authorization:
+      - fake_token
+    method: GET
+    uri: http://awair-elem-1419e1.local/air-data/latest
+  response:
+    body:
+      string: '{"timestamp":"2020-08-31T22:07:03.831Z","score":93,"dew_point":11.11,"temp":19.59,"humid":58.05,"abs_humid":9.77,"co2":408,"co2_est":400,"voc":159,"voc_baseline":2533859097,"voc_h2_raw":28,"voc_ethanol_raw":40,"pm25":2,"pm10_est":3}'
+    headers:
+      Access-Control-Allow-Origin: '*'
+      Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
+      Connection: Keep-Alive
+      Content-Type: application/json
+      Pragma: no-cache
+      Transfer-Encoding: chunked
+    status:
+      code: 200
+      message: OK
+    url: http://awair-elem-1419e1.local/air-data/latest
+version: 1
diff --git a/tests/fixtures/cassettes/local_devices.yaml b/tests/fixtures/cassettes/local_devices.yaml
@@ -0,0 +1,48 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Content-Type:
+      - application/json
+      authorization:
+      - fake_token
+    method: GET
+    uri: http://awair-elem-1416dc.local/settings/config/data
+  response:
+    body:
+      string: '{"device_uuid":"awair-element_6049","wifi_mac":"70:88:6B:14:16:DC","ssid":"morpac-east","ip":"192.168.1.133","netmask":"255.255.255.0","gateway":"none","fw_version":"1.1.5","timezone":"America/Los_Angeles","display":"clock","led":{"mode":"auto","brightness":179},"voc_feature_set":"Unknown"}'
+    headers:
+      Access-Control-Allow-Origin: '*'
+      Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
+      Connection: Keep-Alive
+      Content-Type: application/json
+      Pragma: no-cache
+      Transfer-Encoding: chunked
+    status:
+      code: 200
+      message: OK
+    url: http://awair-elem-1416dc.local/settings/config/data
+- request:
+    body: null
+    headers:
+      Content-Type:
+      - application/json
+      authorization:
+      - fake_token
+    method: GET
+    uri: http://awair-elem-1419e1.local/settings/config/data
+  response:
+    body:
+      string: '{"device_uuid":"awair-element_5366","wifi_mac":"70:88:6B:14:19:E1","ssid":"morpac-east","ip":"192.168.1.225","netmask":"255.255.255.0","gateway":"none","fw_version":"1.1.5","timezone":"America/Los_Angeles","display":"co2","led":{"mode":"manual","brightness":73},"voc_feature_set":"Unknown"}'
+    headers:
+      Access-Control-Allow-Origin: '*'
+      Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
+      Connection: Keep-Alive
+      Content-Type: application/json
+      Pragma: no-cache
+      Transfer-Encoding: chunked
+    status:
+      code: 200
+      message: OK
+    url: http://awair-elem-1419e1.local/settings/config/data
+version: 1
diff --git a/tests/test_python_awair.py b/tests/test_python_awair.py
