Merge branch 'api-v2' into v2-examples

Author: brentru

.travis.yml

@@ -0,0 +1,23 @@
+# .travis.yml for Adafruit IO Python Client Library
+
+dist: trusty
+sudo: false
+language: python
+python:
+    - "3.6"
+
+cache:
+    pip: true
+
+install:
+  - pip install pylint Sphinx sphinx-rtd-theme
+
+script:
+  # test adafruit_io_basics examples
+  - pylint --disable=missing-docstring,invalid-name examples/aio_basics/*.py
+  # test API examples
+   pylint --disable=missing-docstring,invalid-name examples/api/*.py
+   # test MQTT examples
+    pylint --disable=missing-docstring,invalid-name examples/aio_basics/*.py 
+  # finally, let's build the docs
+  - cd docs && sphinx-build -E -W -b html . _build/html

Adafruit_IO/client.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2014 Adafruit Industries
+# Copyright (c) 2018 Adafruit Industries
 # Authors: Justin Cooper & Tony DiCola
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -60,8 +60,11 @@ def __init__(self, username, key, proxies=None, base_url='https://io.adafruit.co
         # constructing the path.
         self.base_url = base_url.rstrip('/')
 
-    def _compose_url(self, path):
-        return '{0}/api/{1}/{2}/{3}'.format(self.base_url, self.api_version, self.username, path)
+    def _compose_url(self, path, is_time=None):
+        if not is_time:
+            return '{0}/api/{1}/{2}/{3}'.format(self.base_url, self.api_version, self.username, path)
+        else: # return a call to https://io.adafruit.com/api/v2/time/{unit}
+            return '{0}/api/{1}/{2}'.format(self.base_url, self.api_version, path)
 
 
     def _handle_error(self, response):
@@ -78,12 +81,15 @@ def _headers(self, given):
         headers.update(given)
         return headers
 
-    def _get(self, path):
-        response = requests.get(self._compose_url(path),
+    def _get(self, path, is_time=None):
+        response = requests.get(self._compose_url(path, is_time),
                                 headers=self._headers({'X-AIO-Key': self.key}),
                                 proxies=self.proxies)
         self._handle_error(response)
-        return response.json()
+        if not is_time:
+            return response.json()
+        else: # time doesn't need to serialize into json, just return text
+            return response.text
 
     def _post(self, path, data):
         response = requests.post(self._compose_url(path),
@@ -130,6 +136,26 @@ def append(self, feed, value):
         """
         return self.create_data(feed, Data(value=value))
 
+    def send_location_data(self, feed, value, lat, lon, ele):
+        """Sends locational data to a feed
+
+        args:
+            - lat: latitude 
+            - lon: logitude
+            - ele: elevation
+            - (optional) value: value to send to the feed
+        """
+        return self.create_data(feed, Data(value = value,lat=lat, lon=lon, ele=ele))
+
+    def receive_time(self, time):
+        """Returns the time from the Adafruit IO server.
+
+        args:
+            - time (string): millis, seconds, ISO-8601
+        """
+        timepath = "time/{0}".format(time)
+        return self._get(timepath, is_time=True)
+
     def receive(self, feed):
         """Retrieve the most recent value for the specified feed.  Feed can be a
         feed ID, feed key, or feed name.  Returns a Data instance whose value

Adafruit_IO/errors.py

@@ -21,6 +21,14 @@
 
 import json
 
+# MQTT RC Error Types
+MQTT_ERRORS   = [ 'Connection successful',
+                  'Incorrect protocol version',
+                  'Invalid Client ID',
+                  'Server unavailable ',
+                  'Bad username or password',
+                  'Not authorized' ]
+
 class AdafruitIOError(Exception):
     """Base class for all Adafruit IO request failures."""
     pass
@@ -49,3 +57,11 @@ def __init__(self):
         super(ThrottlingError, self).__init__("Exceeded the limit of Adafruit IO "  \
             "requests in a short period of time. Please reduce the rate of requests " \
             "and try again later.")
+
+class MQTTError(Exception):
+    """Handles connection attempt failed errors.
+    """
+    def __init__(self, response):
+        error = MQTT_ERRORS[response]
+        super(MQTTError, self).__init__(error)
+    pass

Adafruit_IO/model.py

@@ -36,7 +36,10 @@
                   'feed_id',
                   'expiration',
                   'position',
-                  'id' ]
+                  'id',
+                  'lat',
+                  'lon',
+                  'ele']
 
 FEED_FIELDS   = [ 'name',
                   'key',

Adafruit_IO/mqtt_client.py

@@ -21,7 +21,8 @@
 import logging
 
 import paho.mqtt.client as mqtt
-
+import sys
+from .errors import MQTTError, RequestError
 
 # How long to wait before sending a keep alive (paho-mqtt configuration).
 KEEP_ALIVE_SEC = 60  # One minute
@@ -34,23 +35,29 @@ class MQTTClient(object):
     using the MQTT protocol.
     """
 
-    def __init__(self, username, key, service_host='io.adafruit.com', service_port=1883):
+    def __init__(self, username, key, service_host='io.adafruit.com', secure=True):
         """Create instance of MQTT client.
 
-        Required parameters:
-        - username: The Adafruit.IO username for your account (found on the
-                    accounts site https://accounts.adafruit.com/).
-        - key: The Adafruit.IO access key for your account.
+            :param username: Adafruit.IO Username for your account.
+            :param key: Adafruit IO access key (AIO Key) for your account.
+            :param secure: (optional, boolean) Switches secure/insecure connections
         """
         self._username = username
         self._service_host = service_host
-        self._service_port = service_port
+        if secure:
+            self._service_port = 8883
+        elif not secure:
+            self._service_port = 1883
         # Initialize event callbacks to be None so they don't fire.
         self.on_connect    = None
         self.on_disconnect = None
         self.on_message    = None
         # Initialize MQTT client.
         self._client = mqtt.Client()
+        if secure:
+            self._client.tls_set_context()
+        elif not secure:
+            print('**THIS CONNECTION IS INSECURE** SSL/TLS not supported for this platform')
         self._client.username_pw_set(username, key)
         self._client.on_connect    = self._mqtt_connect
         self._client.on_disconnect = self._mqtt_disconnect
@@ -62,11 +69,12 @@ def _mqtt_connect(self, client, userdata, flags, rc):
         # Check if the result code is success (0) or some error (non-zero) and
         # raise an exception if failed.
         if rc == 0:
+            #raise RequestError(rc)
             self._connected = True
+            print('Connected to Adafruit IO!')
         else:
-            # TODO: Make explicit exception classes for these failures:
-            # 0: Connection successful 1: Connection refused - incorrect protocol version 2: Connection refused - invalid client identifier 3: Connection refused - server unavailable 4: Connection refused - bad username or password 5: Connection refused - not authorised 6-255: Currently unused.
-            raise RuntimeError('Error connecting to Adafruit IO with rc: {0}'.format(rc))
+            # handle RC errors within `errors.py`'s MQTTError class
+            raise MQTTError(rc)
         # Call the on_connect callback if available.
         if self.on_connect is not None:
             self.on_connect(self)
@@ -78,7 +86,8 @@ def _mqtt_disconnect(self, client, userdata, rc):
         # log the RC as an error.  Continue on to call any disconnect handler
         # so clients can potentially recover gracefully.
         if rc != 0:
-            logger.debug('Unexpected disconnect with rc: {0}'.format(rc))
+            raise MQTTError(rc)
+        print('Disconnected from Adafruit IO!')
         # Call the on_disconnect callback if available.
         if self.on_disconnect is not None:
             self.on_disconnect(self)
@@ -91,7 +100,10 @@ def _mqtt_message(self, client, userdata, msg):
         if self.on_message is not None and self._username == parsed_topic[0]:
             feed = parsed_topic[2]
             payload = '' if msg.payload is None else msg.payload.decode('utf-8')
-            self.on_message(self, feed, payload)
+        elif self.on_message is not None and parsed_topic[0] == 'time':
+            feed = parsed_topic[0]
+            payload = msg.payload.decode('utf-8')
+        self.on_message(self, feed, payload)
 
     def connect(self, **kwargs):
         """Connect to the Adafruit.IO service.  Must be called before any loop
@@ -154,6 +166,22 @@ def subscribe(self, feed_id):
         """
         self._client.subscribe('{0}/feeds/{1}'.format(self._username, feed_id))
 
+    def subscribe_time(self, time):
+        """Subscribe to changes on the Adafruit IO time feeds. When the feed is
+        updated, the on_message function will be called and publish a new value:
+        time =
+            millis: milliseconds
+            seconds: seconds
+            iso: ISO-8601 (https://en.wikipedia.org/wiki/ISO_8601)
+        """
+        if time == 'millis' or time == 'seconds':
+            self._client.subscribe('time/{0}'.format(time))
+        elif time == 'iso':
+            self._client.subscribe('time/ISO-8601')
+        else:
+            print('ERROR: Invalid time type specified')
+            return
+
     def publish(self, feed_id, value):
         """Publish a value to a specified feed.
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at support@adafruit.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Adafruit
+Copyright (c) 2014-2018 Adafruit
 Author: Justin Cooper and Tony DiCola
 
 MIT License

MANIFEST.in

@@ -1 +1 @@
-include README.md
+include README.rst