thingdom 0.1.0

data/lib/httpHelper.rb

@@ -0,0 +1,94 @@
+#
+# A class that handles all HTTP communication with Thingdom.
+#
+require 'rubygems'
+require 'net/https'
+require 'uri'
+require 'json'
+
+class HttpHelper
+
+  # 
+  # Constructor method for HttpHelper.  Initialize local data.
+  # 
+  def initialize()
+    @uri = URI.parse 'https://api.thingdom.io'
+    @path = '/1.1'
+    @request_counter = 0;
+  end
+
+  #
+  # Perform a HTTP GET request.
+  #
+  # @param [String] requestPath Contains path and optional query parameters (e.g. path/to/somewhere?param1=1&param2=2)
+  # @return [Hash] The request response.
+  #
+  def get_data( requestPath )
+    do_request( requestPath )
+  end
+
+  #
+  # Perform a HTTP Post request.
+  #
+  # @param [String] requestPath Contains path to where data will be posted (e.g. path/to/post/endpoint)
+  # @param [Hash] data The data to be posted.
+  # @return [Hash] The request response.
+  #
+  def post_data( requestPath, data )
+    @request_counter += 1
+    data[:counter] = @request_counter
+    data[:time] = Time.now.strftime( '%Y/%m/%d %H:%M:%S' )
+    do_request( requestPath, data )
+  end
+
+  # ***************************************************************************
+  # Helper Methods
+  # ***************************************************************************
+  private
+
+  #
+  # Convert JSON string to a hash where all keys are Symbols.
+  #
+  # @param [String] jsonString The JSON string.
+  # @return [Hash] A hash table representation of the JSON string.
+  #
+  def json_to_hash( jsonString )
+    jsonHash = JSON.parse( jsonString )
+    jsonHash = Hash[jsonHash.map{ |k, v| [k.to_sym, v] }]
+    return jsonHash
+  end
+
+  #
+  # Perform HTTP request.
+  #
+  # @param [String] requestPath Contains path to where data will be retrieved or posted (e.g. path/to/post-or-get/endpoint)
+  # @param [Hash] data The data to be posted.
+  # @return [Hash] The request response.
+  #
+  def do_request( requestPath, data = nil )
+    #
+    # Initialize HTTPS.
+    #
+    https = Net::HTTP.new( @uri.host, @uri.port )
+    https.use_ssl = true
+    https.verify_mode =  OpenSSL::SSL::VERIFY_PEER
+    https.ca_file = File.join( File.dirname( __FILE__ ), 'cacert.pem' )
+    #
+    # Build request.
+    #
+    if( data.nil? )
+      request = Net::HTTP::Get.new( @path + '/' + requestPath )
+    else
+      request = Net::HTTP::Post.new( @path + '/' + requestPath )
+      request.initialize_http_header( {'Content-Type' => 'application/json'} )
+      request.body = data.to_json
+    end
+    #
+    # Send request and convert JSON response into a hash.
+    #
+    response = https.request( request )
+    jsonHash = json_to_hash( response.body )
+  end
+
+end
+

data/lib/tasks/baseTask.rb

@@ -0,0 +1,57 @@
+
+class BaseTask
+
+  def initialize( webService, thing, isThingTask )
+    @web = webService
+    @thing = thing
+    @isThingTask = isThingTask
+  end
+
+  #
+  # Perform the task.
+  #
+  def perform
+    response = {}
+    #
+    # Make sure thing is valid (id and code exists) before doing any work.  The exception of course is if we
+    # are creating or retrieving a thing, in which case, id and code will not exist.
+    #
+    if( (@thing.id.to_s.length > 0 && @thing.code.length > 0) || @isThingTask )
+      #
+      # Do the task work.  If token has expired, then reauthorize and try again.
+      #
+      begin
+        response = do_task_work()
+        if( response[:response] == 'token_expired')
+          @web.get_authorization()
+          response = do_task_work()
+        end
+      #
+      # On any exception, return an error response with the exception description in the message.
+      #
+      rescue
+        response[:response] = 'error'
+        response[:msg] = "#{$!.class} - #{$!.message}"
+        @thing.last_error = response[:msg]
+      end
+    #
+    # Thing has not been created.  Return the appropriate error and message.
+    #
+    else
+      response[:response] = 'error'
+      response[:msg] = "Thing '#{@thing.name}' has not been created."
+    end
+    #
+    # Return the response.
+    #
+    return response
+  end
+
+  #
+  # This method should be overridden by the subclass and does the specific task work.
+  #
+  def do_task_work
+    return { :response => 'error', :msg => 'Task work method not implemented.' }
+  end
+
+end

data/lib/tasks/feedTask.rb

@@ -0,0 +1,18 @@
+require_relative( 'baseTask' )
+
+class FeedTask < BaseTask
+
+  def initialize( webService, thing, category, message, feedOptions )
+    super( webService, thing, false )
+    @web = webService
+    @thing = thing
+    @category = category
+    @message = message
+    @feedOptions = feedOptions
+  end
+
+  def do_task_work
+    @web.add_feed( @thing, @category, @message, @feedOptions )
+  end
+
+end

data/lib/tasks/statusTask.rb

@@ -0,0 +1,49 @@
+require_relative( 'baseTask' )
+
+class StatusTask < BaseTask
+
+  def initialize( webService, thing, *args )
+    super( webService, thing, false )
+    @web = webService
+    @thing = thing
+    @statusUpdates = statusArgsToArray( *args )
+  end
+
+  def do_task_work
+    @web.add_status( @thing, @statusUpdates )
+  end
+
+  # ***************************************************************************
+  # Helper methods.
+  # ***************************************************************************
+  private
+
+  #
+  # Convert status args into an array of hashes.
+  #
+  # @param [Array] *args The status args.
+  #
+  def statusArgsToArray( *args )
+    dataArray = Array.new
+    #
+    # If only one argument, then assume its already an array.
+    #
+    if( args.size == 1 )
+      dataArray = args[0]
+      #
+      # Otherwise, take the individual arguments, create a hash and insert into an array.
+      #
+    elsif( args.size >= 2 )
+      data = { :name => args[0], :value => args[1] }
+      if( args.size >= 3 )
+        data[:unit] = args[2]
+      end
+      dataArray.push( data )
+    end
+    #
+    # Return the result.
+    #
+    return dataArray
+  end
+
+end

data/lib/tasks/thingTask.rb

@@ -0,0 +1,15 @@
+require_relative ( 'baseTask' )
+
+class ThingTask < BaseTask
+
+  def initialize( webService, thing )
+    super( webService, thing, true )
+    @web = webService
+    @thing = @thing
+  end
+
+  def do_task_work
+    @web.add_thing( @thing )
+  end
+
+end

data/lib/thing.rb

@@ -0,0 +1,68 @@
+#
+# A class that encapsulates a Thing
+#
+require_relative( './tasks/statusTask' )
+require_relative( './tasks/feedTask' )
+require_relative( './tasks/thingTask' )
+
+class Thing
+  #
+  # Public Properties.
+  #
+  attr_accessor :id, :name, :product_type, :display_name, :code, :last_error
+
+  #
+  # Constructor method for Thing.
+  #
+  # @param [WebService] webService A web service used to communicate with Thingdom.
+  # @param [String] name The name of the Thing.
+  # @param [String] productType The product type the Thing belongs to.
+  # @param [String] displayName A user friendly name for Thing.
+  #
+  def initialize( webService, name, productType = '', displayName = '' )
+    @web = webService
+    @id = ''
+    @name = name
+    @product_type = productType
+    @display_name = displayName
+    @code = ''
+    #
+    # Perform task to get thing.
+    #
+    thingTask = ThingTask.new( @web, self )
+    response = thingTask.perform()
+    #
+    # If successful, then update the thing id and code.
+    #
+    if( response[:response] == 'success' )
+      @id = response[:thing_id]
+      @code = response[:code]
+    end
+  end
+
+  #
+  # Send a feed with additional feed options.
+  #
+  # @param [String] category A feed category that was defined during application registration.
+  # @param [String] message The feed message.
+  # @param [FeedOption] feedOptions Additional feed options: icon, progress bar, etc.
+  #
+  def feed( category, message, feedOptions = nil )
+    feedTask = FeedTask.new( @web, self, category, message, feedOptions )
+    feedTask.perform()
+  end
+
+  #
+  # Add or update a status item for this Thing.
+  #
+  # @param [String] name The status item name.
+  # @param [String] value The status item value.
+  # @param [String] unit The status item unit.
+  #
+  def status( *args )
+    statusTask = StatusTask.new( @web, self, *args )
+    statusTask.perform()
+  end
+
+
+end

data/lib/thingdom.rb

@@ -0,0 +1,34 @@
+#
+# The top level class that provides the Thingdom API.
+#
+require_relative 'webService'
+require_relative 'thing'
+
+class Thingdom
+
+  def initialize( appSecret )
+    #
+    # Create the web service.
+    #
+    @webService = WebService.new( appSecret )
+    @applicationToken = ''
+    #
+    # Authorize the application using the application secret.  If successful, save the application token that
+    # is returned for all subsequent communications with Thingdom.  Otherwise, raise an exception using the
+    # returned error message.
+    #
+    response = @webService.get_authorization()
+    result = response[:response] != 'error' && !response[:application_token].nil? && response[:application_token].length > 0
+    if( result )
+      @applicationToken = response[:application_token]
+    else
+      raise response[:msg]
+    end
+  end
+
+  def get_thing( name, productType = '', displayName = '' )
+    thing = Thing.new( @webService, name, productType, displayName )
+    return thing
+  end
+
+end

data/lib/thingdom/version.rb

@@ -0,0 +1,3 @@
+module Thingdom
+  VERSION = "0.1.0"
+end

data/lib/webService.rb

@@ -0,0 +1,101 @@
+#
+# A class that encapsulates the web services needed by the Ruby wrapper.
+#
+require_relative 'httpHelper'
+
+class WebService
+
+  #
+  # Constructor method for WebService.
+  #
+  # @param [String] secret A secret identifier for an application obtained by the user during the registration process.
+  #                        Without this, the app will not have access to Thingdom.
+  #
+  def initialize( secret )
+    @httpHelper = HttpHelper.new()
+    @apiSecret = secret
+    @applicationToken = ''
+    @deviceSecret = 'none'
+  end
+
+  #
+  # Ping Thingdom.
+  #
+  def ping_server()
+    @httpHelper.get_data( 'ping' )
+  end
+
+  #
+  # Authorize this application by sending the application secret to Thingdom.  If valid, Thingdom will send back a token
+  # which must be used in subsequent communications.
+  #
+  # @return [Hash] A hash containing the authorization response:
+  #                  application_token - The token used in subsequent communications with Thingdom
+  #                  expires_in - The number of seconds remaining before above token expires.
+  #                  device_secret - A unique identifier for device running this application (always ruby in this case)
+  #
+  def get_authorization()
+    data = {
+        api_secret: @apiSecret,
+        device_secret: @deviceSecret
+    }
+    response = @httpHelper.post_data( 'token', data )
+    response[:device_secret] ||= '';
+    @applicationToken = response[:application_token]
+    return response
+  end
+
+  #
+  # Retrieve a thing.  If it doesn't exist, then add it.
+  #
+  # @param [Thing] thing The thing to get or add.
+  #
+  def add_thing( thing )
+    data = {
+               token: @applicationToken,
+                name: thing.name,
+        display_name: thing.display_name
+    }
+    if( thing.product_type.length > 0 )
+      data[:product_type] = thing.product_type
+    end
+
+    @httpHelper.post_data( 'thing', data )
+  end
+
+  #
+  # Add or update a status item for a thing.
+  #
+  # @param [Thing] thing The thing to which the status item is attached.
+  # @param [Array] statusArray An array of status item updates (name, value, unit).
+  #
+  def add_status( thing, statusArray )
+    data = {
+               token: @applicationToken,
+            thing_id: thing.id,
+                  id: 'null',
+        status_array: statusArray
+    }
+    @httpHelper.post_data( 'status', data )
+  end
+
+  #
+  # Add a feed message to a thing.
+  #
+  # @param [Thing] thing The thing to which the feed message is applied.
+  # @param [String] category The feed category.
+  # @param [String] message The feed message.
+  # @param [FeedOption] feedOptions Additional feed options (icon, progress bar, etc)
+  #
+  def add_feed( thing, category, message, feedOptions  )
+    data = {
+                token: @applicationToken,
+             thing_id: thing.id,
+        feed_category: category,
+              message: message,
+              options: feedOptions
+    }
+    @httpHelper.post_data( 'feed', data )
+  end
+
+end