phidgets-ffi 0.0.5 → 0.1.0

data/lib/phidgets-ffi/dictionary.rb

@@ -1,10 +1,31 @@
 module Phidgets
-  class Dictionary
+  
+    # This class represents a PhidgetDictionary.
+	class Dictionary
 
     Klass = Phidgets::FFI::CPhidgetDictionary
     include Utility
     
-    def initialize(options={}, &block)
+#    attr_accessor :key_sleep, :handler_sleep
+
+   # Initializes a PhidgetDictionary. There are two methods that you can use to program the PhidgetDictionary.
+   # 
+   # @param [String] options Information required to connect to the WebService. This is optional. If no option is specified, it is assumed that the address is localhost and port is 5001
+   # @param [Proc] Block When the callback is executed, the device and object are yielded to this block.
+   #	
+   # @return [Object]
+   #
+   # <b>First Method:</b> You can program with a block. Please note that {Phidgets::Dictionary#open} will have to be called afterwards to open the PhidgetDictionary over the WebService.
+   #  options = {:address => 'localhost', :port => 5001, :server_id => nil, :password => nil}
+   #  Phidgets::Dictionary.new(options) do |dict| 
+   #    ...
+   #  end
+   #
+   # <b>Second Method:</b> You can program without a block
+   #
+   #  dict = Phidgets::Dictionary.new
+   def initialize(options={}, &block)
+      @key_sleep, @handler_sleep = 0.1, 0.5
       @listeners = {}
       @options = {:address => 'localhost', :port => 5001, :server_id => nil, :password => nil}.merge(options)
 
@@ -13,10 +34,14 @@ module Phidgets
         open(@options)
         yield self
         close
-        delete_dict
       end
     end
 
+    private
+	
+	# Creates a PhidgetDictionary.
+    # 
+    # @return [Boolean] returns true or raises an error
     def create
       ptr = ::FFI::MemoryPointer.new(:pointer, 1)
       Klass.create(ptr)        
@@ -24,7 +49,23 @@ module Phidgets
       true
     end
 
-    def open(options)
+	public
+    
+	# Opens a PhidgetDictionary over the WebService. 
+	# If you are not programming with the block method, you will have to call this explicitly.
+	# This is called automatically if you are programming with the block method. 
+	#
+	# <b>Usage:</b>
+	#
+	# Open a PhidgetDictionary using an address, port, and an optional password.
+	#  options = {:address => 'localhost', :port => 5001, :password => nil}
+	#  dict.open(options)
+	#
+	# Open a PhidgetDictionary using a server id, and an optional password.
+	#  options = {:server_id => 'localhost', :password => nil}
+	#  dict.open(options)
+	# @return [Boolean] returns true or raises an error
+	def open(options)
       password = (options[:password].nil? ? nil : options[:password].to_s)
       if !options[:server_id].nil?
         Klass.openRemote(@handle, options[:server_id].to_s, password)
@@ -35,29 +76,47 @@ module Phidgets
       true
     end
     
+    # Closes and frees a PhidgetDictionary
+    # 
+    # @return [Boolean] returns true or raises an error
     def close
       Klass.close(@handle)
-      true
-    end
-
-    def delete_dict
+	  sleep 0.2
       Klass.delete(@handle)
       true
     end
     
-    def []=(key, val, persistent=false)      
+	# Adds a key/value pair to the dictionary. Or, changes an existing key's value.
+	# @param [String] key key
+	# @param [String, Boolean] Value <b>:value</b> => value, <b>:persistent</b> => whether the key stays in the dictionary after the client that created it disconnects. Persistent is optional. Defaults to false
+	#
+	# @example
+	#  dict["key1"] = ["value1", true] #adds value1 to dict["key1"] with persistent = true
+	#  dict["key2"] = ["value2", false] #adds value2 to dict["key2"] with persistent = false
+	#  dict["key3"] = ["value3"] #adds value to to dict["key3"] with the default persistent = false
+	#  dict["key1"] = nil #removes the value of dict["key1"]
+	#
+	# @return [Boolean] returns true or raises an error
+
+	def []=(key, value=nil)  
+
       # If we are assigning something to nil, let's remove it
-      if val.nil?
+      if value.nil?
         delete(key)
+        sleep @key_sleep.to_f
+        nil
       else
-        persistent = (persistent ? 1 : 0)
-        Klass.addKey(@handle, key.to_s, val.to_s, persistent)
-        val.to_s
+	    persistent = (value[:persistent].nil? ? 0 : (value[:persistent] ? 1 : 0))
+	  
+        Klass.addKey(@handle, key.to_s, value[:value].to_s, persistent)
+        sleep @key_sleep.to_f
+        value[:value].to_s
       end
     end
     alias_method :add, :[]=
     alias_method :put, :[]=
     
+	# @return [String] returns the key value. If more than one key matches, only the first value is returned, or raises an error.
     def [](key)
       ptr = ::FFI::MemoryPointer.new(:string, 8192)
       Klass.getKey(@handle, key, ptr, 8192)
@@ -65,11 +124,24 @@ module Phidgets
     end
     alias_method :get, :[]
 
-    def delete(pattern)      
+	# Removes a set of keys from the dictionary
+    # 
+    # @return [Boolean] returns true or raises an error
+	def delete(pattern)      
       Klass.removeKey(@handle, (pattern.kind_of?(Regexp) ? pattern.source : pattern.to_s))
       true
     end
     
+    # Sets a server connect handler callback function. This is called when a connection to the server has been made.
+    #
+    # @param [String] obj Object to pass to the callback function. This is optional.
+    # @param [Proc] Block When the callback is executed, the device and object are yielded to this block.
+    # @example
+    #     dict.on_connect do |obj|
+    #       puts 'Connected'
+    #     end
+    # As this runs in it's own thread, be sure that all errors are properly handled or the thread will halt and not fire any more.
+    # @return [Boolean] returns true or raises an error
     def on_connect(obj=nil, &block)
       @on_connect_obj = obj
       @on_connect = Proc.new { |handle, obj_ptr|
@@ -78,39 +150,73 @@ module Phidgets
           begin
             next if status != :connected
             Klass.set_OnKeyChange_Handler(@handle, listener, pattern, proc, pointer_for(obj))              
-            sleep 0.5
+            sleep @handler_sleep
           rescue
             Phidgets::Log.error("#{self.class}::on_connect", $!.to_s)
           end
         end
-        yield object_for(obj_ptr)
+        yield self, object_for(obj_ptr)
       }
       Klass.set_OnServerConnect_Handler(@handle, @on_connect, pointer_for(obj))
+      sleep @handler_sleep
     end
     
+    # Sets a server disconnect handler callback function. This is called when a connection to the server has been lost.
+    #
+    # @param [String] obj Object to pass to the callback function. This is optional.
+    # @param [Proc] Block When the callback is executed, the device and object are yielded to this block.
+    # @example
+    #     dict.on_disconnect do |obj|
+    #       puts 'Disconnected'
+    #     end
+    # As this runs in it's own thread, be sure that all errors are properly handled or the thread will halt and not fire any more.
+    # @return [Boolean] returns true or raises an error
     def on_disconnect(obj=nil, &block)
       @on_disconnect_obj = obj
       @on_disconnect = Proc.new { |handle, obj_ptr|
         # On disconnect, we'll need to remove all of our change handlers
         @listeners.each_pair do |pattern, (listener, proc)|
           Klass.remove_OnKeyChange_Handler(listener.get_pointer(0))
+          sleep @handler_sleep
         end
-        yield object_for(obj_ptr)
+        yield self, object_for(obj_ptr)
       }
       Klass.set_OnServerDisconnect_Handler(@handle, @on_disconnect, pointer_for(obj))
+      sleep @handler_sleep
     end
     
+    # Sets a error handler callback function. This is called when an asynchronous error occurs.
+    #
+    # @param [String] obj Object to pass to the callback function. This is optional.
+    # @param [Proc] Block When the callback is executed, the device and object are yielded to this block.
+    # @example
+    #     dict.on_error do |obj|
+    #       puts "Error (#{code}): #{reason}"
+    #     end
+    # As this runs in it's own thread, be sure that all errors are properly handled or the thread will halt and not fire any more.
+    # @return [Boolean] returns true or raises an error
     def on_error(obj=nil, &block)
       @on_error_obj = obj
       @on_error = Proc.new { |handle, obj_ptr, code, error|
         yield object_for(obj_ptr), code, error
       }
       Klass.set_OnError_Handler(@handle, @on_error, pointer_for(obj))
+      sleep @handler_sleep
     end
 
-
+    # Adds a key listener to an opened dictionary. Note that this should only be called after the connection has been made - unlike all other events.
+    #
+    # @param [String] obj Object to pass to the callback function. This is optional.
+    # @param [Proc] Block When the callback is executed, the device and object are yielded to this block.
+    # @example
+    #     dict.on_change do |obj, key, val, reason|
+    #       puts "Every key: #{key} => #{val}-- #{reason}"
+    #     end
+    # As this runs in it's own thread, be sure that all errors are properly handled or the thread will halt and not fire any more.
+    # @return [Boolean] returns true or raises an error
     def on_change(pattern=".*", obj=nil, &block)
       pattern = (pattern.kind_of?(Regexp) ? pattern.source : pattern.to_s)
+
       @listeners[pattern] = [
         ::FFI::MemoryPointer.new(:pointer),
         Proc.new { |handle, obj_ptr, key, value, reason|
@@ -118,40 +224,47 @@ module Phidgets
         }
       ]
       Klass.set_OnKeyChange_Handler(@handle, @listeners[pattern][0], pattern, @listeners[pattern][1], pointer_for(obj))
-      sleep 0.5
+      sleep @handler_sleep
     end
 
-    def remove_on_change(pattern)
+	# Removes a key listener
+	# @param [String] pattern pattern
+	# @return [Boolean] returns true or raises an error
+    def remove_on_change(pattern=".*")
       pattern = (pattern.kind_of?(Regexp) ? pattern.source : pattern.to_s)
       if @listeners.has_key?(pattern)
         listener, proc = @listeners.delete(pattern)
         Klass.remove_OnKeyChange_Handler(listener.get_pointer(0))
-        sleep 0.5
+        sleep @handler_sleep
         true
       else
         nil
       end
     end
-    
+
+	# @return [Array] returns all the keys in the dictionary or raises an error    
     def listeners
       @listeners.keys
     end
 
+	# @return [Strings] returns the server ID, or raises an error    
     def server_id
       ptr = ::FFI::MemoryPointer.new(:string)
       Klass.getServerID(@handle, ptr)
       ptr.get_string(0)
     end
 
+	# @return [String] returns the connected to server status, or raises an error    
     def status
       ptr = ::FFI::MemoryPointer.new(:int)
       Klass.getServerStatus(@handle, ptr)
       Phidgets::FFI::ServerStatus[ptr.get_int(0)]
     end
 
+	# @return [String, Integer] returns the address and port, or raises an error    
     def server_address
       str_ptr, int_ptr = ::FFI::MemoryPointer.new(:string), ::FFI::MemoryPointer.new(:int)
-      Klass.getServerID(@handle, str_ptr, int_ptr)
+      Klass.getServerAddress(@handle, str_ptr, int_ptr)
       strPtr = str_ptr.get_pointer(0)
       address = (strPtr.null? ? nil : strPtr.read_string)
       port = int_ptr.get_int(0)

data/lib/phidgets-ffi/encoder.rb

@@ -0,0 +1,196 @@
+module Phidgets
+
+  # This class represents a PhidgetEncoder
+  class Encoder
+ 
+    Klass = Phidgets::FFI::CPhidgetEncoder
+    include Phidgets::Common
+    
+	# Collection of digital inputs
+	# @return [EncoderDigitalInputs] 
+    attr_reader :inputs
+	
+	# Collection of encoders
+	# @return [EncoderEncoders] 
+    attr_reader :encoders
+	
+	attr_reader :attributes
+		
+	# The attributes of a PhidgetEncoder
+    def attributes
+      super.merge({
+        :inputs => inputs.size,
+        :encoders => encoders.size,
+    	})
+    end
+
+    # Sets an input change handler callback function. This is called when a digital input on the PhidgetEncoder board has changed.
+    #
+    # @param [String] obj Object to pass to the callback function. This is optional.
+    # @param [Proc] Block When the callback is executed, the device and object are yielded to this block.
+    # @example
+    #     en.on_input_change do |device, input, state, obj|
+    #       print "Digital Input  #{input.index}, changed to #{state}\n"
+    #     end
+    # As this runs in it's own thread, be sure that all errors are properly handled or the thread will halt and not fire any more.
+    # @return [Boolean] returns true or raises an error
+    def on_input_change(obj=nil, &block)
+      @on_input_change_obj = obj
+      @on_input_change = Proc.new { |device, obj_ptr, index, state|
+        yield self, @inputs[index], (state == 0 ? false : true), object_for(obj_ptr)
+      }
+      Klass.set_OnInputChange_Handler(@handle, @on_input_change, pointer_for(obj))
+    end
+    
+    # Sets a position change handler callback function. This is called when an encoder position changes.
+    #
+    # @param [String] obj Object to pass to the callback function. This is optional.
+    # @param [Proc] Block When the callback is executed, the device and object are yielded to this block.
+    # @example
+    #     en.on_position_change do |device, encoder, time, position_change, obj|
+    #       puts "Encoder #{encoder.index} changed by #{position_change} - Time: #{time}"
+    #     end
+    # As this runs in it's own thread, be sure that all errors are properly handled or the thread will halt and not fire any more.
+    # @return [Boolean] returns true or raises an error
+    def on_position_change(obj=nil, &block)
+      @on_position_change_obj = obj
+      @on_position_change = Proc.new { |device, obj_ptr, index, time, position_change|
+	    yield self, @encoders[index], time, position_change, object_for(obj_ptr)
+	}
+      Klass.set_OnPositionChange_Handler(@handle, @on_position_change, pointer_for(obj))
+    end
+	
+ # This class represents a digital input a PhidgetEncoder. All the properties of an digital input are stored and modified in this class.
+  class EncoderDigitalInputs 
+    Klass = Phidgets::FFI::CPhidgetEncoder
+
+	private
+	def initialize(handle, index)
+      @handle, @index = handle, index.to_i
+	end
+
+	public
+
+	# Displays data for the digital input
+    def inspect
+      "#<#{self.class} @index=#{index}, @state=#{state}>"
+    end
+
+	# @return [Integer] returns index of the digital input, or raises an error.
+	def index 
+		@index
+	end
+	
+	# @return [Boolean] returns state of the digital input, or raises an error.
+    def state
+      ptr = ::FFI::MemoryPointer.new(:int)
+      Klass.getInputState(@handle, @index, ptr)
+      (ptr.get_int(0) == 0) ? false : true
+    end
+	
+	# @return [Boolean] returns true if the state is true.
+    def on
+      state == true
+    end
+	alias_method :on?, :on
+    
+	# @return [Boolean] returns true if the state is off.
+    def off
+      !on
+    end
+    alias_method :off?, :off
+  end #EncoderDigitalInputs
+  
+  # This class represents a encoder for a PhidgetEncoder. All the properties of an encoder are stored and modified in this class.
+  class EncoderEncoders
+    Klass = Phidgets::FFI::CPhidgetEncoder
+
+	private
+    def initialize(handle, index)
+      @handle, @index = handle, index.to_i
+    end
+
+	public
+	# Displays data for the encoder.
+    def inspect
+      "#<#{self.class} @index=#{index}, @position=#{position}>"
+	
+	end
+
+	# @return [Integer] returns the index of the encoder, or raises an error.
+	def index 
+		@index
+	end
+	
+	# @return [Integer] returns the index position for an encoder that supports index, or raises an error.
+    def index_position
+      ptr = ::FFI::MemoryPointer.new(:int)
+      Klass.getIndexPosition(@handle, @index, ptr)
+      ptr.get_int(0)
+    end
+
+	# @return [Boolean] returns the enabled state of a encoder, or raises an error.
+    def enabled
+      ptr = ::FFI::MemoryPointer.new(:int)
+      Klass.getEnabled(@handle, @index, ptr)
+      (ptr.get_int(0) == 0) ? false : true
+    end
+
+	# Sets the enabled state of an encoder, or raises an error.
+	# @param [Boolean] new_state new state
+	# @return [Boolean] returns enabled state of an encoder, or raises an error.
+    def enabled=(new_state)
+      tmp = new_state ? 1 : 0
+      Klass.setEnabled(@handle, @index, tmp)
+      new_state
+    end
+
+	# @return [Integer] returns the position of an encoder, or raises an error.
+    def position
+      ptr = ::FFI::MemoryPointer.new(:int)
+      Klass.getPosition(@handle, @index, ptr)
+      ptr.get_int(0)
+    end
+	
+	# Sets the position of an encoder, or raises an error.
+	# @param [Integer] new_position new position
+	# @return [Integer] returns the position of an encoder, or raises an error.
+    def position=(new_position)
+      Klass.setPosition(@handle, @index, new_position.to_i)
+      new_position
+    end	
+	
+  end #EncoderEncoders
+  
+	private
+    
+	def load_device_attributes
+	  load_inputs
+	  load_encoders
+	end
+
+    def load_inputs
+	  ptr = ::FFI::MemoryPointer.new(:int)
+      Klass.getInputCount(@handle, ptr)
+      @inputs = []
+      ptr.get_int(0).times do |i|
+        @inputs << EncoderDigitalInputs.new(@handle, i)
+      end
+    end
+
+    def load_encoders
+	  ptr = ::FFI::MemoryPointer.new(:int)
+      Klass.getEncoderCount(@handle, ptr)
+      @encoders = []
+      ptr.get_int(0).times do |i|
+        @encoders << EncoderEncoders.new(@handle, i)
+      end
+    end
+
+	def remove_specific_event_handlers
+	   Klass.set_OnInputChange_Handler(@handle, nil, nil)
+	   Klass.set_OnPositionChange_Handler(@handle, nil, nil)
+	end
+  end
+
+end