artoo 0.4.0 → 0.4.1

data/lib/artoo/api.rb

@@ -3,46 +3,80 @@ require 'artoo/api_route_helpers'
 require 'artoo/device_event_client'
 
 module Artoo
+  # Artoo API Server provides an interface to communicate with
+  # master class and retrieve information about robots being
+  # controlled
   class Api < Reel::Server
     include Artoo::ApiRouteHelpers
 
+    # Create new API server
+    # @param [String] host
+    # @param [Int]    port
     def initialize(host = "127.0.0.1", port = 3000)
       super(host, port, &method(:on_connection))
     end
 
+    # Dispatches connection requests
     def on_connection(connection)
       while request = connection.request
         dispatch!(connection, request)
       end
     end
 
+    # Retrieve list of robots
+    # @return [JSON] robots
     get '/robots' do
       MultiJson.dump(master.robots.collect {|r|r.to_hash})
     end
 
+    # Retrieve robot by id
+    # @return [JSON] robot
     get '/robots/:robotid' do
-      master.get_robot(@params['robotid']).as_json
+      master.robot(@params['robotid']).as_json
     end
 
+    # Retrieve robot devices
+    # @return [JSON] devices
     get '/robots/:robotid/devices' do
-      MultiJson.dump(master.get_robot_devices(@params['robotid']).each_value.collect {|d| d.to_hash})
+      MultiJson.dump(master.robot_devices(@params['robotid']).each_value.collect {|d| d.to_hash})
     end
 
+    # Retrieve robot device
+    # @return [JSON] device
     get '/robots/:robotid/devices/:deviceid' do
       device(@params['robotid'], @params['deviceid']).as_json
     end
 
+    # Retrieve robot commands
+    # @return [JSON] commands
+    get '/robots/:robotid/devices/:deviceid/commands' do
+      MultiJson.dump(device(@params['robotid'], @params['deviceid']).commands)
+    end
+
+    # Retrieve robot command
+    # @return [JSON] command
+    post '/robots/:robotid/devices/:deviceid/commands/:commandid' do
+      result = device(@params['robotid'], @params['deviceid']).command(@params['commandid'], command_params)
+      return MultiJson.dump({'result' => result})
+    end
+
+    # Subscribte to robot device events
+    # @return [nil]
     get_ws '/robots/:robotid/devices/:deviceid/events' do
       DeviceEventClient.new(@req, device(@params['robotid'], @params['deviceid']).event_topic_name('update'))
       return nil
     end
 
+    # Retrieve robot connections
+    # @return [JSON] connections
     get '/robots/:robotid/connections' do
-      MultiJson.dump(master.get_robot_connections(@params['robotid']).each_value.collect {|c| c.to_hash})
+      MultiJson.dump(master.robot_connections(@params['robotid']).each_value.collect {|c| c.to_hash})
     end
 
+    # Retrieve robot connection
+    # @return [JSON] connection
     get '/robots/:robotid/connections/:connectionid' do
-      master.get_robot_connection(@params['robotid'], @params['connectionid']).as_json
+      master.robot_connection(@params['robotid'], @params['connectionid']).as_json
     end
 
     protected
@@ -52,7 +86,16 @@ module Artoo
     end
 
     def device(robot_id, device_id)
-      master.get_robot_device(robot_id, device_id)
+      master.robot_device(robot_id, device_id)
+    end
+
+    def command_params
+      data = MultiJson.load(@req.body, :symbolize_keys => true)
+      if data
+        data[:params]
+      else
+        nil
+      end
     end
   end
 end

data/lib/artoo/api_route_helpers.rb

@@ -1,23 +1,30 @@
-# route helpers used within the Artoo::Api class
 module Artoo
+  # Route helpers used within the Artoo::Api class
   module ApiRouteHelpers
     class ResponseHandled < StandardError; end
     module ClassMethods
 
+      # Path to api/public directory
+      # @return [String] static path
       def static_path(default=File.join(File.dirname(__FILE__), "..", "..", "api/public"))
         @static_path ||= default
       end
 
+      # @return [Hash] routes
       def routes
         @routes ||= {}
       end
 
+      # Adds compiled signature to routes hash
+      # @return [Array] signature
       def route(verb, path, &block)
         signature = compile!(verb, path, block, {})
         (routes[verb] ||= []) << signature
       end
 
-      ## Ripped from Sinatra 'cause it's so sexy in there
+      # Creates method from block, ripped from Sinatra
+      # 'cause it's so sexy in there
+      # @return [Method] generated method
       def generate_method(method_name, &block)
         define_method(method_name, &block)
         method = instance_method method_name
@@ -25,6 +32,7 @@ module Artoo
         method
       end
 
+      #@todo Add documentation
       def compile!(verb, path, block, options = {})
         options.each_pair { |option, args| send(option, *args) }
         method_name             = "#{verb} #{path}"
@@ -37,6 +45,7 @@ module Artoo
             proc { |a,p| unbound_method.bind(a).call } ]
       end
 
+      #@todo Add documentation
       def compile(path)
         keys = []
         if path.respond_to? :to_str
@@ -71,6 +80,7 @@ module Artoo
         end
       end
 
+      #@todo Add documentation
       def safe_ignore(ignore)
         unsafe_ignore = []
         ignore = ignore.gsub(/%[\da-fA-F]{2}/) do |hex|
@@ -94,13 +104,22 @@ module Artoo
         end
       end
 
-      # Helper route functions
+      # Route function for get
       def get(path, &block)
         route 'GET', path, &block
       end
+
+      # Route function for get_ws
       def get_ws(path, &block)
         route 'GET', path, &block
       end
+
+      # Route function for post
+      def post(path, &block)
+        route 'POST', path, &block
+      end
+
+      # Route function for put
       def put(path, &block)
         route 'PUT', path, &block
       end

data/lib/artoo/basic.rb

@@ -1,7 +1,6 @@
-
 module Artoo
+  # Methods taken from Sinatra codebase
   module Basic
-    # Taken from Sinatra codebase
     # Sets an option to the given value.  If the value is a proc,
     # the proc will be called every time the option is accessed.
     def set(option, value = (not_set = true), ignore_setter = false, &block)
@@ -39,7 +38,7 @@ module Artoo
       self
     end
 
-    # Taken from Sinatra codebase
+    # Callers to ignore
     CALLERS_TO_IGNORE = [ # :nodoc:
       /lib\/artoo.*\.rb$/,                                # artoo code
       /^\(.*\)$/,                                         # generated code
@@ -50,7 +49,6 @@ module Artoo
       /src\/kernel\/bootstrap\/[A-Z]/                     # maglev kernel files
     ]
 
-    # Taken from Sinatra codebase
     # Like Kernel#caller but excluding certain magic entries and without
     # line / method information; the resulting array contains filenames only.
     def caller_files
@@ -59,16 +57,14 @@ module Artoo
 
     private
 
-    # Taken from Sinatra codebase
+    # Replace with call to singleton_class once we're 1.9 only
     def define_singleton_method(name, content = Proc.new)
-    # replace with call to singleton_class once we're 1.9 only
       (class << self; self; end).class_eval do
         undef_method(name) if method_defined? name
         String === content ? class_eval("def #{name}() #{content}; end") : define_method(name, &content)
       end
     end
 
-    # Taken from Sinatra codebase
     # Like Kernel#caller but excluding certain magic entries
     def cleaned_caller(keep = 3)
       caller(1).

data/lib/artoo/connection.rb

@@ -1,7 +1,7 @@
 require 'artoo/utility'
 
 module Artoo
-  # The Connection class represents the interface to 
+  # The Connection class represents the interface to
   # a specific group of hardware devices. Examples would be an
   # Arduino, a Sphero, or an ARDrone.
   class Connection
@@ -11,6 +11,12 @@ module Artoo
 
     attr_reader :parent, :name, :port, :adaptor, :connection_id
 
+    # Create new connection
+    # @param [Hash] params
+    # @option params :name    [String]
+    # @option params :parent  [String]
+    # @option params :adaptor [String]
+    # @option params :port    [Integer]
     def initialize(params={})
       @connection_id = rand(10000)
       @name = params[:name].to_s
@@ -20,6 +26,8 @@ module Artoo
       require_adaptor(params[:adaptor] || :loopback)
     end
 
+    # Creates adaptor connection
+    # @return [Boolean]
     def connect
       Logger.info "Connecting to '#{name}' on port '#{port}'..."
       adaptor.connect
@@ -28,36 +36,46 @@ module Artoo
       Logger.error e.backtrace.inspect
     end
 
+    # Closes adaptor connection
+    # @return [Boolean]
     def disconnect
       Logger.info "Disconnecting from '#{name}' on port '#{port}'..."
       adaptor.disconnect
     end
 
+    # @return [Boolean] Connection status
     def connected?
       adaptor.connected?
     end
 
+    # @return [String] Adaptor class name
     def adaptor_name
       adaptor.class.name
     end
 
+    # @return [Hash] connection
     def to_hash
-      {:name => name,
-       :connection_id => connection_id,
-       :port => port.to_s,
-       :adaptor => adaptor_name.demodulize,
-       :connected => connected?
+      {
+        :name => name,
+        :connection_id => connection_id,
+        :port => port.to_s,
+        :adaptor => adaptor_name.to_s.gsub(/^.*::/, ''),
+        :connected => connected?
       }
     end
 
+    # @return [JSON] connection
     def as_json
       MultiJson.dump(to_hash)
     end
 
+    # @return [String] Formated connection
     def inspect
       "#<Connection @id=#{object_id}, @name='#{name}', @adaptor=#{adaptor_name}>"
     end
 
+    # Redirects missing methods to adaptor,
+    # attemps reconnection if adaptor not connected
     def method_missing(method_name, *arguments, &block)
       unless adaptor.connected?
         Logger.warn "Cannot call unconnected adaptor '#{name}', attempting to reconnect..."
@@ -78,4 +96,4 @@ module Artoo
       @adaptor = constantize("Artoo::Adaptors::#{classify(type.to_s)}").new(:port => port, :parent => current_instance)
     end
   end
-end
+end

data/lib/artoo/delegator.rb

@@ -1,25 +1,15 @@
-
 module Artoo
   # Execution context for top-level robots
   # DSL methods executed on main are delegated to this class like Sinatra
   class MainRobot < Robot
-    #set :logging, Proc.new { ! test? }
-    #set :method_override, true
-    set :start_work, false #Proc.new { ! test? }
-    #set :app_file, nil
-
-    # def self.register(*extensions, &block) #:nodoc:
-    #   added_methods = extensions.map {|m| m.public_instance_methods }.flatten
-    #   Delegator.delegate(*added_methods)
-    #   super(*extensions, &block)
-    # end
+    set :start_work, false
   end
-  
-  # Artoo delegation mixin that acts like Sinatra. 
+
+  # Artoo delegation mixin that acts like Sinatra.
   # Mixing this module into an object causes all
-  # methods to be delegated to the Artoo::MainRobot class. 
+  # methods to be delegated to the Artoo::MainRobot class.
   # Used primarily at the top-level.
-  module Delegator #:nodoc:
+  module Delegator
     def self.delegate(*methods)
       methods.each do |method_name|
         define_method(method_name) do |*args, &block|
@@ -46,4 +36,4 @@ module Artoo
     robot.class_eval(&block) if block_given?
     robot
   end
-end
+end

data/lib/artoo/device.rb

@@ -1,13 +1,21 @@
 module Artoo
-  # The Artoo::Device class represents the interface to 
+  # The Artoo::Device class represents the interface to
   # a specific individual hardware devices. Examples would be a digital
   # thermometer connected to an Arduino, or a Sphero's accelerometer.
   class Device
     include Celluloid
     include Artoo::Utility
-    
+
     attr_reader :parent, :name, :driver, :pin, :connection, :interval
 
+    # Create new device
+    # @param  [Hash] params
+    # @option params :name       [String]
+    # @option params :pin        [String]
+    # @option params :parent     [String]
+    # @option params :connection [String]
+    # @option params :interval   [String]
+    # @option params :driver     [String]
     def initialize(params={})
       @name = params[:name].to_s
       @pin = params[:pin]
@@ -18,39 +26,60 @@ module Artoo
       require_driver(params[:driver] || :passthru)
     end
 
+    # Retrieve connections from parent
+    # @param [String] c connection
     def determine_connection(c)
       parent.connections[c] unless c.nil?
     end
 
+    # @return [Connection] default connection
     def default_connection
       parent.default_connection
     end
 
+    # Starts device driver
     def start_device
       driver.start_driver
     end
 
+    # @return [String] event topic name
     def event_topic_name(event)
-      "#{parent.safe_name}_#{name}_#{event}"  
+      "#{parent.safe_name}_#{name}_#{event}"
     end
 
+    # @return [Hash] device
     def to_hash
-      {:name => name,
-       :driver => driver.class.name.demodulize,
-       :pin => pin.to_s,
-       :connection => connection.to_hash,
-       :interval => interval
+      {
+        :name => name,
+        :driver => driver.class.name.to_s.gsub(/^.*::/, ''),
+        :pin => pin.to_s,
+        :connection => connection.to_hash,
+        :interval => interval,
+        :commands => driver.commands
       }
     end
 
+    # @return [JSON] device
     def as_json
       MultiJson.dump(to_hash)
     end
 
+    # @return [Collection] commands
+    def commands
+      driver.commands
+    end
+
+    # Execute driver command
+    def command(method_name, *arguments, &block)
+      driver.command(method_name, *arguments)
+    end
+
+    # Sends missing methods to command
     def method_missing(method_name, *arguments, &block)
-      driver.send(method_name, *arguments, &block)
+      command(method_name, *arguments, &block)
     end
 
+    # @return [String] pretty inspect
     def inspect
       "#<Device @id=#{object_id}, @name='name', @driver='driver'>"
     end
@@ -62,4 +91,4 @@ module Artoo
       @driver = constantize("Artoo::Drivers::#{classify(d.to_s)}").new(:parent => current_instance)
     end
   end
-end
+end

data/lib/artoo/device_event_client.rb

@@ -9,6 +9,9 @@ module Artoo
 
     attr_reader :topic
 
+    # Create new event client
+    # @param [Socket] websocket
+    # @param [String] topic
     def initialize(websocket, topic)
       @topic = topic
       info "Streaming #{@topic} to websocket..."
@@ -16,6 +19,9 @@ module Artoo
       subscribe(@topic, :notify_event)
     end
 
+    # Event notification
+    # @param [String] topic
+    # @param [Object] data
     def notify_event(topic, *data)
       # TODO: send which topic sent the notification
       @socket << data.last.to_s