dlife.robot
Class Device

java.lang.Object
  java.util.Observable
      dlife.robot.Device

Direct Known Subclasses:

AiboHeadEffector, AiboWalkEffector, ARDroneLEDs, ARDroneYoke, ArraySensor, Camera, DeltaPositionEffector, DifferentialDriveEffector, FilterManager, FinchBuzzer, FinchLED, GripperEffector, HemissonTextToSpeech, OnOffSetEffector, PanTiltZoomEffector, PseudoDevice, ScribblerSpeaker

public abstract class Device
extends Observable

Represents a robotic device (a sensor or an effector). Concrete implementations of Device are created for each type of sensor or effector for each robot.

Each Device implementation will:

• Read the device state from the robot (by implementing updateFromRobot) and make that information available to the user via accessors.
• Provide methods for manipulating the device (if appropriate).
• Provide a GUI with displays for the device's state and, if appropriate, controls for manipulating it. (by implementing the createGUIComponents method.)
• Implement the freeze method. If the device has motion associated with it this method should stop the motion. If there is no motion this method can be empty.

This abstract base class provides the following functionality:

• An AutoReadTimer that, when started, periodically:
  1. Invokes the readStateFromRobot method (approximately every readDelay ms).
  2. Notifies observers of the device (i.e. its GUI) (approximately every guiUpdateDelay ms) if the following are true:
     • Changes have been made to the device state (i.e. setChanged has been invoked).
     • At least guiUpdateDelay ms have elapsed since the last notification
• Basic startUp, and shutDown methods that start and stop the auto read timer and record timing statistics. Implementations that wish to customize these behaviors can override these methods but should be sure to invoke the superclass implementation.

Version:

Nov 8, 2010

Author:

Grant Braught, Dickinson College

Field Summary

static int	DEFAULT_GUI_UPDATE_DELAY The default GUI update delay.
static int	DEFAULT_READ_DELAY The default delay.
protected Robot	myRobot
protected int	readCount The number of times this device has updated its state from the physical device.

Constructor Summary

Device(boolean autoRead)
Construct a new Device.

Device(int readDelay, int guiUpdateDelay, boolean autoRead)
Construct a new Device.

Method Summary

protected abstract DeviceDisplay[]	createGUIObjects() Create the objects that make up the GUI for this Device.
abstract void	freeze() Immediately stop the device.
boolean	getAutoRead() Get the current auto read setting.
DeviceDisplay[]	getGUI() Get the GUI for this Device.
int	getGUIUpdateDelay() Get the current GUI update delay.
int	getReadDelay() Get the current read delay for the AutoReadTimer.
Robot	getRobot() Return the robot to which this device is attached.
int	getSensorReadCount() Get the current sensor read count.
double	getSensorReadRate() Get the current sensor read rate.
abstract void	readStateFromRobot() Read the state of this Device from the robot.
void	setAutoRead(boolean autoRead) Set the auto read setting.
void	setGUIUpdateDelay(int delay) Set the GUI update delay (in ms).
void	setReadDelay(int delay) Set the read delay (in ms).
void	setRobot(Robot r) Set the robot to which this device is attached.
void	shutDown() Perform any shutdown operations on the device.
void	startAutoReadTimer() Start a timer to perform auto reads.
void	startUp() Perform any startup operations for the device.
void	stopAutoReadTimer() Stop the timer that is performing the auto reads.

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_READ_DELAY

public static final int DEFAULT_READ_DELAY

The default delay. The read delay is the delay (in ms) between invocations of the readStateFromRobot method by the AutoReadThread. The actual time between reads will be longer than this. How much longer depends upon the speed of the machine, the speed of the communication channel and the number of devices that are active.

See Also:

Constant Field Values

DEFAULT_GUI_UPDATE_DELAY

public static final int DEFAULT_GUI_UPDATE_DELAY

The default GUI update delay. The GUI update delay is the minimum time (in ms) that will elapse between consecutive notifications of the GUI. The GUI will update its display of the device's state each time it is notified. The actual time between notifications will depend upon the speed of the machine, the speed of the communication channel, the number of devices that are active and rate at which the state of this device changes.

See Also:

Constant Field Values

readCount

protected int readCount

The number of times this device has updated its state from the physical device. This is typically updated by the updateState method in this class. However, sub-classes may wish to count differently (e.g. Camera).

myRobot

protected Robot myRobot

Constructor Detail

Device

public Device(boolean autoRead)

Construct a new Device. Default value are assigned for the read delay and the GUI update delay. The AutoRead setting is obtained by invoking the useAutoRead method.

Device

public Device(int readDelay,
              int guiUpdateDelay,
              boolean autoRead)

Construct a new Device. Use the provided value for the read delay ad the GUI update delay.

Parameters:

readDelay - the delay (in ms) between attempts to read the device's state from the robot. The actual time between reads will be longer than this. How much longer depends upon the speed of the machine, the speed of the communication channel and the number of devices that are active.

guiUpdateDelay - the minimum time (in ms) that will elapse between consecutive notifications of the GUI. The GUI will update its display of the device's state each time it is notified. The actual time between notifications will depend upon the speed of the machine, the speed of the communication channel, the number of devices that are active and rate at which the state of this device changes.

autoRead - indicates the initial value of the autoRead state for this Device. If true, then the AutoReadThread will be started when the device is added to a robot. If false, it will not.

Throws:

IllegalArgumentException - if readDelay or guiUpdateDelay are < 0.

Method Detail

getReadDelay

public int getReadDelay()

Get the current read delay for the AutoReadTimer. The read delay is the delay (in ms) between invocations of readStateFromRobot by the AutoReadTimer. The actual time between reads will be longer than this. How much longer depends upon the speed of the machine, the speed of the communication channel and the number of devices that are active.

Returns:

the read delay.

getGUIUpdateDelay

public int getGUIUpdateDelay()

Get the current GUI update delay. The GUI update delay is the minimum time (in ms) that will elapse between consecutive notifications of the GUI. The GUI will update its display of the device's state each time it is notified. The actual time between notifications will depend upon the speed of the machine, the speed of the communication channel, the number of devices that are active and rate at which the state of this device changes.

Returns:

the GUI update delay.

setReadDelay

public void setReadDelay(int delay)

Set the read delay (in ms). The read delay is the delay (in ms) between invocations of readStateFromRobot by the AutoReadTimer. The actual time between reads will be longer than this. How much longer depends upon the speed of the machine, the speed of the communication channel and the number of devices that are active.

Parameters:

delay - the new read delay.

Throws:

IllegalArgumentException - if delay < 0.

setGUIUpdateDelay

public void setGUIUpdateDelay(int delay)

Set the GUI update delay (in ms). The GUI update delay is the minimum time (in ms) that will elapse between consecutive notifications of the GUI. The GUI will update its display of the device's state each time it is notified. The actual time between notifications will depend upon the speed of the machine, the speed of the communication channel, the number of devices that are active and rate at which the state of this device changes.

Parameters:

delay - the new GUI update delay.

Throws:

IllegalArgumentException - if delay < 0.

setRobot

public void setRobot(Robot r)

Set the robot to which this device is attached.

Parameters:

r - the robot.

getRobot

public Robot getRobot()

Return the robot to which this device is attached.

Returns:

the robot.

getGUI

public DeviceDisplay[] getGUI()

Get the GUI for this Device. This method ensures that the GUI is only constructed once. The first time the method is called a reference to the GUI is cached. That reference is returned on any subsequent calls.

Returns:

the GUI for this device.

setAutoRead

public void setAutoRead(boolean autoRead)

Set the auto read setting. If this device is assigned to a live robot (i.e. one that has been started up) when this method is invoked it will start or stop the auto reads as appropriate. If this device has not yet been assigned to a robot when this method is invoked then it simply changes the autoRead state and the Robot will handle starting and stopping the auto reads as appropriate.

Parameters:

autoRead - true to turn on auto read, false to turn it off.

getAutoRead

public boolean getAutoRead()

Get the current auto read setting. If auto read is true then the readStateFromRobot method will be invoked periodically any time the robot has been started up. If auto read is false then the readStateFromRobot method will have to be invoked manually in order to update the device state.

Returns:

the auto read in ControlCenter setting.

startAutoReadTimer

public void startAutoReadTimer()

Start a timer to perform auto reads. If this device has been assigned to a robot and that robot is alive then a timer is created that will invoke the abstract readStateFromRobot method approximately every readDelay ms. In addition, the GUI will be notified of changes every guiUpdateDelay ms. If this device has not been assigned to a robot or the robot is not alive then this method has no effect. This method also sets the autoRead state to true.

stopAutoReadTimer

public void stopAutoReadTimer()

Stop the timer that is performing the auto reads. If there is no timer running then this method has no effect. This method also sets the autoRead state to false.

startUp

public void startUp()

Perform any startup operations for the device. For example, storing a gripper, centering a PTZ or zeroing a dead reckoning device. The implementation provided by this class sets up some timing information necessary for computing sensor read rate statistics and starts the auto read timer if getAutoRead returns true. Subclasses that have their own start up requirements should override this method but should invoke super.startUp() to ensure that the statistics are computed correctly.

The Robot base class invokes this method once in addSensor or addEffector just before the Device is added to the Robot. The Robot will be alive when this method is invoked so it may send commands to the robot. If there are critical problems completing the startUp then this method should throw a RobotCommunicationException.

shutDown

public void shutDown()

Perform any shutdown operations on the device. For example, storing a gripper or centering a PTZ. The implementation provided by this class handles timing information necessary for computing sensor read rate statistics. This method also stops the auto read timer if it was running. Subclasses that have their own shut down requirements should override this method but should invoke super.shutDown() to ensure that the statistics are computed correctly.

The Robot base class invokes this method once in removeSensor or removeEffector just after the Device is removed from the Robot. The robot will still be alive when this method is invoked so it may send commands to the robot. If there are critical problems completing the shutDown then this method should throw a RobotCommunicationException.

getSensorReadCount

public int getSensorReadCount()

Get the current sensor read count. Note: this count is only accurate if the device has been being read using the AutoReadTimer. If additional reads are performed by directly invoking readStateFromRobot they are not counted.

Returns:

the number of times that updateState has been called by the AutoReadTimer.

getSensorReadRate

public double getSensorReadRate()

Get the current sensor read rate. Note: this rate is only accurate if the device has been being read using the AutoReadTimer. If additional reads are performed by directly invoking readStateFromRobot they are not counted in this computation. This is computed as the time that the device has been running divided number of calls that have been made to updateState. The time that the device has been running begins when startUp is invoked (e.g. when the device is added to a robot) and ends either at the time this method was called or at the time when shutDown was called (e.g. when the robot to which this device was added is shutdown.).

Returns:

the sensor read rate in reads/second.

freeze

public abstract void freeze()

Immediately stop the device. This method should send commands to the robot to stop any motion associated with the device. For example, motion devices should stop the robot, the gripper device should stop any gripper motion, etc... For many devices this method will do nothing. However, a default empty implementation is not provided to force that decision to be made when a new device implementation is created.

createGUIObjects

protected abstract DeviceDisplay[] createGUIObjects()

Create the objects that make up the GUI for this Device. In most situations this method will simply create an array of new DeviceDisplay subclasses that make up the GUI. It will not typically contain any actual GUI creation code, that will be contained in the DeviceDisplay subclass. Because this method does not typically create the GUI components it is not invoked on the AWT event thread.

Returns:

an array of DeviceDisplay subclass objects that make up the GUI for this Device.

readStateFromRobot

public abstract void readStateFromRobot()

Read the state of this Device from the robot. This method should use the Robot's sendMessage method to read the state of the Device. It should update any fields that are used to cache the state. If the state is changed it should invoke the setChanged method so that the GUI is notified of the state change by the AutoReadTimer.

Throws:

RobotCommuniationException - if unable to update the state of the device from the robot.