Module: Phidgets::Common

Includes:
Utility
Included in:
Accelerometer, AdvancedServo, Analog, Bridge, Encoder, FrequencyCounter, GPS, IR, InterfaceKit, LED, MotorControl, RFID, Servo, Spatial, Stepper, TemperatureSensor, TextLCD
Defined in:
lib/phidgets-ffi/common.rb

Overview

This is the base class from which all Phidget device classes derive.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#attributes ⇒ Object (readonly)

The attributes of a Phidget



614
615
616
 
# File 'lib/phidgets-ffi/common.rb', line 614

def attributes
  @attributes
end

Class Method Details

.attributes(handle) ⇒ Object 



599
600
601
602
603
604
605
606
607
608
609
 
# File 'lib/phidgets-ffi/common.rb', line 599

def self.attributes(handle)
  {
    :type => type(handle),
    :name => name(handle),
    :serial_number => serial_number(handle),
    :version => version(handle),
    :label => label(handle),
    :device_class => device_class(handle),
    :device_id => device_id(handle),
  }
end

.device_class(handle) ⇒ Object 



570
571
572
573
574
 
# File 'lib/phidgets-ffi/common.rb', line 570

def self.device_class(handle)
  ptr = ::FFI::MemoryPointer.new(:int)
  Phidgets::FFI::Common.getDeviceClass(handle, ptr)
  Phidgets::FFI::DeviceClass[ptr.get_int(0)]
end

.device_id(handle) ⇒ Object 



564
565
566
567
568
 
# File 'lib/phidgets-ffi/common.rb', line 564

def self.device_id(handle)
  ptr = ::FFI::MemoryPointer.new(:int)
  Phidgets::FFI::Common.getDeviceID(handle, ptr)
  Phidgets::FFI::DeviceID[ptr.get_int(0)]
end

.server_address(handle) ⇒ Object 



583
584
585
586
587
588
589
590
 
# File 'lib/phidgets-ffi/common.rb', line 583

def self.server_address(handle)
	  str_ptr, int_ptr = ::FFI::MemoryPointer.new(:string), ::FFI::MemoryPointer.new(:int)
	  Phidgets::FFI::Common.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)
  [address, port]
end

.server_id(handle) ⇒ Object 



576
577
578
579
580
581
 
# File 'lib/phidgets-ffi/common.rb', line 576

def self.server_id(handle)
  ptr = ::FFI::MemoryPointer.new(:string)
  Phidgets::FFI::Common.getServerID(handle, ptr)
  strPtr = ptr.get_pointer(0)
  strPtr.null? ? nil : strPtr.read_string
end

.server_status(handle) ⇒ Object 



592
593
594
595
596
597
 
# File 'lib/phidgets-ffi/common.rb', line 592

def self.server_status(handle)
  ptr = ::FFI::MemoryPointer.new(:int)
  Phidgets::FFI::Common.getServerStatus(handle, ptr)
	  #(ptr.get_int(0) == 0) ? false : true
	  Phidgets::FFI::ServerStatus[ptr.get_int(0)]
end

Instance Method Details

#attached? ⇒ Boolean

Returns the attached status

Returns:

  • (Boolean) —

    returns the attached status



291
292
293
 
# File 'lib/phidgets-ffi/common.rb', line 291

def attached?
		Common.device_status(@handle);
end

#attached_to_server? ⇒ Boolean

Returns the server status of this Phidget or raises an error

Returns:

  • (Boolean) —

    returns the server status of this Phidget or raises an error



345
346
347
 
# File 'lib/phidgets-ffi/common.rb', line 345

def attached_to_server?
	  Common.server_status(@handle)
end

#close ⇒ Boolean

Closes and frees a Phidget. This should be called before closing your application or things may not shut down cleanly.

Returns:

  • (Boolean) —

    returns true or raises an error



253
254
255
256
257
258
259
260
 
# File 'lib/phidgets-ffi/common.rb', line 253

def close
	  remove_common_event_handlers
	  remove_specific_event_handlers
	  sleep 0.2
  Phidgets::FFI::Common.close(@handle) 
	  delete
  true
end

#detached? ⇒ Boolean

Returns the detached status

Returns:

  • (Boolean) —

    returns the detached status



298
299
300
 
# File 'lib/phidgets-ffi/common.rb', line 298

def detached?
  !attached?
end

#detached_to_server? ⇒ Boolean

Returns the detached to server status of this Phidget or raises an error

Returns:

  • (Boolean) —

    returns the detached to server status of this Phidget or raises an error



350
351
352
 
# File 'lib/phidgets-ffi/common.rb', line 350

def detached_to_server?
  !attached_to_server?
end

#device_class ⇒ String

Returns the device class of the Phidget

Returns:

  • (String) —

    returns the device class of the Phidget, or raises an error



331
 
# File 'lib/phidgets-ffi/common.rb', line 331

def device_class; Common.device_class(@handle); end

#id ⇒ String

Returns the device id of the Phidget

Returns:

  • (String) —

    returns the device id of the Phidget, or raises an error



325
 
# File 'lib/phidgets-ffi/common.rb', line 325

def id; Common.device_id(@handle); end

#initialize(options = nil, &block) ⇒ Object

Initializes a Phidget. There are two methods that you can use to program Phidgets.

First Method: You can program with a block

Phidgets::InterfaceKit.new do |ifkit| 
  ...
end

Second Method: You can program without a block

ifkit = Phidgets::InterfaceKit.new

The constructor accepts optional arguments. Depending on what is specified as options, a Phidget will be opened in a different manner. The timeout is used for block programming; if no timeout is specified, the default timeout(1000 milliseconds) will be used. Please note that if you are not using the block method and specify a timeout, the timeout will be ignored.

The first available Phidget that meets all the criteria will be opened. If there are two Phidgets of the same type attached to the system, you should specify a serial number or label, as there is no guarantee which Phidget will be selected by the call.

Usage:

Open the first available Phidget with an optional timeout(milliseconds).

Specify 0 for timeout to wait forever.

Parameters: (Integer)

new({:timeout => 5000})

<br/>

Open a Phidget using a serial number, and an optional timeout(milliseconds).

Specify -1 for serial number to open any. Specify 0 for timeout to wait forever.

Parameters: (Integer, Integer)

new({:serial_number => -1, :timeout => 5000})

<br/>

Open a Phidget using a specific label, and an optional timeout(milliseconds).

Specify nil for device label to open any. Specify 0 for timeout to wait forever.

Parameters: (String, Integer)

new({:label => nil, :timeout => 5000})

<br/>

Open a Phidget remotely and securely, using a specific serial number, server id, password, and an optional timeout(milliseconds).

Specify -1 for serial number to open any. Specify nil for password if it is not required. Specify 0 for timeout to wait forever.

Parameters: (Integer, String, String, Integer)

new({:serial_number => -1, :server_id => 'phidgetsbc', :password => nil, :timeout => 5000})

<br/>

Open a Phidget remotely and securely, using a specific serial number, IP Address, port, password, and an optional timeout(milliseconds).

Specify -1 for serial number to open any. Specify nil for password if it is not required. Specify 0 for timeout to wait forever.

Parameters: (Integer, String, Integer, String, Integer)

new({:serial_number => -1, :server_address => 'localhost', :port => 5001, :password => nil, :timeout => 5000})

<br/>

Open a Phidget remotely and securely, using a specific device label, server id, password, and an optional timeout(milliseconds).

Specify nil for device label to open any. Specify nil for password if it is not required. Specify 0 for timeout to wait forever.

Parameters: (String, String, String, Integer)

new({:label => nil, :server_id => 'phidgetsbc', :password => nil, :timeout => 5000})

<br/>

Open a Phidget remotely and securely, using a specific label, server address, port, password, and an optional timeout(milliseconds).

Specify nil for device label to open any. Specify nil for password if it is not required. Specify 0 for timeout to wait forever.

Parameters: (String, String, Integer, String, Integer)

new({:label => nil, :server_address => 'localhost', :port => 5001, :password => nil, :timeout => 5000})

Parameters:

  • options (Integer) (defaults to: nil) —

    The first available Phidget that meets all the criteria will be opened.

  • Block (Proc) —

    initialize will automatically will open and call wait_for_attachment on the Phidget. Then, the block will yield. Afterwards, close is automatically called.

Returns:

  • (Object) 


133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/phidgets-ffi/common.rb', line 133

def initialize(options=nil, &block)
create
args_for_open = 0
with_wait_time = false
args_to_consider = 0

if !options.nil?
	
	label = (options[:label].nil? ? nil : options[:label].to_s)
	serial_number = (options[:serial_number].nil? ? -1 : options[:serial_number].to_i)
	password = (options[:password].nil? ? nil : options[:password].to_s)
	
	if !options[:server_id].nil?
		if !label.nil?
			open_label_remote(label, options[:server_id].to_s, password)
		else
			open_remote(serial_number, options[:server_id].to_s, password)
		end
	elsif !options[:address].nil?
		if !label.nil?
			open_label_remote_ip(label, options[:address].to_s, options[:port].to_i, password)
		else
			open_remote_ip(serial_number, options[:address].to_s, options[:port].to_i, password)
		end
	else #local
	
		if !label.nil?
			open_label(label)
		else
			open(serial_number)
		end
	end
	
else    #option is not specified
	open(-1)
end


     if block_given?
	if !options.nil? && !options[:timeout].nil? #timeout is given
		wait_for_attachment options[:timeout].to_i
	else
		wait_for_attachment #use default wait time
	end
	yield self
       close
  end
end

#label ⇒ String

Returns the label of the Phidget

Returns:

  • (String) —

    returns the label of the Phidget, or raises an error



336
 
# File 'lib/phidgets-ffi/common.rb', line 336

def label; Common.label(@handle); end

#label=(new_label) ⇒ String

Sets the label of a Phidget. Note that this is not supported on very old Phidgets, and not yet supported in Windows. The label can be up to ten characters, and is stored in the Flash memory of newer Phidgets. This label can be set programatically, and is non-volatile - so it is remembered even if the Phidget is unplugged.

Parameters:

  • new_label (String) —

    New label

Returns:

  • (String) —

    returns the label, or raises an error



559
560
561
562
 
# File 'lib/phidgets-ffi/common.rb', line 559

def label=(new_label)
	  Phidgets::FFI::Common.setDevicelabel(@handle, new_label)
	  new_label
end

#name ⇒ String

Returns the name of the Phidget

Returns:

  • (String) —

    returns the name of the Phidget, or raises an error



305
 
# File 'lib/phidgets-ffi/common.rb', line 305

def name; Common.name(@handle); end

#on_attach(obj = nil, &block) ⇒ Boolean

Sets an attach handler callback function. This is called when the Phidget is plugged into the system, and is ready for use.

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.

Examples:

ifkit.on_attach do |device, obj|
  puts "InterfaceKit attached #{device.attributes.inspect}"
end

Parameters:

  • obj (String) (defaults to: nil) —

    Object to pass to the callback function. This is optional.

  • Block (Proc) —

    When the callback is executed, the device and object are yielded to this block.

Returns:

  • (Boolean) —

    returns true or raises an error



364
365
366
367
368
369
370
371
372
 
# File 'lib/phidgets-ffi/common.rb', line 364

def on_attach(obj=nil, &block)
	  @on_attach_obj = obj
  @on_attach = Proc.new { |handle, obj_ptr|
		load_device_attributes
    yield self, object_for(obj_ptr)
	 }
  Phidgets::FFI::Common.set_OnAttach_Handler(@handle, @on_attach, pointer_for(obj))
	  true
end

#on_detach(obj = nil, &block) ⇒ Boolean

Sets a detach handler callback function. This is called when the Phidget is physically detached from the system, and is no longer available.

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.

Examples:

ifkit.on_detach do |device, obj|
  puts "InterfaceKit detached #{device.attributes.inspect}"
end

Parameters:

  • obj (String) (defaults to: nil) —

    Object to pass to the callback function. This is optional.

  • Block (Proc) —

    When the callback is executed, the device and object are yielded to this block.

Returns:

  • (Boolean) —

    returns true or raises an error



384
385
386
387
388
389
390
391
 
# File 'lib/phidgets-ffi/common.rb', line 384

def on_detach(obj=nil, &block)
  @on_detach_obj = obj
  @on_detach = Proc.new { |handle, obj_ptr|
    yield self, object_for(obj_ptr)
  }
  Phidgets::FFI::Common.set_OnDetach_Handler(@handle, @on_detach, pointer_for(obj))
	  true
end

#on_error(obj = nil, &block) ⇒ Boolean

Sets an error handler callback function. This is called when an asynchronous error occurs. This is generally used for network errors, and device hardware error messages.

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.

Examples:

ifkit.on_error do |device, obj, code, description|
  puts "Error - code #{code}, description #{description}"
end

Parameters:

  • obj (String) (defaults to: nil) —

    Object to pass to the callback function. This is optional.

  • Block (Proc) —

    When the callback is executed, the device and object are yielded to this block.

Returns:

  • (Boolean) —

    returns true or raises an error



403
404
405
406
407
408
409
410
 
# File 'lib/phidgets-ffi/common.rb', line 403

def on_error(obj=nil, &block)
  @on_error_obj = obj
  @on_error = Proc.new { |handle, obj_ptr, code, description|
    yield self, object_for(obj_ptr), code, description
  }
  Phidgets::FFI::Common.set_OnError_Handler(@handle, @on_error, pointer_for(obj))
	  true
end

#on_server_connect(obj = nil, &block) ⇒ Boolean

Sets a server connect handler callback function. This is called for network opened Phidgets when a connection to the PhidgetWebService has been established.

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.

Examples:

ifkit.on_server_connect do |device, obj|
  puts "Server connect #{device.attributes.inspect}"
end

Parameters:

  • obj (String) (defaults to: nil) —

    Object to pass to the callback function. This is optional.

  • Block (Proc) —

    When the callback is executed, the device and object are yielded to this block.

Returns:

  • (Boolean) —

    returns true or raises an error



422
423
424
425
426
427
428
429
 
# File 'lib/phidgets-ffi/common.rb', line 422

def on_server_connect(obj=nil, &block)
  @on_server_connect_obj = obj
  @on_server_connect = Proc.new { |handle, obj_ptr|
    yield self, object_for(obj_ptr)
  }
  Phidgets::FFI::Common.set_OnServerConnect_Handler(@handle, @on_server_connect, pointer_for(obj))
	  true
end

#on_server_disconnect(obj = nil, &block) ⇒ Boolean

Sets a server disconnect handler callback function. This is called for network opened Phidgets when a connectiotn to the PhidgetWebService has been broken - either by calling close, or by network trouble, etc.…

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.

Examples:

ifkit.on_server_disonnect do |device, obj|
  puts "Server disonnect #{device.attributes.inspect}"
end

Parameters:

  • obj (String) (defaults to: nil) —

    Object to pass to the callback function. This is optional.

  • Block (Proc) —

    When the callback is executed, the device and object are yielded to this block.

Returns:

  • (Boolean) —

    returns true or raises an error



441
442
443
444
445
446
447
448
 
# File 'lib/phidgets-ffi/common.rb', line 441

def on_server_disconnect(obj=nil, &block)
  @on_server_disconnect_obj = obj
  @on_server_disconnect = Proc.new { |handle, obj_ptr|
    yield self, object_for(obj_ptr)
  }
  Phidgets::FFI::Common.set_OnServerDisconnect_Handler(@handle, @on_server_disconnect, pointer_for(obj))
	  true
end

#on_sleep(obj = nil, &block) ⇒ Boolean

Note:

Used only in Mac OS X

Sets a sleep handler callback function. This is called when the MacOS X is entering sleep mode.

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.

Examples:

ifkit.on_sleep do |obj|
  puts "System sleeping"
end

Parameters:

  • obj (String) (defaults to: nil) —

    Object to pass to the callback function. This is optional.

  • Block (Proc) —

    When the callback is executed, the device and object are yielded to this block.

Returns:

  • (Boolean) —

    returns true or raises an error



461
462
463
464
465
466
467
468
469
 
# File 'lib/phidgets-ffi/common.rb', line 461

def on_sleep(obj=nil, &block)
  @on_sleep_obj = obj
  @on_sleep = Proc.new { |obj_ptr|
    yield object_for(obj_ptr)
  }
  Phidgets::FFI::Common.set_OnWillSleep_Handler(@on_sleep, pointer_for(obj))
	  true
	  
end

#on_wake(obj = nil, &block) ⇒ Boolean

Note:

Used only in Mac OS X

Sets a wake callback function. This is called when the MacOS X is waking up from sleep mode.

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.

Examples:

ifkit.on_wake do |obj|
  puts "System waking up"
end

Parameters:

  • obj (String) (defaults to: nil) —

    Object to pass to the callback function. This is optional.

  • Block (Proc) —

    When the callback is executed, the device and object are yielded to this block.

Returns:

  • (Boolean) —

    returns true or raises an error



482
483
484
485
486
487
488
489
 
# File 'lib/phidgets-ffi/common.rb', line 482

def on_wake(obj=nil, &block)
     @on_wake_obj = obj
     @on_wake = Proc.new { |obj_ptr|
       yield object_for(obj_ptr)
     }
     Phidgets::FFI::Common.set_OnWakeup_Handler(@on_wake, pointer_for(obj))
     true
end

#serial_number ⇒ Integer

Returns the serial number of the Phidget

Returns:

  • (Integer) —

    returns the serial number of the Phidget, or raises an error



310
 
# File 'lib/phidgets-ffi/common.rb', line 310

def serial_number; Common.serial_number(@handle); end

#server_address ⇒ String, Integer

Returns the Phidget WebService server address and port for a Phidget opened over the network, or raises an error

Returns:

  • (String, Integer) —

    returns the Phidget WebService server address and port for a Phidget opened over the network, or raises an error



342
 
# File 'lib/phidgets-ffi/common.rb', line 342

def server_address; Common.server_address(@handle); end

#server_id ⇒ String

Returns the server id for a Phidget opened over the network, or raises an error

Returns:

  • (String) —

    returns the server id for a Phidget opened over the network, or raises an error



339
 
# File 'lib/phidgets-ffi/common.rb', line 339

def server_id; Common.server_id(@handle); end

#type ⇒ String

Returns the device type of the Phidget

Returns:

  • (String) —

    returns the device type of the Phidget, or raises an error



320
 
# File 'lib/phidgets-ffi/common.rb', line 320

def type; Common.type(@handle); end

#version ⇒ Integer

Returns the device version of the Phidget

Returns:

  • (Integer) —

    returns the device version of the Phidget, or raises an error



315
 
# File 'lib/phidgets-ffi/common.rb', line 315

def version; Common.version(@handle); end

#wait_for_attachment(wait_time = 1000) ⇒ Boolean

This method can be called after the Phidget object has been created. This method blocks indefinitely until the Phidget becomes available. This can be quite some time (forever), if the Phidget is never plugged in. Please note that this call is not needed if you are programming inside a block. If you are programming inside a block, you can specify the wait time in the #initialize constructor

Parameters:

  • wait_time (Integer) (defaults to: 1000) —

    Time to wait for the attachment. Specify 0 to wait forever. This is Optional. The default wait time is 1000 milliseconds.

Returns:

  • (Boolean) —

    returns true or raises an error



277
278
279
280
281
282
283
284
285
286
 
# File 'lib/phidgets-ffi/common.rb', line 277

def wait_for_attachment(wait_time=1000)
	
  Phidgets::FFI::Common.waitForAttachment(@handle, wait_time)
	  if attached?
		load_device_attributes
	  end
	  
  true

end