Hologram Python SDK v0.6.0 release

Author: tzhenghao

ChangeLog

@@ -1,3 +1,18 @@
+2017-09-22 Hologram <[email protected]>
+    * Added program install verification steps to install script.
+
+2017-09-20 Hologram <[email protected]>
+    * Added hologram activate CLI subcommand. This allows developers to
+      activate their SIM via the CLI instead of doing it on the dashboard.
+
+2017-09-18 Hologram <[email protected]>
+    * Added autodetection of USB modems and serial ports associated with those
+      modems
+    * Fix issue where scripts might hang when trying to use a serial port with
+      ppp attached
+    * Remove some redundant checks and unneeded initializations that were slowing
+      things down
+
 2017-09-12 Hologram <[email protected]>
     * Deprecated enable_inbound flag in HologramCloud constructor.
     * Suppress stack traces when user sends a SIGTERM while it's establishing

Exceptions/HologramError.py

@@ -3,6 +3,9 @@ class HologramError(Exception):
     def __repr__(self):
         return '%s: %s' % (type(self).__name__, str(self))
 
+class ApiError(HologramError):
+    pass
+
 class AuthenticationError(HologramError):
     pass
 

Hologram/Api/Api.py

@@ -0,0 +1,96 @@
+from Exceptions.HologramError import ApiError
+
+import logging
+from logging import NullHandler
+import requests
+
+HOLOGRAM_REST_API_BASEURL = 'https://dashboard.hologram.io/api/1'
+
+class Api(object):
+
+    def __init__(self, apikey='', username='', password=''):
+        # Logging setup.
+        self.logger = logging.getLogger(__name__)
+        self.logger.addHandler(NullHandler())
+        self.authtype = None
+
+        self.__enforce_auth_method(apikey, username, password)
+
+        self.apikey = apikey
+        self.username = username
+        self.password = password
+
+    # REQUIRES: a SIM number and a plan id.
+    # EFFECTS: Activates a SIM. Returns a tuple of a success flag and
+    #          more info about the response.
+    def activateSIM(self, sim='', plan=None, zone=1, preview=False):
+
+        endpoint = HOLOGRAM_REST_API_BASEURL + '/links/cellular/sim_' + str(sim) + '/claim'
+
+        args = self.__populate_auth_payload()
+        args['data'] = {'plan': plan, 'tier': zone}
+
+        if preview == True:
+            args['params']['preview'] = 1
+
+        response = requests.post(endpoint, **args)
+        if response.status_code != requests.codes.ok:
+            response.raise_for_status()
+
+        response = response.json()
+        if response['success'] == False:
+            return (response['success'], response['data'][str(sim)])
+        return (response['success'], response['order_data'])
+
+    # EFFECTS: Returns a list of plans. Returns a tuple of a success flag and
+    #          more info about the response.
+    def getPlans(self):
+        endpoint = HOLOGRAM_REST_API_BASEURL + '/plans'
+        args = self.__populate_auth_payload()
+
+        response = requests.get(endpoint, **args)
+        if response.status_code != requests.codes.ok:
+            response.raise_for_status()
+
+        response = response.json()
+        return (response['success'], response['data'])
+
+    # EFFECTS: Gets the SIM state
+    def getSIMState(self, sim):
+        endpoint = HOLOGRAM_REST_API_BASEURL + '/links/cellular'
+
+        args = self.__populate_auth_payload()
+        args['params']['sim'] = str(sim)
+
+        response = requests.get(endpoint, **args)
+        if response.status_code != requests.codes.ok:
+            response.raise_for_status()
+
+        response = response.json()
+        return (response['success'], response['data'][0]['state'])
+
+    # EFFECTS: Populates and returns a dictionary with the proper HTTP
+    #          authentication credentials.
+    def __populate_auth_payload(self):
+
+        args = dict()
+        args['params'] = dict()
+
+        if self.authtype == 'basic_auth':
+            args['auth'] = (self.username, self.password)
+        elif self.authtype == 'apikey':
+            args['params'] = {'apikey' : self.apikey}
+        else:
+            raise ApiError('Invalid HTTP Authentication type')
+
+        return args
+
+    # EFFECTS: Checks to make sure that the valid authentication parameters are being used
+    #          correctly, throws an Exception if there's an issue with it.
+    def __enforce_auth_method(self, apikey, username, password):
+        if apikey == '' and (username == '' or password == ''):
+            raise ApiError('Must specify valid HTTP authentication credentials')
+        elif apikey == '':
+            self.authtype = 'basic_auth'
+        else:
+            self.authtype = 'apikey'

Hologram/Api/__init__.py

@@ -0,0 +1 @@
+from Api import *

Hologram/Cloud.py

@@ -14,7 +14,7 @@
 from Network import NetworkManager
 from Authentication import *
 
-__version__ = '0.5.28'
+__version__ = '0.6.0'
 
 class Cloud(object):
 

Hologram/CustomCloud.py

@@ -207,6 +207,9 @@ def stopPeriodicMessage(self):
         self.logger.info('Periodic job stopped')
 
     def initializeReceiveSocket(self):
+        return self.openReceiveSocket()
+
+    def openReceiveSocket(self):
 
         try:
             self.__enforce_receive_host_and_port()
@@ -220,12 +223,12 @@ def initializeReceiveSocket(self):
         self.logger.info('Socket created')
         self._receive_cv.release()
 
-        self.openReceiveSocket()
+        self.open_receive_socket_helper()
 
         return True
 
     # EFFECTS: Opens and binds an inbound socket connection.
-    def openReceiveSocket(self):
+    def open_receive_socket_helper(self):
 
         self._receive_cv.acquire()
 

Hologram/HologramCloud.py

@@ -127,6 +127,7 @@ def sendMessage(self, message, topics = None, timeout = 5):
     def sendSMS(self, destination_number, message):
 
         try:
+            self.__enforce_valid_destination_number(destination_number)
             self.__enforce_max_sms_length(message)
         except HologramError as e:
             self.logger.error(repr(e))
@@ -211,6 +212,10 @@ def __enforce_max_sms_length(self, message):
         if len(message) > MAX_SMS_LENGTH:
             raise HologramError('SMS cannot be more than %d characters long' % MAX_SMS_LENGTH)
 
+    def __enforce_valid_destination_number(self, destination_number):
+        if not destination_number.startswith('+'):
+            raise HologramError('SMS destination number must start with a \'+\' sign')
+
     # REQUIRES: A result code (int).
     # EFFECTS: Returns a translated string based on the given hologram result code.
     def getResultString(self, result_code):

Hologram/Network/Cellular.py

@@ -17,6 +17,7 @@
 from Network import Network
 import subprocess
 import sys
+import usb.core
 
 # Cellular return codes.
 CLOUD_DISCONNECTED = 0
@@ -36,18 +37,25 @@ class Cellular(Network):
         '': Modem
     }
 
-    def __init__(self, modem='', event=Event()):
+    def __init__(self, event=Event()):
         super(Cellular, self).__init__(event=event)
         self._connectionStatus = CLOUD_DISCONNECTED
-        self.modem = modem
+        self._modem = None
+
+
+    def autodetect_modem(self):
+        # scan for a modem and set it if found
+        dev_devices = self._scan_for_modems()
+        if dev_devices is None:
+            raise NetworkError('Modem not detected')
+        self.modem = dev_devices[0]
+
 
     def getConnectionStatus(self):
         return self._connectionStatus
 
     def connect(self, timeout = DEFAULT_CELLULAR_TIMEOUT):
-        self.logger.info('Connecting to cell network with timeout of ' + str(timeout) + ' seconds')
-        self._enforce_modem_attached()
-
+        self.logger.info('Connecting to cell network with timeout of %s seconds', timeout)
         success = False
         try:
             success = self.modem.connect(timeout = timeout)
@@ -66,7 +74,6 @@ def connect(self, timeout = DEFAULT_CELLULAR_TIMEOUT):
 
     def disconnect(self):
         self.logger.info('Disconnecting from cell network')
-        self._enforce_modem_attached()
         success = self.modem.disconnect()
         if success:
             self.logger.info('Successfully disconnected from cell network')
@@ -101,33 +108,32 @@ def popReceivedSMS(self):
     def get_sim_otp_response(self, command):
         return self.modem.get_sim_otp_response(command)
 
-    # EFFECTS: Returns a list of devices that are physically attached and recognized
-    #          by the machine.
-    def _get_attached_devices(self):
-        return subprocess.check_output('ls /dev/tty*', stderr=subprocess.STDOUT,
-                                       shell=True)
-    def _get_active_device_name(self):
-
-        self._enforce_modem_attached()
-
-        dev_devices = self._get_attached_devices()
-        if '/dev/ttyACM0' in dev_devices:
-            self.logger.info('/dev/ttyACM0 found to be active modem interface')
-            return 'nova'
-        elif '/dev/ttyUSB0' in dev_devices:
-            self.logger.info('/dev/ttyUSB0 found to be active modem interface')
-            return 'ms2131'
-        else:
-            raise NetworkError('Modem device name not found')
 
-    def _enforce_modem_attached(self):
-        if self.isModemAttached() == False:
-            raise NetworkError('Modem is not physically connected')
+    def _scan_for_modems(self):
+        res = None
+        for (modemName, modemHandler) in self._modemHandlers.iteritems():
+            if self._scan_for_modem(modemHandler):
+                res = (modemName, modemHandler)
+                break
+        return res
+
+
+    def _scan_for_modem(self, modemHandler):
+        usb_ids = modemHandler.usb_ids
+        for vid_pid in usb_ids:
+            if not vid_pid:
+                continue
+            self.logger.debug('checking for vid_pid: %s', str(vid_pid))
+            vid = int(vid_pid[0], 16)
+            pid = int(vid_pid[1], 16)
+            dev = usb.core.find(idVendor=vid, idProduct=pid)
+            if dev:
+                self.logger.info('Detected modem %s', modemHandler.__name__)
+                return True
+        return False
+
+
 
-    # EFFECTS: Returns True if a supported modem is physically attached to the machine.
-    def isModemAttached(self):
-        dev_devices = self._get_attached_devices()
-        return ('/dev/ttyACM0' in dev_devices) or ('/dev/ttyUSB0' in dev_devices)
 
     @property
     def modem(self):
@@ -136,11 +142,11 @@ def modem(self):
     @modem.setter
     def modem(self, modem):
         try:
-            modem = self._get_active_device_name()
             if modem not in self._modemHandlers:
                 raise NetworkError('Invalid modem type: %s' % modem)
             else:
                 self._modem = self._modemHandlers[modem](event=self.event)
+            # not sure about the exception handling in here. seems like we should let it bubble up
         except NetworkError as e:
             self.logger.error(repr(e))
             sys.exit(1)

Hologram/Network/Modem/E303.py

@@ -11,22 +11,17 @@
 from Modem import Modem
 from ...Event import Event
 
-E303_DEVICE_NAME = '/dev/ttyUSB0'
 DEFAULT_E303_TIMEOUT = 200
 
 class E303(Modem):
+    usb_ids = [('12d1','1001')]
 
-    def __init__(self, device_name=E303_DEVICE_NAME, baud_rate='9600',
+    def __init__(self, device_name=None, baud_rate='9600',
                  chatscript_file=None, event=Event()):
 
         super(E303, self).__init__(device_name=device_name, baud_rate=baud_rate,
                                    chatscript_file=chatscript_file, event=event)
 
-    def isConnected(self):
-        return self._mode.connected()
+    def connect(self, timeout = DEFAULT_E303_TIMEOUT):
+        return super(E303, self).connect(timeout)
 
-    def connect(self, timeout=DEFAULT_E303_TIMEOUT):
-        return self._mode.connect(timeout=timeout)
-
-    def disconnect(self):
-        return self._mode.disconnect()

Hologram/Network/Modem/IModem.py

@@ -19,6 +19,8 @@
 
 class IModem(object):
 
+    usb_ids = []
+
     _error_code_description = {
 
         MODEM_NO_MATCH: 'Modem response doesn\'t match expected return value',
@@ -34,6 +36,7 @@ def __init__(self, device_name='/dev/ttyUSB0', baud_rate='9600', event=Event()):
 
         self.event = event
         self.device_name = device_name
+        self.baud_rate = baud_rate
 
     def __repr__(self):
         return type(self).__name__