frog.plugin
Class Device

java.lang.Object
  frog.plugin.Device

public final class Device
extends Object

A Device object represents everything a Plugin should need to perform operations between a host and device. Devices are set up such that the FROG platform does not have to keep track of which Plugin a Device belongs to, but rather, can just call methods on Devices which pass the command on to their respective Plugin.

Author:

Team Better Recognize

Field Summary

String	id unique identifier for this device
String	type what kind of device this is (SPOT, ANDROID, ...)

Constructor Summary

Device(String id, String type, Plugin plugin)
A new Device with no short name

Device(String id, String type, String shortName, Plugin plugin)
A new Device with a GUI-friendly short name

Method Summary

void	addDeviceListener(DeviceListener dl) Adds a new listener for this device.
void	addFilter(int id, String arg) Instruct the device to add a new filter to its filtering pipeline.
void	calibrate() Calibrates the accelerometers of the device.
void	connect(DeviceListener dl) Formally connect to a specified device.
void	disconnect() Disconnect a formally connected device.
boolean	equals(Object other) A Device is considered equal to another Device if and only if: Other object is an instance of Device Other Device has equal id Other Device has equal type
String[]	getActiveFilters() Returns a list of filters currently active on the device.
String[]	getAvailFilters() Returns a list of available filters that this device supports.
int	getSampleRate() Returns the current sample rate of this device in hertz.
String	getShortName() Return the GUI-friendly name of this device.
boolean	isConnected() Determines if this Device is currently connected or just discoverable.
void	notifyAcceleration(Accel3D acc) Give the Device the most recent acceleration performed so it can notify anything listening on it.
void	notifyDisconnect() Used to notify the DeviceListeners that the device has unexpectedly disconnected from the host.
void	notifyGestureEnd(boolean good) Notifies listeners that a gesture has ended.
void	removeDeviceListener(DeviceListener dl) Removes a DeviceListener from this Device.
void	removeFilter(int index) Removes a Filter from the list of active filters on this Device.
void	resetFilters() Sends a message to the Device removing any filters currently in use.
void	setSamplingRate(int rate) Sets the sampling rate, in hertz, of this Device.
void	setShortName(String name) Declare a new short name for this device.
String	toString() Converts this object to a String.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

id

public final String id

unique identifier for this device

type

public final String type

what kind of device this is (SPOT, ANDROID, ...)

Constructor Detail

Device

public Device(String id,
              String type,
              Plugin plugin)

A new Device with no short name

Parameters:

id - a unique identifier for this Device

type - the type of Device (SPOT, ANDROID, ...)

plugin - creator of this Device object

Device

public Device(String id,
              String type,
              String shortName,
              Plugin plugin)

A new Device with a GUI-friendly short name

Parameters:

id - a unique identifier for this Device

type - the type of Device (SPOT, ANDROID, ...)

shortName - a short name for this Device. Preferably less than 8 characters.

plugin - creator of this Device object

Method Detail

addFilter

public void addFilter(int id,
                      String arg)
               throws IOException

Instruct the device to add a new filter to its filtering pipeline. If the device supports on-board filtering, this method should communicate both what type of filter to use as well as an argument string for that filter. The id should come from the getAvailFilters method (it is the index of the array of the desired filter).

Parameters:

id - the filter desired. This should be the index from the array of filters.

arg - the argument String for this filter

Throws:

IOException - if any communication error occurs

See Also:

Plugin.addFilter(Device, int, String)

addDeviceListener

public void addDeviceListener(DeviceListener dl)

Adds a new listener for this device. When Gestures are performed they should be notified and given the gestures from that event.

Parameters:

dl - the DeviceListener you wish to add.

See Also:

DeviceListener

calibrate

public void calibrate()
               throws IOException

Calibrates the accelerometers of the device. If the device requires calibration or any adjustment before use, this method can be called to provide a custom GUI instructing the user on how to set up their device (such as setting it flat on a table or throwing it out a window).

Throws:

IOException - if any communication error occurs

See Also:

Plugin.calibrate(Device)

connect

public void connect(DeviceListener dl)
             throws IOException

Formally connect to a specified device. After the user has been presented with a list of discovered devices, the one they pick must be connected to so that a formal connection (and probably a new Thread) can be established and they can begin using the device.

Parameters:

dl - a DeviceListener to listen to this connection. Could be null but not recommended.

Throws:

IOException - if any communication error occurs. It should be assumed that if this exception is thrown, the device is NOT connected.

See Also:

Plugin.connect(Device)

disconnect

public void disconnect()
                throws IOException

Disconnect a formally connected device. This method should tear down any facilities that were set up to support the device. This can be called by the user when they no longer wish to use the device, but you may also wish to use this method as a clean-up method in the event of an IOException so that the device could be connected to again. A successful disconnect causes all listeners to be removed.

Throws:

IOException - if the device cannot be sent a disconnect signal. Regardless, a best attempt must be made to tear down any local resources tied to this device.

See Also:

Plugin.disconnect(Device)

equals

public boolean equals(Object other)

A Device is considered equal to another Device if and only if:

1. Other object is an instance of Device
2. Other Device has equal id
3. Other Device has equal type

Overrides:

equals in class Object

getActiveFilters

public String[] getActiveFilters()
                          throws IOException

Returns a list of filters currently active on the device. If the Device does not support on-device filtering, a null or empty array may be returned.

Returns:

the list of currently active filters on the device in the order in which they were instantiated

Throws:

IOException

See Also:

Plugin.getActiveFilters(Device)

getAvailFilters

public String[] getAvailFilters()

Returns a list of available filters that this device supports. The array of strings returned by this method should be in a specific order as the index of the array will be used to communicate with the device later.

Returns:

a list of Strings containing the names of the filters supported

See Also:

Plugin.getAvailFilters()

getSampleRate

public int getSampleRate()
                  throws IOException

Returns the current sample rate of this device in hertz.

Returns:

the current sample rate in hertz

Throws:

IOException

See Also:

Plugin.getSampleRate(Device)

getShortName

public String getShortName()

Return the GUI-friendly name of this device. Usually this name is a shortened version of the id.

Returns:

the short name of this device

isConnected

public boolean isConnected()

Determines if this Device is currently connected or just discoverable. This is set by the connect(DeviceListener) method.

Returns:

true for connected. false if not.

notifyAcceleration

public void notifyAcceleration(Accel3D acc)

Give the Device the most recent acceleration performed so it can notify anything listening on it.

Parameters:

acc - a single XYZ sample from the device's accelerometers

See Also:

DeviceListener, AccelEvent

notifyDisconnect

public void notifyDisconnect()

Used to notify the DeviceListeners that the device has unexpectedly disconnected from the host. It should not be called when the disconnect was planned (i.e. called by the disconnect() method).

notifyGestureEnd

public void notifyGestureEnd(boolean good)

Notifies listeners that a gesture has ended.

Parameters:

good - true for a complete gesture, false if something went wrong

See Also:

DeviceListener.gestureComplete(boolean, Device)

removeDeviceListener

public void removeDeviceListener(DeviceListener dl)

Removes a DeviceListener from this Device. The listener will no longer be notified of AccelEvents.

Parameters:

dl - the DeviceListener to remove

See Also:

DeviceListener

removeFilter

public void removeFilter(int index)
                  throws IOException

Removes a Filter from the list of active filters on this Device.

Parameters:

index - the index on the array of active filters to remove

Throws:

IOException

resetFilters

public void resetFilters()
                  throws IOException

Sends a message to the Device removing any filters currently in use. This method makes it possible for the user to edit or remove filters the Device is performing. This method does nothing if on-board filtering cannot be done by this type of Device.

Throws:

IOException - if any communication error occurs

See Also:

addFilter(int, String), Plugin.resetFilters(Device)

setSamplingRate

public void setSamplingRate(int rate)
                     throws IOException

Sets the sampling rate, in hertz, of this Device. If the Device is not compatible with changing the sampling frequency, this method should return immediately.

Parameters:

rate - the rate to sample, in hertz

Throws:

IOException

See Also:

Plugin.setSampleRate(Device, int)

setShortName

public void setShortName(String name)

Declare a new short name for this device. It is recommended that the name be kept under 8 characters in length and be closely related to the id of this device.

Parameters:

name - the new short name for this device

toString

public String toString()

Converts this object to a String.

Overrides:

toString in class Object

Returns:

type followed by the id

See Also:

Object.toString()