phidgets-ffi 0.0.5 → 0.1.0

data/.gitignore

@@ -1,3 +1,6 @@
 pkg/*
 *.gem
 .bundle
+.svn/
+.yardoc/
+.doc/

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011, Kelley Reynolds
+Copyright (c) 2011, Kelley Reynolds, Phidgets
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

data/README.rdoc

@@ -5,47 +5,104 @@ available from http://www.phidgets.com.
 
 =Phidgets-FFI
 
-This is a set of FFI bindings for the Phidgets library available for most platforms.
-Currently, it only supports the devices available to me but it to but it supports them completely.
-It also supports the manager, dictionary, logging, callbacks function perfectly, and there
-are a set of idiomatic bindings that take the provided API and make it more accessible. Raw FFI
-examples are in examples/ffi and the idiomatic versions are in examples/.
+This is a set of FFI bindings for the Phidgets library available for Mac OS X and Linux.
+There are a set of idiomatic bindings that take the provided API and make it more accessible. 
+Idiomatic examples are in examples/ and the Raw FFI examples are in examples/raw-ffi.
 
-==Quick Start
+==Environment and Libraries
+First, we need to set up the proper environment and get the necessary files off the Phidgets website. Visit the drivers section at www.phidgets.com and get the latest Phidget driver for your system. You will also need to install the phidgets-ffi gem from RubyGems. More information will be provided in the "Installing the phidgets-ffi gem" section of this document.
 
-To access the manager and see your attached devices:
+We also recommend that you download the following reference materials:
+* {Programming Manual}[http://www.phidgets.com/programming_resources.php]:
+* The {Product Manual}[http://www.phidgets.com] for your device
+* {RubyDoc API Documentation}[http://rubydoc.info/gems/phidgets-ffi/frames]
+* {Ruby code samples}[https://github.com/kreynolds/phidgets-ffi/tree/master/examples]
 
-  Phidgets::Manager.new do |manager|
-    puts manager.devices.inspect
+The RubyDoc API manual contains calls and events for every type of Phidget and can be used as a reference. You can find a high level discussion about programming with Phidgets in general in the Programming Manual. The Product manual for your device also contains an API section that describes limitations, defaults, and implementation details specific to your Phidget. You may want to have these manuals open while working through these instructions.
+
+==Installing the phidgets-ffi gem
+To install:
+  gem install phidgets-ffi
+
+phidgets-ffi is dependent on the ffi(>=1.0.9) gem. If the above command does not automatically install the gem for you, please enter:
+  gem install ffi
+
+==Coding for your Phidget
+Before you can use the Phidget, you must include a reference to the phidgets-ffi gem:
+  require "rubygems"
+  require "phidgets-ffi"
+
+Afterwards, the Phidget constructor method will need to be called to create the Phidget object. There are two methods of programming with Phidgets in Ruby: with a block and without a block. For the most part, the two methods behave the same, but there are some subtle differences, which will be explained in the next section.
+
+Without a block:
+  ifkit = Phidgets::InterfaceKit.new
+
+With a block:
+  Phidgets::InterfaceKit.new do |ifkit|
+    ...
+  end
+
+The object name for any type of Phidget is listed in the API manual. Every type of Phidget also inherits functionality from the Phidget base class. In the above example, InterfaceKit represents the PhidgetInterfaceKit. For simplicity in explaining the programming concepts, the remainder of this document will use the InterfaceKit object.
+
+==Connecting to the Phidget
+The program needs to try and connect to the Phidget. Options can be added to the InterfaceKit constructor to connect to the first Phidget it finds, based on its serial number, label, or even connect across the network. Rubydocs API Documentation lists all of the available modes that the constructor provides. 
+
+For example, the following will try to connect to the first Phidget it finds:
+  ifkit = Phidgets::InterfaceKit.new
+
+The following will try to connect to a Phidget over the Phidget WebService with a serial number of  99999, and a server id of "myserver":
+
+  options = {:serial_number => 99999, :server_id => "myserver", :password => nil}
+  ifkit = Phidgets::InterfaceKit.new(options)
+
+One important thing to remember is that when working with Phidgets, a local connection will reserve the device until closed. This prevents any other instances from retrieving data from the Phidget, including other programs. The one connection per device limit does not apply when exclusively using the Phidget Webservice
+
+Phidgets::InterfaceKit.new will tell the program to continuously try to connect to a Phidget, based on the options given(if any), even trying to reconnect if it gets disconnected. 
+
+==Non Block Programming
+For the non block programming method, simply calling the constructor does not guarantee you can use the Phidget immediately. We can handle this by using event driven programming and tracking the on_attach and on_detach events, or by calling: wait_for_attachment. wait_for_attachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded.
+
+  ifkit = Phidgets::InterfaceKit.new
+  ifkit.wait_for_attachment 2000 #halt the program for up 2000 milliseconds or until the Phidget is connected
+
+Please also remember to call close at the end or the program to free any locks on the Phidget
+
+  ifkit.close
+
+==Block Programming
+If you are programming inside a block, wait_for_attachment is automatically called. By default, it will halt the program and try to connect to the Phidget for up to 1000 milliseconds. Afterwards, the block will yield. Finally, close is not needed as it is automatically called once the block has yield.
+
+  options = {:timeout => 2000)
+  Phidgets::InterfaceKit.new(options) do |ifkit|
+    ...
   end
-  
-  [{
-    :type=>"PhidgetServo",
-    :label=>"",
-    :device_id=>:servo_1motor,
-    :serial_number=>12345,
-    :name=>"Phidget Servo Controller 1-motor",
-    :device_class=>:servo,
-    :version=>313
-  }]
-
-To access that servo controller and do something with the servo:
-
-  Phidgets::ServoController.new(12345) do |controller|
-    servo = controller.servos[0]
-
-    controller.on_change do |servo, position, data|
-      print "Moving servo #{servo.index} to #{position}\n"
-    end
-  
-    max = servo.max
-    10.times do
-      servo.position = rand(max)
-      sleep 1
-    end
-    servo.engaged = false
+
+==Event Driven Programming
+
+We recommend the use of event driven programming when working with Phidgets. In Ruby, we can hook an event handler at loading with the following code:  
+
+  ifkit.on_sensor_change do |device, input, value, obj|
+    puts "Sensor #{input.index}'s value has changed to #{value}"
   end
 
+With this method, the block inside on_sensor_change will get executed every time the 
+PhidgetInterfaceKit reports a change on one of its analog inputs. Some events such as on_attach and on_detach belong to the base Phidget object and thus are common to all types of Phidgets. Please refer to the RubyDoc API documentation for a full list of events and their usage. 
+
+==Working directly with the Phidget
+Some values can be read and sent directly to the Phidget, simply use the instance members and properties. This is also how you would set properties on the Phidget such as the output state or sensor sensitivity. These functions can be used inside a polling loop as an alternative to event driven programming. 
+
+  puts "Serial number: #{ifkit.serial_number}"
+  puts "Sensor value[0]: #{ifkit.sensors[0].value}"
+
+==Working with Multiple Phidgets
+Multiple Phidgets of the same type can easily be run inside the same program. In our case, it requires another InterfaceKit instance to be defined and initialized. The new instance can then be set up, opened and used in the same process as the previous one. If the application needs to distinguish between the devices, the constructor can be called with the serial number or label of a specific Phidget.
+
+==Other Phidgets
+The design given in this document can also be followed for almost all Phidgets. For example, if you were using a PhidgetRFID instead of a PhidgetInterfacekit, you would declare an RFID object instead of an InterfaceKit. The methods and events available would change but they can be accessed in a similar manner.
+
+==Raw FFI
+As an alternative to programming with the method as outlined in this document, you can also program making straight C calls through FFI. Please refer to the files in lib/phidgets-ffi/ffi/ to see a list of available methods, and the {C API}[http://www.phidgets.com/programming_resources.php] for usage. There are raw ffi examples in examples/raw-ffi/.
+
 ==Logging
 
 Logging can be accomplished by either accessing the C library directly or using the idiomatic method.
@@ -55,10 +112,3 @@ There are additional examples of each in the examples/ directory.
   Phidgets::Log.info('identifier', 'message')
   Phidgets::Log.error('identifier', 'message')
   Phidgets::Log.disable
-
-==Notes
-
-Again, note that not every device is here. I'm more than happy to add support for it
-but I'll need a test device to make sure it works ;)
-
-P.S. Seriously, contact me if you want my mailing address to send me a device you'd like this library to support.

data/examples/accelerometer.rb

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'phidgets-ffi'
+
+puts "Library Version: #{Phidgets::FFI.library_version}"
+
+accel = Phidgets::Accelerometer.new 
+
+puts "Wait for PhidgetAccelerometer to attached..."
+	  
+#The following method runs when the PhidgetAccelerometer is attached to the system
+accel.on_attach  do |device, obj|
+	 
+    puts "Device attributes: #{device.attributes} attached"
+    puts "Class: #{device.device_class}"
+	puts "Id: #{device.id}"
+	puts "Serial number: #{device.serial_number}"
+	puts "Version: #{device.version}"
+	puts "# Axes: #{device.axes.size}"
+
+	puts device.axes[0].inspect
+	puts "Accleration[0]: #{device.axes[0].acceleration}"
+	puts "Acceleration min[0]: #{device.axes[0].acceleration_min}"
+	puts "Acceleration max[0]: #{device.axes[0].acceleration_max}"
+end
+	 
+accel.on_detach  do |device, obj|
+	puts "#{device.attributes.inspect} detached"
+end
+
+accel.on_error do |device, obj, code, description|
+	puts "Error #{code}: #{description}"
+end
+
+accel.on_acceleration_change do |device, axis, value|
+ 	puts "Axis #{axis.index}'s acceleration has changed to #{value}"
+end 
+
+sleep 10
+accel.close

data/examples/advanced_servo.rb

@@ -0,0 +1,94 @@
+require 'rubygems'
+require 'phidgets-ffi'
+
+puts "Library Version: #{Phidgets::FFI.library_version}"
+
+adv = Phidgets::AdvancedServo.new
+	  
+puts "Wait for PhidgetAdvancedServo to attached..."
+
+#The following method runs when the PhidgetAdvancedServo is attached to the system
+adv.on_attach  do |device, obj|
+	 
+    puts "Device attributes: #{device.attributes} attached"
+    puts "Class: #{device.device_class}"
+	puts "Id: #{device.id}"
+	puts "Serial number: #{device.serial_number}"
+	puts "Version: #{device.version}"
+	puts "# Servos: #{device.advanced_servos.size}"
+
+	device.advanced_servos[0].engaged = true
+	sleep 1  #allow time for engaged to be set before event ends
+
+end
+	 
+adv.on_detach  do |device, obj|
+	puts "#{device.attributes.inspect} detached"
+end
+
+adv.on_error do |device, obj, code, description|
+	puts "Error #{code}: #{description}"
+end
+
+adv.on_velocity_change do |device, servo, velocity, obj|
+    puts "Servo #{servo.index}'s velocity has changed to #{velocity}"
+end
+
+adv.on_position_change do |device, servo, position, obj|
+    puts "Servo #{servo.index}'s position has changed to #{position}"
+end
+
+adv.on_current_change do |device, servo, current, obj|
+    puts "Servo #{servo.index}'s current has changed to #{current}"
+end
+
+sleep 3
+
+if(adv.attached?)
+
+	max = adv.advanced_servos[0].position_max
+	3.times do
+		adv.advanced_servos[0].position = rand(max)
+		sleep 0.5
+	end
+
+	puts "Setting servo parameters: #{adv.advanced_servos[0].set_servo_parameters(600, 2000, 120, 1500)}"
+	
+	puts "Acceleration: #{adv.advanced_servos[0].acceleration}"
+	puts "Acceleration min: #{adv.advanced_servos[0].acceleration_min}"
+	puts "Acceleration max: #{adv.advanced_servos[0].acceleration_max}"
+	puts "Current: #{adv.advanced_servos[0].current}"
+	puts "Speed ramp: #{adv.advanced_servos[0].speed_ramping}"
+	puts "Stopped: #{adv.advanced_servos[0].stopped}"
+	puts "Type: #{adv.advanced_servos[0].type}"
+	puts "Velocity: #{adv.advanced_servos[0].velocity}"
+	sleep 2
+
+	adv.advanced_servos[0].velocity_limit = 200
+	sleep 1
+	puts "Velocity limit: #{adv.advanced_servos[0].velocity_limit}"
+	puts "Velocity max: #{adv.advanced_servos[0].velocity_max}"
+	puts "Velocity min: #{adv.advanced_servos[0].velocity_min}"
+
+	adv.advanced_servos[0].acceleration = 89
+	adv.advanced_servos[0].position_max = 160
+	adv.advanced_servos[0].position_min = 5
+	adv.advanced_servos[0].speed_ramping = true
+	adv.advanced_servos[0].type = Phidgets::FFI::AdvancedServoType[:default]
+	puts "Type: #{adv.advanced_servos[0].type}"
+
+	begin	
+		puts "Position: #{adv.advanced_servos[0].position}" #An error is raised when the position is unknown
+	rescue Phidgets::Error::UnknownVal => e
+		puts "Exception caught: #{e.message}"
+	end
+
+	puts "Position max: #{adv.advanced_servos[0].position_max}"
+	puts "Position min: #{adv.advanced_servos[0].position_min}"
+
+end
+
+sleep 2
+adv.advanced_servos[0].engaged = false
+sleep 1
+adv.close

data/examples/analog.rb

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'phidgets-ffi'
+
+puts "Library Version: #{Phidgets::FFI.library_version}"
+
+an = Phidgets::Analog.new
+	  
+puts "Wait for PhidgetAnalog to attached..."
+	  
+#The following method runs when the PhidgetAnalog is attached to the system
+an.on_attach  do |device, obj|
+	 
+    puts "Device attributes: #{device.attributes} attached"
+    puts "Class: #{device.device_class}"
+	puts "Id: #{device.id}"
+	puts "Serial number: #{device.serial_number}"
+	puts "Version: #{device.version}"
+	puts "# Outputs: #{device.outputs.size}"
+
+	puts "Voltage min: #{device.outputs[0].voltage_min}"
+	puts "Voltage max: #{device.outputs[0].voltage_max}"
+	  
+	device.outputs[0].enabled = true
+	sleep 1
+	device.outputs[0].voltage = 2.2
+	  
+	sleep 3
+
+	device.outputs[0].enabled = false													
+        sleep 1
+end
+	 
+an.on_detach  do |device, obj|
+	puts "#{device.attributes.inspect} detached"
+end
+
+an.on_error do |device, obj, code, description|
+	puts "Error #{code}: #{description}"
+end
+
+sleep 5
+
+an.close

data/examples/bridge.rb

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'phidgets-ffi'
+
+puts "Library Version: #{Phidgets::FFI.library_version}"
+
+br = Phidgets::Bridge.new
+
+puts "Wait for PhidgetBridge to attached..."
+	  
+#The following method runs when the PhidgetBridge is attached to the system
+br.on_attach  do |device, obj|
+	 
+    puts "Device attributes: #{device.attributes} attached"
+    puts "Class: #{device.device_class}"
+	puts "Id: #{device.id}"
+	puts "Serial number: #{device.serial_number}"
+	puts "Version: #{device.version}"
+	puts "# Inputs: #{device.inputs.size}"
+
+	device.inputs[0].enabled = true
+	device.inputs[0].gain = Phidgets::FFI::BridgeGains[:gain_32]
+	device.data_rate = 64
+
+	sleep 1
+	
+	puts "Enabled: #{device.inputs[0].enabled}"
+	puts "Gain: #{device.inputs[0].gain}"
+	
+end
+	 
+br.on_detach  do |device, obj|
+	puts "#{device.attributes.inspect} detached"
+end
+
+br.on_error do |device, obj, code, description|
+	puts "Error #{code}: #{description}"
+end
+
+br.on_bridge_data do |device, inputs, value|
+ 	puts "Bridge #{inputs.index}'s value changed to #{value}"
+end 
+
+sleep 5
+
+if(br.attached?)
+	5.times do
+		begin	
+			puts "Bridge Value[0]: #{br.inputs[0].bridge_value}"  
+		rescue Phidgets::Error::UnknownVal => e
+			puts "Exception caught: #{e.message}"
+		end
+		sleep 0.5	
+	end
+end
+
+sleep 5
+br.close

data/examples/dictionary.rb

@@ -4,43 +4,58 @@ require 'phidgets-ffi'
 Phidgets::Log.enable(:verbose)
 
 puts "Library Version: #{Phidgets::FFI.library_version}"
-Phidgets::Dictionary.new do |dict|
-  dict.on_error do |obj, code, reason|
+
+dict = Phidgets::Dictionary.new
+
+dict.on_error do |obj, code, reason|
     puts "Error (#{code}): #{reason}"
   end
+
   dict.on_connect do |obj|
-    print "Connected!\n"
-  end
-  dict.on_disconnect do |obj|
-    print "Disconnected!\n"
+    puts "Connected!"
+		#Listening for every pattern
+		dict.on_change do |obj, key, val, reason|
+		  puts "Every key: #{key} => #{val}-- #{reason}"
+		end
+
+		dict.on_change('snoop') do |obj, key, val, reason|
+		  puts "Keys matching snoop: #{key} => #{val}-- #{reason}"
+		end
+
+		#Patterns an also be of ruby type: Regexp
+		dict.on_change(/test.*/) do |obj, key, val, reason|  
+		  puts "Keys matching /test.*/: #{key} => #{val}-- #{reason}"
+		end
+	end
+
+	dict.on_disconnect do |obj|
+    puts "Disconnected!"
   end
   
-  dict.on_change('fnord') do |obj, key, val, reason|
-      print "Fnord key: #{key} => #{val}, #{reason}\n"
-  end
-  dict.on_change do |obj, key, val, reason|
-      print "Every key: #{key} => #{val}, #{reason}\n"
-  end
-  dict.on_change('test') do |obj, key, val, reason|
-      print "Keys matching test: #{key} => #{val}, #{reason}\n"
-  end
+options = {:address => 'localhost', :port => 5001, :password => nil}
+dict.open(options)
+  
+sleep 5
+if dict.status.to_s == 'connected'
+	puts "Listening to: #{dict.listeners.inspect}"
 
-  puts "Listening to: #{dict.listeners.inspect}"
+	dict.remove_on_change('snoop')
 
-  dict.remove_on_change('fnord')
+	puts "Listening to: #{dict.listeners.inspect}"
 
-  puts "Listening to: #{dict.listeners.inspect}"
 
-  dict["fnord"] = "This is a fnordic key"
-  dict["test"] = "This is a key that is called test"
-  dict["fnord"] = nil
-  dict["snoop"] = nil
-  20.times do |i|
-    print "#{i}\n"
-    begin
-      dict["testerson"] = "This is another test matching key"
-    rescue Phidgets::Error::NetworkNotConnected
-    end
-    sleep 1
-  end
-end
+	dict["fnord"] = {:value => "This is a fnordic key", :persistent => true}
+	dict["test"] = {:value => "This is a key that is called test", :persistent => false}
+	dict["test"] = nil
+	  
+	20.times do |i|
+		print "#{i}\n"
+		begin
+		  dict["snoop"] = {:value => "value: #{i}"}
+		  dict["testerson"] = {:value => "This is another test matching key"}
+		  
+		rescue Phidgets::Error::NetworkNotConnected
+	    end
+	    sleep 1
+	end
+end