com.phidgets
Class Phidget

java.lang.Object
  extended by com.phidgets.Phidget
Direct Known Subclasses:
AccelerometerPhidget, AdvancedServoPhidget, EncoderPhidget, InterfaceKitPhidget, LEDPhidget, MotorControlPhidget, PHSensorPhidget, RFIDPhidget, ServoPhidget, TemperatureSensorPhidget, TextLCDPhidget, TextLEDPhidget, WeightSensorPhidget

public class Phidget
extends java.lang.Object

This is the base class from which all Phidget device classes derive. Don't create phidget devices directly using this class. Use the specific class for the device that you wish to access.


Constructor Summary
Phidget(long handle)
          Class constructor specifying a handle.
 
Method Summary
 void addAttachListener(AttachListener l)
          Adds an attach listener.
 void addDetachListener(DetachListener l)
          Adds a detach listener.
 void addErrorListener(ErrorListener l)
          Adds an error listener.
 void close()
          Closes this Phidget.
 boolean equals(java.lang.Object comp)
          Compares two Phidgets.
 java.lang.String getDeviceName()
          Return the name of this Phidget.
 java.lang.String getDeviceType()
          Return the device type of this Phidget.
 long getDeviceVersion()
          Returns the device version of this Phidget.
static java.lang.String getLibraryVersion()
          Returns the library version.
 long getSerialNumber()
          Returns the unique serial number of this Phidget.
 java.lang.String getTag()
          Returns the tag associated with this Phidget.
 boolean isAttached()
          Returns the attached status of this Phidget.
 void open(int serial)
          Open this Phidget with a specific serial number.
 void openAny()
          Open a this Phidget without a serial number.
 void removeAttachListener(AttachListener l)
          Removes an attach listener.
 void removeDetachListener(DetachListener l)
          Removes a detach listener.
 void removeErrorListener(ErrorListener l)
          Removes an error listener.
 void setTag(java.lang.String tag)
          Sets the Tag associated with this Phidget.
 java.lang.String toString()
          Return a Sring describing this Phidget.
 void waitForAttachment()
          Waits for this Phidget to become available.
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Phidget

public Phidget(long handle)
Class constructor specifying a handle. This constructor is to be used only by subclasses, as the Phidget calss should never need to be instatiated directly by the user.

Parameters:
handle - A native Handle points to the underlying phidget structure in the base phidget21 C library.
Method Detail

getLibraryVersion

public static final java.lang.String getLibraryVersion()
Returns the library version. This is the library version of the underlying phidget21 C library and not the version of the JNI wrapper implementation.

The version is retured at a string which contains the version number and build date.

Returns:
Library Version

getSerialNumber

public final long getSerialNumber()
                           throws PhidgetException
Returns the unique serial number of this Phidget. This number is set during manufacturing, and is unique across all Phidgets. This number can be used in calls to open to specify this specific Phidget to be opened.

Returns:
Serial Number
Throws:
PhidgetException - If this Phidget is not opened and attached. See open for information on determining if a device is attached.

getDeviceVersion

public final long getDeviceVersion()
                            throws PhidgetException
Returns the device version of this Phidget. This number is simply a way of distinguishing between different revisions of a specific type of Phidget, and is only really of use if you need to troubleshoot device problems with Phidgets Inc.

Returns:
Version
Throws:
PhidgetException - If this Phidget is not opened and attached. See open for information on determining if a device is attached.

getDeviceType

public final java.lang.String getDeviceType()
                                     throws PhidgetException
Return the device type of this Phidget. This is a string that describes the device as a class of devices. For example, all PhidgetInterfaceKit Phidgets will returns the String "PhidgetInterfaceKit".

This function is mostly usefull if you are using the Phidget Manager because it's attach and detach handlers return {link com.phidgets.phidget phidget} objects, and you can use this method to determine their proper type.

Returns:
Device Type
Throws:
PhidgetException - If this Phidget is not opened and attached. See open for information on determining if a device is attached.

getDeviceName

public final java.lang.String getDeviceName()
                                     throws PhidgetException
Return the name of this Phidget. This is a string that describes the device. For example, a PhidgetInterfaceKit could be described as “Phidget InterfaceKit 8/8/8”, or “Phidget InterfaceKit 0/0/4”, among others, depending on the specific device.

This lets you determine the specific type of a Phidget, within the broader classes of Phidgets, such as PhidgetInterfaceKit, or PhidgetServo

Returns:
Name
Throws:
PhidgetException - If this Phidget is not opened and attached. See open for information on determining if a device is attached.

isAttached

public final boolean isAttached()
                         throws PhidgetException
Returns the attached status of this Phidget. This method returns True or False, depending on whether the Phidget is phisically plugged into the, initialized, and ready to use - or not. If a Phidget is not attached, many functions calls will fail with a PhidgetException, so either checking this function, or using the Attach and Detach events, is recommended, if a device is likely to be attached or detached during use.

Returns:
Status
Throws:
PhidgetException - If this Phidget is not opened.

getTag

public final java.lang.String getTag()
                              throws PhidgetException
Returns the tag associated with this Phidget. This Tag is a String - up to ten digits - that is stored in the Flash memory of newer Phidgets. This tag can be set programatically (see setTag), and is non-volatile - so it is remembered even if the Phidget is unplugged.

Returns:
Tag
Throws:
PhidgetException - If this Phidget is not opened and attached, or if this Phidget does not support tags. See open for determining if a device is attached.

setTag

public final void setTag(java.lang.String tag)
                  throws PhidgetException
Sets the Tag associated with this Phidget. Tags are user defined Strings that persist in a Phidget's Flash. They are only supported in the newer Phidgets. The maximum length is 10 characters.

Tags can not currently be set from Windows because of driver incompatibility. Tags can be set from MacOS, Linux and Windows CE.

Parameters:
tag - Tag
Throws:
PhidgetException - If this Phidget is not opened and attached, or if this Phidget does not support tags, or if this is called from Windows. See open for determining if a device is attached.

open

public final void open(int serial)
                throws PhidgetException
Open this Phidget with a specific serial number.

Open is pervasive. What this means is that you can call open on a device before it is plugged in, and keep the device opened across device dis- and re-connections.

Open is Asynchronous. What this means is that open will return immediately – before the device being opened is actually available, so you need to use either the attach event or the waitForAttachment method to determine if a device is available before using it.

This version of open specifies a serial number - The serial number is a unique number assinged to each Phidget during production and can be used to uniquely identify specific phidgets. use openAny to open a device without specifying the serial number.

Parameters:
serial - Serial Number
Throws:
PhidgetException

openAny

public final void openAny()
                   throws PhidgetException
Open a this Phidget without a serial number. This method is the same as open, except that it specifies no serial number. Therefore, the first available Phidget will be opened. If there are two Phidgets of the same type attached to the system, you should specify a serial number, as there is no guarantee which Phidget will be selected by the call to openAny().

Throws:
PhidgetException

close

public final void close()
                 throws PhidgetException
Closes this Phidget. This will shut down all threads dealing with this Phidget and you won't recieve any more events.

Throws:
PhidgetException - If this Phidget is not opened.

waitForAttachment

public void waitForAttachment()
                       throws PhidgetException
Waits for this Phidget to become available. This method can be called after open has been called to wait for thid Phidget to become available. This is usefull because open is asynchronous (and thus returns immediately), and most methods will throw a PhidgetException is they are called before a device is actually ready. This method is synonymous with polling the isAttached method until it returns True, or using the Attach event.

This method blocks indefinitely until the Phidget becomes available. This can be quite some time (forever), if the Phidget is never plugged in.

This method uses the attach handler internally to determine when the Phidget becomes available.

Throws:
PhidgetException - If this Phidget is not opened.

addAttachListener

public final void addAttachListener(AttachListener l)
Adds an attach listener. The attach handler is a method that will be called when this Phidget is phisically attached to the system, and has gone through its initalization, and so is ready to be used.

There is no limit on the number of attach handlers that can be registered for a particular Phidget.

Parameters:
l - An implemetation of the AttachListener interface

removeAttachListener

public final void removeAttachListener(AttachListener l)
Removes an attach listener. This will remove a previously added attach listener.


addErrorListener

public final void addErrorListener(ErrorListener l)
Adds an error listener. The error handler is a method that will be called when an asynchronous error occurs. Error events are not currently used, but will be in the future to report any problems that happen out of context from a direct function call.

There is no limit on the number of error handlers that can be registered for a particular Phidget.

Parameters:
l - An implemetation of the ErrorListener interface

removeErrorListener

public final void removeErrorListener(ErrorListener l)
Removes an error listener. This will remove a previously added error listener.


addDetachListener

public final void addDetachListener(DetachListener l)
Adds a detach listener. The detach handler is a method that will be called when this Phidget is phisically detached from the system, and is no longer available. This is particularly usefull for applications when a phisical detach would be expected.

Remember that many of the methods, if called on an unattached device, will throw a PhidgetException. This Exception can be checked to see if it was caused by a device being unattached, but a better method would be to regiter the detach handler, which could notify the main program logic that the device is no longer available, disable GUI controls, etc.

There is no limit on the number of detach handlers that can be registered for a particular Phidget.

Parameters:
l - An implemetation of the DetachListener interface

removeDetachListener

public final void removeDetachListener(DetachListener l)
Removes a detach listener. This will remove a previously added detach listener.


toString

public java.lang.String toString()
Return a Sring describing this Phidget.

Overrides:
toString in class java.lang.Object

equals

public boolean equals(java.lang.Object comp)
Compares two Phidgets. This method compares two Phidgets using serial number, device type and version.

Overrides:
equals in class java.lang.Object