shady.common
Class ShadyCommon

java.lang.Object
  extended by shady.common.ShadyCommon
All Implemented Interfaces:
ShadyCommonAPI
Direct Known Subclasses:
ShadySim

public abstract class ShadyCommon
extends java.lang.Object
implements ShadyCommonAPI

Shady common implementation.

Copyright (C) 2006 Marsette A. Vona, III

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Author:
Marsette (Marty) A. Vona, III, Carrick Detweiler

Field Summary
protected  ShadyAccountingInfo accountingInfo
          Internal representation of the current accounting info.
protected  double[] accumulatedBarrelRotation
          Current accumulated barrel rotations.
protected  double accumulatedShadeRotation
          Current accumulated shade rotation.
protected  boolean accumulating
          Whether we're currently accumulating barrel and shade rotations.
static java.lang.String[] BARREL_NAME
          The barrel names.
protected  AbstractSegment bodySegment
          Cached body segment.
static double CC
          Alias to NOMINAL_CENTER_TO_CENTER_DISTANCE.
protected  vona.time.Clock clock
          Keeps track of time for this Shady.
private static java.lang.String cvsid
          CVS id.
static double DEFAULT_GRIPPER_SLOP
          Slop below which gripper state should snap to ShadyCommonAPI.CLOSED_STATE or ShadyCommonAPI.OPEN_STATE.
static double DEFAULT_SHADE_OPEN_ANGLE
          Default signed CCW angle in degrees at which the shade is open.
static double DEFAULT_SHADE_SLOP
          Slop below which the shade is considered open or closed, in degrees.
static double DEFAULT_UPDATE_TIME
          Default period at which to update(double), seconds.
static int ENERGY
          Index of energy resource.
static java.lang.String[] FAULT_NAME
          Names for the faults.
static java.lang.String[] GRIPPER_OPERATION_NAME
          The gripper operation names.
protected  java.lang.String name
          The user-set name, if any.
static double NOMINAL_BARREL_ROTATE_POWER
          Default power required to open the gripper in Watts.
static double NOMINAL_BARREL_ROTATION_LIMIT
          Default barrel rotation limit in degrees.
static double NOMINAL_BARREL_ROTATION_SPEED
          Default barrel rotation speed in degrees/sec.
static double NOMINAL_CENTER_TO_CENTER_DISTANCE
          Default distance between barrel centers in meters.
static double NOMINAL_GRIPPER_CLOSE_POWER
          Default power required to close the gripper in Watts.
static double NOMINAL_GRIPPER_CLOSE_TIME
          Default gripper close time in seconds.
static double NOMINAL_GRIPPER_OPEN_POWER
          Default power required to open the gripper in Watts.
static double NOMINAL_GRIPPER_OPEN_TIME
          Default gripper open time in seconds.
static double NOMINAL_GRIPPER_WIDTH
          Default gripper width in meters.
static double NOMINAL_MIN_ENERGY
          Power level below which a ShadyCommonAPI.LOW_BATTERY fault is triggered (Joules).
static double NOMINAL_QUIESCENT_POWER
          Default total system power consumption, in Watts, when no motion is occuring.
static double NOMINAL_SHADE_ROTATION_SPEED
          Default shade rotation speed in degrees/sec.
static double NOMINAL_TOTAL_BATTERY_ENERGY
          Default fully charged batter energy in Joules.
static double NOMINAL_TOTAL_LENGTH
          Default tip-to-tip mechanism length in meters.
protected  ShadyPose pose
          The current pose of the mechanism, may be null.
protected  ShadyState state
          Internal representation of the current state.
static int TIME
          Index of time resource.
protected  java.lang.Thread updateThread
          An async thread to update(double).
protected  boolean wouldDuelOverride
          Whether to override generation of ShadyCommonAPI.WOULD_DUEL faults.
protected  boolean wouldTiltOverride
          Whether to override generation of ShadyCommonAPI.WOULD_TILT faults.
 
Fields inherited from interface shady.common.ShadyCommonAPI
CLOSED_STATE, COLLISION, ESTOP, GRIPPER_CLOSE, GRIPPER_OPEN, GRIPPER_OPERATION_TARGET_STATE, IMPLEMENTATION_FAULT, LEFT, LOW_BATTERY, MOTION_LIMIT, OPEN_STATE, OVER_CURRENT, OVER_TEMP, RIGHT, TILT, TIMEOUT, UNALIGNED, UNKNOWN, WOULD_COLLIDE, WOULD_DUEL, WOULD_MOTION_LIMIT, WOULD_TILT
 
Constructor Summary
ShadyCommon()
          Covers ShadyCommon(ShadyPose), no initial pose.
ShadyCommon(ShadyPose pose)
          Create a new ShadyCommon.
 
Method Summary
protected  java.lang.StringBuffer appendBarrelString(java.lang.StringBuffer buf, DoubleFormatter formatter, int barrel, boolean html, java.awt.Color[] barrelColor)
          Append a human-readable string representation of barrel.
protected  java.lang.StringBuffer appendHTMLFontTag(java.lang.StringBuffer buf, java.awt.Color color)
          Append a colored HTML font tag.
static java.lang.String barrelName(int barrel)
          Get the name of a barrel.
 void beginAccumulatingMotion()
          Begin accumulating barrel and shade rotations.
static void checkBarrel(int barrel)
          Check a barrel id.
protected  boolean checkEnergy(double energyRequired, java.lang.String msg)
          Check whether at least NOMINAL_MIN_ENERGY plus energyRequired remains.
protected  void checkFault()
          Check the mechansim for any ongoing fault condition.
static void checkGripperOperation(int operation)
          Check a gripper operation.
 int closeGripper(int barrel)
          Same as ShadyCommonAPI.closeGripper(int, Point.OnSegment) but for use only when the caller cannot provide gripPoint.
 int closeGripper(int barrel, Point.OnSegment gripPoint)
          Close the gripper in barrel.
protected  void closeGripperPost(int barrel, Point.OnSegment gripPoint)
          Last part of closeGripper(int, Point.OnSegment).
protected  Point.OnSegment closeGripperPre(int barrel, Point.OnSegment gripPoint)
          First part of closeGripper(int, Point.OnSegment).
 int closeShade()
          Close the shade to 0 in opposite direction of ShadyCommonAPI.getShadeOpenAngle().
protected  boolean disableTiltCheck()
          Whether to disable tilt checking on gripper open.
protected abstract  double doSimultaneousMotion(double leftBarrelDT, double rightBarrelDT, double shadeDT)
          Implementation of simultaneousMotion(double, double, double).
 int endAccumulatingMotion()
          End accumulating barrel and shade rotations.
 java.lang.String faultName(int fault)
          Get the name of a fault.
 ShadyAccountingInfo getAccountingInfo()
          Get the accounting info accumulated since reboot or since the last ShadyCommonAPI.resetAccounting().
 ShadyAccountingInfo getAccountingInfo(ShadyAccountingInfo dest)
          Same as ShadyCommonAPI.getAccountingInfo() but returns in dest.
 double getBarrelAngle(int barrel)
          Get the current angle of the specified barrel, in degrees.
 double getBarrelRotationLimit()
          Get the barrel rotation limit, in degrees.
 double getCenterToCenterDistance()
          Get the center-to-center distance between barrel rotation axes, in meters.
 vona.time.Clock getClock()
          Get the clock this Shady is using.
 double getCurrentPower()
          Get the current power used by the mechanism in Watts.
protected  double getCurrentTime()
          Covers clock.getCurrentTime() iff clock is set, else uses the system clock.
 int getFault()
          Get the current fault, if any.
 int getFault(java.lang.String[] faultDetails)
          Get the current fault, if any.
 java.lang.String getFaultDetails()
          Get a human-readable detail string about the current Fault, if any.
static double getGripperOperationTargetState(int operation)
          Get the target state of a gripper operation.
protected  double getGripperSlop()
          Return slop below which gripper state should snap to ShadyCommonAPI.CLOSED_STATE or ShadyCommonAPI.OPEN_STATE.
 double getGripperState(int barrel)
          Get a gripper state.
 double getGripperWidth()
          Get the width of the gripper paddles, in meters.
 double getGripQuality(int barrel)
          Check the gripping quality of a closed gripper.
 java.lang.String getName()
          Get the name of this Shady.
 int getNumActiveActuators()
          Get the number of actuaturs currently active.
 ShadyPose getPose()
          Get a copy of the current pose.
 ShadyPose getPose(ShadyPose dest)
          Get a copy of the current pose.
 double getShadeAngle()
          Get the shade angle in CCW degrees.
 double getShadeOpenAngle()
          Get the signed CCW angle in degrees at which the shade is considered open.
protected  double getShadeSlop()
          Return slop below which shade state should snap to closed (0 deg) or open (getShadeOpenAngle()).
 ShadyState getState()
          Get the current state of the mechanism.
 ShadyState getState(ShadyState dest)
          Same as ShadyCommonAPI.getState() but returns in dest.
 double getTotalLength()
          Get the tip-to-tip mechansim length, in meters.
protected  double getUpdateTime()
          Get the update period, in seconds.
static java.lang.String gripperOperationName(int operation)
          Get the name of a gripper operation.
static java.lang.String gripperStateName(double state)
          Convenience cover of gripperStateName(double, DoubleFormatter), uses no formatter.
static java.lang.String gripperStateName(double state, DoubleFormatter formatter)
          Get the name of a gripper state.
 boolean isAccumulatingMotion()
          Check whether barrel and shade rotation accumulation is currently enabled.
 boolean isGripperAligned(int barrel)
          Same as ShadyCommonAPI.isGripperAligned(int, Point.OnSegment) but for use only when the caller cannot provide gripPoint.
 boolean isGripperAligned(int barrel, Point.OnSegment point)
          Check whether the mechanism considers the specified gripper to be "properly aligned" over an environment segment.
 boolean isGripperClosed(int barrel)
          Convenience method to check whether a gripper is logically closed.
 boolean isGripperOpen(int barrel)
          Convenience method to check whether a gripper is logically open.
 boolean isNameSet()
          Check whether the name of this Shady has been explicitly set.
 boolean isShadeClosed()
          Check if the shade is closed.
 boolean isShadeOpen()
          Check if the shade is open.
protected  ShadyAccountingInfo makeAccountingInfo()
          Instantiate accountingInfo.
protected  vona.time.Clock makeClock()
          Instantiate clock.
protected  ShadyState makeState()
          Instantiate state.
protected  java.lang.Thread makeUpdateThread()
          Instantiate updateThread.
 int openGripper(int barrel)
          Open the gripper in barrel.
protected  void openGripperPost(int barrel)
          Last part of openGripper(int).
protected  int openGripperPre(int barrel)
          First part of openGripper(int).
 int openShade()
          Open the shade to ShadyCommonAPI.getShadeOpenAngle().
static int otherBarrel(int barrel)
          Convenience method to get the other barrel.
static int otherGripperOperation(int operation)
          Convenience method to get the other gripper operation.
 boolean pick(Point p, double threshold)
          Check if this Shady is picked by p in world coordinates (meters) within a given threshold in meters.
 boolean pick(Point p, double threshold, Point.OnSegment projectionPoint)
          Determine whether p is within threshold of its projection onto this Shady's body segment.
protected  double reallyGetCurrentBatteryEnergy()
          Get the remaining battery energy in Joules.
protected  double reallyGetTotalBatteryEnergy()
          Get the total battery capacity, when fully charged, in Joules.
protected abstract  double reallyRotateBarrel(int barrel, double dt)
          Really rotates the barrel.
protected abstract  double reallyRotateShade(double dt)
          Really rotates the shade.
protected abstract  double reallySetGripper(int barrel, double targetState)
          Really actuates the gripper.
protected  void reestablishState()
          Examine the mechanism to reestablish the state.
 int reset()
          Attempt to reset the mechanism.
 void resetAccounting()
          Reset all accounting.
 int rotateBarrel(int barrel, double dt)
          Incrementally rotate barrel.
protected  void rotateBarrel(int barrel, double dt, double[] resource)
          Second part of rotateBarrel(int, double).
protected  int rotateBarrelPost(int barrel, double dt, double energy, double time)
          Third part of rotateBarrel(int, double).
protected  double rotateBarrelPre(int barrel, double dt)
          First part of rotateBarrel(int, double).
 int rotateBarrelTo(int barrel, double angle)
          Same as ShadyCommonAPI.rotateBarrel(int, double) but goes to an absolute angle.
 int rotateShade(double dt)
          Incrementally rotate the shade.
 int setFault(int fault, java.lang.String details)
          Try to set a fault.
protected  void setGripper(int barrel, double targetState, double[] resource)
          Second part of setGripper(int, int).
protected  int setGripper(int barrel, int operation)
          This impl checks if motion is necessary and if so asks reallySetGripper(int, double) to do the motion, then takes care of all accounting info updates.
protected  int setGripperPost(int barrel, int operation, double targetState, double energy, double time)
          Third part of setGripper(int, int).
protected  double setGripperPre(int barrel, int operation)
          First part of setGripper(int, int).
 void setName(java.lang.String name)
          Set the name of this Shady.
 boolean setPose(ShadyPose newPose)
          Set the mechanism pose (by copy).
 boolean setState(ShadyState state)
          Set the mechanism state.
 void setWouldDuelOverride(boolean wouldDuelOverride)
          Set whether to override generation of ShadyCommonAPI.WOULD_DUEL faults.
 void setWouldTiltOverride(boolean wouldTiltOverride)
          Set whether to override generation of ShadyCommonAPI.WOULD_TILT faults.
 int simultaneousMotion(double leftBarrelDT, double rightBarrelDT, double shadeDT)
          Execute a simultaneous barrel rotation and shade motion.
 java.lang.String toString()
          Same as toString(DoubleFormatter) but uses no formatter.
 java.lang.String toString(DoubleFormatter formatter)
          Same as toString(DoubleFormatter, boolean) but uses no HTML.
 java.lang.String toString(DoubleFormatter formatter, boolean html)
          Same as toString(DoubleFormatter, boolean, java.awt.Color[], java.awt.Color) but uses no colors.
 java.lang.String toString(DoubleFormatter formatter, boolean html, java.awt.Color[] barrelColor, java.awt.Color faultColor)
          Get a human-readable string representation of this Shady.
protected  void update(double dt)
          By default this is called at the period getUpdateTime() by updateThread.
protected  void updateState(double dt)
          This is used by the default impl of update(double).
protected  boolean wouldDuel(boolean enableFault)
          Check whether the barrels would duel on rotation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface shady.common.ShadyCommonAPI
stop
 

Field Detail

cvsid

private static final java.lang.String cvsid

CVS id.

See Also:
Constant Field Values

NOMINAL_BARREL_ROTATION_LIMIT

public static final double NOMINAL_BARREL_ROTATION_LIMIT

Default barrel rotation limit in degrees.

See Also:
Constant Field Values

NOMINAL_CENTER_TO_CENTER_DISTANCE

public static final double NOMINAL_CENTER_TO_CENTER_DISTANCE

Default distance between barrel centers in meters.

See Also:
Constant Field Values

CC

public static final double CC

Alias to NOMINAL_CENTER_TO_CENTER_DISTANCE.

See Also:
Constant Field Values

NOMINAL_TOTAL_LENGTH

public static final double NOMINAL_TOTAL_LENGTH

Default tip-to-tip mechanism length in meters.

See Also:
Constant Field Values

NOMINAL_GRIPPER_WIDTH

public static final double NOMINAL_GRIPPER_WIDTH

Default gripper width in meters.

See Also:
Constant Field Values

NOMINAL_TOTAL_BATTERY_ENERGY

public static final double NOMINAL_TOTAL_BATTERY_ENERGY

Default fully charged batter energy in Joules.

See Also:
Constant Field Values

NOMINAL_MIN_ENERGY

public static final double NOMINAL_MIN_ENERGY

Power level below which a ShadyCommonAPI.LOW_BATTERY fault is triggered (Joules).

Currently 1% of NOMINAL_TOTAL_BATTERY_ENERGY.

See Also:
Constant Field Values

NOMINAL_GRIPPER_CLOSE_POWER

public static final double NOMINAL_GRIPPER_CLOSE_POWER

Default power required to close the gripper in Watts.

See Also:
Constant Field Values

NOMINAL_GRIPPER_OPEN_POWER

public static final double NOMINAL_GRIPPER_OPEN_POWER

Default power required to open the gripper in Watts.

See Also:
Constant Field Values

NOMINAL_BARREL_ROTATE_POWER

public static final double NOMINAL_BARREL_ROTATE_POWER

Default power required to open the gripper in Watts.

See Also:
Constant Field Values

NOMINAL_QUIESCENT_POWER

public static final double NOMINAL_QUIESCENT_POWER

Default total system power consumption, in Watts, when no motion is occuring.

See Also:
Constant Field Values

NOMINAL_BARREL_ROTATION_SPEED

public static final double NOMINAL_BARREL_ROTATION_SPEED

Default barrel rotation speed in degrees/sec.

See Also:
Constant Field Values

NOMINAL_GRIPPER_CLOSE_TIME

public static final double NOMINAL_GRIPPER_CLOSE_TIME

Default gripper close time in seconds.

See Also:
Constant Field Values

NOMINAL_GRIPPER_OPEN_TIME

public static final double NOMINAL_GRIPPER_OPEN_TIME

Default gripper open time in seconds.

See Also:
Constant Field Values

NOMINAL_SHADE_ROTATION_SPEED

public static final double NOMINAL_SHADE_ROTATION_SPEED

Default shade rotation speed in degrees/sec.

See Also:
Constant Field Values

DEFAULT_UPDATE_TIME

public static final double DEFAULT_UPDATE_TIME

Default period at which to update(double), seconds.

See Also:
Constant Field Values

DEFAULT_GRIPPER_SLOP

public static final double DEFAULT_GRIPPER_SLOP

Slop below which gripper state should snap to ShadyCommonAPI.CLOSED_STATE or ShadyCommonAPI.OPEN_STATE.

See Also:
Constant Field Values

DEFAULT_SHADE_SLOP

public static final double DEFAULT_SHADE_SLOP

Slop below which the shade is considered open or closed, in degrees.

See Also:
Constant Field Values

DEFAULT_SHADE_OPEN_ANGLE

public static final double DEFAULT_SHADE_OPEN_ANGLE

Default signed CCW angle in degrees at which the shade is open.

See Also:
Constant Field Values

BARREL_NAME

public static final java.lang.String[] BARREL_NAME

The barrel names.


GRIPPER_OPERATION_NAME

public static final java.lang.String[] GRIPPER_OPERATION_NAME

The gripper operation names.


FAULT_NAME

public static final java.lang.String[] FAULT_NAME

Names for the faults.


ENERGY

public static final int ENERGY

Index of energy resource.

See Also:
Constant Field Values

TIME

public static final int TIME

Index of time resource.

See Also:
Constant Field Values

clock

protected vona.time.Clock clock

Keeps track of time for this Shady.

Init from makeClock().


updateThread

protected java.lang.Thread updateThread

An async thread to update(double).

Initialized from makeUpdateThread().

If non-null, this will be started by the constructor.


pose

protected ShadyPose pose

The current pose of the mechanism, may be null.

To interoperate with the default machinery you must synchronize on this object before reading or writing it.

DEADLOCK AVOIDANCE: synchronization order is pose, then state, then accountingInfo.


state

protected ShadyState state

Internal representation of the current state.

Initialized by makeState().

To interoperate with the default machinery you must synchronize on this object before reading or writing it.

DEADLOCK AVOIDANCE: synchronization order is pose, then state, then accountingInfo.


accountingInfo

protected ShadyAccountingInfo accountingInfo

Internal representation of the current accounting info.

Initialized by makeAccountingInfo().

To interoperate with the default machinery you must synchronize on this object before reading or writing it.

DEADLOCK AVOIDANCE: synchronization order is pose, then state, then accountingInfo.


name

protected java.lang.String name

The user-set name, if any.


bodySegment

protected AbstractSegment bodySegment

Cached body segment.


wouldDuelOverride

protected boolean wouldDuelOverride

Whether to override generation of ShadyCommonAPI.WOULD_DUEL faults.


wouldTiltOverride

protected boolean wouldTiltOverride

Whether to override generation of ShadyCommonAPI.WOULD_TILT faults.


accumulating

protected boolean accumulating

Whether we're currently accumulating barrel and shade rotations.


accumulatedBarrelRotation

protected double[] accumulatedBarrelRotation

Current accumulated barrel rotations.


accumulatedShadeRotation

protected double accumulatedShadeRotation

Current accumulated shade rotation.

Constructor Detail

ShadyCommon

public ShadyCommon(ShadyPose pose)

Create a new ShadyCommon.

Calls reset() and resetAccounting(), then sets initial accountingInfo.currentBatteryEnergy (see reallyGetCurrentBatteryEnergy(), then start()s updateThread iff it's not null.

Parameters:
pose - the initial pose, or null for none (see setPose(shady.common.ShadyPose))

ShadyCommon

public ShadyCommon()

Covers ShadyCommon(ShadyPose), no initial pose.

Method Detail

otherBarrel

public static int otherBarrel(int barrel)

Convenience method to get the other barrel.

Parameters:
barrel - you want the other one
Returns:
the other one

checkBarrel

public static void checkBarrel(int barrel)

Check a barrel id.

Parameters:
barrel - the barrel id to check
Throws:
java.lang.IllegalArgumentException - if barrel is not ShadyCommonAPI.LEFT or ShadyCommonAPI.RIGHT

barrelName

public static java.lang.String barrelName(int barrel)

Get the name of a barrel.

Parameters:
barrel - the barrel for which to return the name
Returns:
the name of barrel

otherGripperOperation

public static int otherGripperOperation(int operation)

Convenience method to get the other gripper operation.

Parameters:
operation - you want the other one
Returns:
the other one

checkGripperOperation

public static void checkGripperOperation(int operation)

Check a gripper operation.

Parameters:
operation - the gripper operation to check
Throws:
java.lang.IllegalArgumentException - if operation is not ShadyCommonAPI.GRIPPER_CLOSE or ShadyCommonAPI.GRIPPER_OPEN

gripperOperationName

public static java.lang.String gripperOperationName(int operation)

Get the name of a gripper operation.

Parameters:
operation - the operation for which to return the name
Returns:
the name of operation

gripperStateName

public static java.lang.String gripperStateName(double state,
                                                DoubleFormatter formatter)

Get the name of a gripper state.

Parameters:
state - the gripper state
formatter - the formatter to use if the gripper is in-between states, null for none
Returns:
the string representation of state

gripperStateName

public static java.lang.String gripperStateName(double state)

Convenience cover of gripperStateName(double, DoubleFormatter), uses no formatter.


getGripperOperationTargetState

public static double getGripperOperationTargetState(int operation)

Get the target state of a gripper operation.

Parameters:
operation - the operation for which to get the target state
Returns:
the target state of operation

faultName

public java.lang.String faultName(int fault)

Get the name of a fault.

Specified by:
faultName in interface ShadyCommonAPI
Parameters:
fault - the fault for which to get the name
Returns:
the name of fault

reset

public int reset()

Attempt to reset the mechanism.

A call to this method will not change the mechanism state, however if any motion was ongoing it will be stopped and an ShadyCommonAPI.ESTOP fault will occur.

The current barrel angles and gripper states are be re-determined.

Any current fault condition will be cleared. However, implementations may subsequently check for any ongoing fault. The first such fault that is found is then set as the current fault and the return value from this method is false.

This is intended to be a relatively lightweight operation to clear a fault condition. I.e. is does not necessarily entail a reboot.

This method does not ShadyCommonAPI.resetAccounting().

Default impl clears state.fault and state.faultDetails, then ShadyCommonAPI.stop(boolean), reestablishState() and checkFault().

Specified by:
reset in interface ShadyCommonAPI
Returns:
0 iff reset was successful and no ongoing fault is detected, else the ongoing fault

reestablishState

protected void reestablishState()

Examine the mechanism to reestablish the state.

Implementations should not do anything during the execution of this method which itself could cause a fault or change the state of the mechanism.

The examined state should be written to state. state should only be modified if all values can be determined without any problems. Otherwise state should not be modified.

Default impl does nothing.


checkFault

protected void checkFault()

Check the mechansim for any ongoing fault condition.

Implementations should not do anything during the execution of this method which itself could cause a fault or change the state of the mechanism.

If a fault is detected it should be written to state.fault and its details to state.faultDetails. If no faults are detected, these variables should not be modified.

Default impl uses checkEnergy(double, java.lang.String) to see if less than NOMINAL_MIN_ENERGY is available.


checkEnergy

protected boolean checkEnergy(double energyRequired,
                              java.lang.String msg)

Check whether at least NOMINAL_MIN_ENERGY plus energyRequired remains.

Sets a ShadyCommonAPI.LOW_BATTERY fault if not enough energy is left.

Parameters:
energyRequired - the required energy in Joules, may be 0.0
msg - the error message for the fault details, if null then a default is used
Returns:
true iff enough energy remains

rotateBarrel

public int rotateBarrel(int barrel,
                        double dt)

Incrementally rotate barrel.

Fails fast if the mechanism is currently in fault.

Blocks until the rotation is complete or a fault has been detected, including an implementation-dependent timeout. Should never block indefinitely.

An implementation is allowed to consider the rotation to be "complete" and return without fault even if the target value has only been reached approximately. ShadyCommonAPI.getBarrelAngle(int) can be subsequently queried to determine the actual mechanism state.

This impl checks that not both barrels are connected, that dt is within limit, then asks reallyRotateBarrel(int, double) to do the rotation, then takes care of all accounting info updates.

Factored into rotateBarrelPre(int, double), rotateBarrel(int, double, double[]), and rotateBarrelPost(int, double, double, double).

Specified by:
rotateBarrel in interface ShadyCommonAPI
Parameters:
barrel - the barrel to rotate, ShadyCommonAPI.LEFT or ShadyCommonAPI.RIGHT
dt - a positive or negative real number giving the incremental rotation in degrees. The sum of dt and the current angle of the corresponding barrel (as returned from getBarrelAngle()) must be in the range [-limit, limit] where limit is given by ShadyCommonAPI.getBarrelRotationLimit(). Note that this must be true not only before this method is called, but also when the check is actually made, sometime during the execution of this method before motion is begun. The validity of the check may change between these two times, e.g. due to unexpected motion of the mechanism, or noise/drift in sensor readings.
Returns:
0 iff the rotation was successful, otherwise the fault that occurred

rotateBarrelTo

public int rotateBarrelTo(int barrel,
                          double angle)

Same as ShadyCommonAPI.rotateBarrel(int, double) but goes to an absolute angle.

See the class header doc for ShadyState for the semantics of the barrel angles.

Specified by:
rotateBarrelTo in interface ShadyCommonAPI
Parameters:
barrel - the barrel to rotate, ShadyCommonAPI.LEFT or ShadyCommonAPI.RIGHT
angle - the absolute angle, in degrees

rotateBarrelPre

protected double rotateBarrelPre(int barrel,
                                 double dt)

First part of rotateBarrel(int, double).

Checks for predictive faults.

Parameters:
barrel - same as for rotateBarrel(int, double)
dt - same as for rotateBarrel(int, double)
Returns:
startAngle the starting angle in degrees or NaN if one of the predictive faults triggered

wouldDuel

protected boolean wouldDuel(boolean enableFault)

Check whether the barrels would duel on rotation.

Parameters:
enableFault - whether to set a ShadyCommonAPI.WOULD_DUEL fault if the barrels would duel and not wouldDuelOverride
Returns:
true iff the barrels would duel on rotation

rotateBarrel

protected void rotateBarrel(int barrel,
                            double dt,
                            double[] resource)

Second part of rotateBarrel(int, double).

Short circuits if dt epsilon equals 0.0, otherwise executes motion and collects resource usage.

Parameters:
barrel - same as for rotateBarrel(int, double)
dt - same as for rotateBarrel(int, double)
resource - a two-element array into which ENERGY and TIME are recorded on return

rotateBarrelPost

protected int rotateBarrelPost(int barrel,
                               double dt,
                               double energy,
                               double time)

Third part of rotateBarrel(int, double).

Updates accountingInfo, and if any rotation occurred with the distal gripper open, and we have a pose, unsets ShadyPose.distalPoint.

Parameters:
barrel - same as for rotateBarrel(int, double)
dt - the movement in degrees of barrel
energy - the energy used while rotating in Joules, or -1 if unavailable
time - the time spent rotating in seconds
Returns:
the fault state after rotating

reallyRotateBarrel

protected abstract double reallyRotateBarrel(int barrel,
                                             double dt)

Really rotates the barrel.

Implementations should have this method do whatever is necessary to rotate the barrel the requested amount, updating state appropriately. Motion limit checking will have already been performed (based on the prior state) in rotateBarrel(int, double). All accounting info management is also done in rotateBarrel(). This method must simply


closeGripper

public int closeGripper(int barrel,
                        Point.OnSegment gripPoint)

Close the gripper in barrel.

Has no effect if the specified gripper is currently in the closed state. The current state of the gripper can be queried from ShadyCommonAPI.getGripperState(int).

Fails fast if the mechanism is currently in fault.

Blocks until the close operation is complete or a fault has been detected, including an implementation-dependent timeout. Should never block indefinitely.

If the return value is 0 then the mechansim considers the gripper to be correctly closed and gripping an environment segment.

Note that even if the return value is 0, the mechanism may at any time detect an unexpected gripper "opening", and change the status of the gripper back to open.

There are exactly two ways for a gripper to change from an open state to a closed state. One is via a call to this method, and the other is if the gripper is detected as actually closed during a ShadyCommonAPI.reset().

It is an error to attempt to close a gripper unless the mechansim considers it to be properly aligned with an environment segment. The precise definition of "properly aligned" is mechanism dependent. ShadyCommonAPI.isGripperAligned(int, shady.common.Point.OnSegment) may be queried to check if the mechanism considers a gripper to be properly aligned.

This impl checks if the gripper is already closed, then checks alignment, then asks setGripper(int, int) to do the close.

Factored into closeGripperPre(int, shady.common.Point.OnSegment), setGripper(int, int), and closeGripperPost(int, shady.common.Point.OnSegment).

Specified by:
closeGripper in interface ShadyCommonAPI
Parameters:
barrel - the barrel containing the gripper to close, ShadyCommonAPI.LEFT or ShadyCommonAPI.RIGHT
gripPoint - the point on the Environment where the caller intends the gripper to close, or null if unknown. If the caller has this piece of information it should provide it because it may improve performance of some impls.
Returns:
0 iff the gripper closing was successful, otherwise the fault that occurred

closeGripperPre

protected Point.OnSegment closeGripperPre(int barrel,
                                          Point.OnSegment gripPoint)

First part of closeGripper(int, Point.OnSegment).

Checks for predictive faults and tries to find gripPoint if not supplied.

Parameters:
barrel - same as for closeGripper(int, Point.OnSegment)
gripPoint - same as for closeGripper(int, Point.OnSegment)
Returns:
the grip point, or null if unaligned

closeGripper

public int closeGripper(int barrel)

Same as ShadyCommonAPI.closeGripper(int, Point.OnSegment) but for use only when the caller cannot provide gripPoint.

This impl defers to closeGripper(int, Point.OnSegment).

Specified by:
closeGripper in interface ShadyCommonAPI

closeGripperPost

protected void closeGripperPost(int barrel,
                                Point.OnSegment gripPoint)

Last part of closeGripper(int, Point.OnSegment).

If we have a pose and we just closed the distal barrel, then update pose's ShadyPose.distalPoint.

Parameters:
barrel - same as for closeGripper(int, Point.OnSegment)
gripPoint - same as for closeGripper(int, Point.OnSegment)

openGripper

public int openGripper(int barrel)

Open the gripper in barrel.

Has no effect if the specified gripper is currently in the open state. The current state of the gripper can be queried from ShadyCommonAPI.getBarrelAngle(int).

Fails fast if the mechanism is currently in fault.

Blocks until the open operation is complete or a fault has been detected, including an implementation-dependent timeout. Should never block indefinitely.

If the return value is 0 then the mechansim considers the gripper to be correctly open.

There are exactly two ways for a gripper to change from a closed state to an open state. One is via a call to this method. However the mechanism may also (asynchronously) detect that a gripper has opened or otherwise lost its hold, resulting in a ShadyCommonAPI.TILT fault.

It is an error to attempt to open a gripper unless the mechanism considers the other gripper to be currently closed on an environment segment.

This impl checks if the gripper is already open, then checks that the other gripper is closed, then asks setGripper(int, int) to do the open.

Factored into openGripperPre(int), setGripper(int, int), and openGripperPost(int).

Specified by:
openGripper in interface ShadyCommonAPI
Parameters:
barrel - the barrel containing the gripper to open, ShadyCommonAPI.LEFT or ShadyCommonAPI.RIGHT
Returns:
0 iff the gripper opening was successful, otherwise the fault that occurred

openGripperPre

protected int openGripperPre(int barrel)

First part of openGripper(int).

Checks for predictive faults.

Parameters:
barrel - same as for openGripper(int)
Returns:
the fault status

disableTiltCheck

protected boolean disableTiltCheck()

Whether to disable tilt checking on gripper open.

Default impl returns wouldTiltOverride.

Returns:
true to disable tilt checking on gripper open

openGripperPost

protected void openGripperPost(int barrel)

Last part of openGripper(int).

Conjugates pose if any and if necessary.

Parameters:
barrel - same as for openGripper(int)

setGripper

protected int setGripper(int barrel,
                         int operation)

This impl checks if motion is necessary and if so asks reallySetGripper(int, double) to do the motion, then takes care of all accounting info updates.

Factored into setGripperPre(int, int), setGripper(int, double, double[]), setGripperPost(int, int, double, double, double).


setGripperPre

protected double setGripperPre(int barrel,
                               int operation)

First part of setGripper(int, int).

Determines target state and checks whether we're already there.

Parameters:
barrel - same as for setGripper(int, int)
operation - same as for setGripper(int, int)
Returns:
the target state or NaN if we're already there

setGripper

protected void setGripper(int barrel,
                          double targetState,
                          double[] resource)

Second part of setGripper(int, int).

Executes motion and collects resource usage.

Parameters:
barrel - same as for setGripper(int, int)
targetState - target gripper state
resource - a two-element array into which ENERGY and TIME are recorded on return

setGripperPost

protected int setGripperPost(int barrel,
                             int operation,
                             double targetState,
                             double energy,
                             double time)

Third part of setGripper(int, int).

Updates accountingInfo, snaps gripper state.

Parameters:
barrel - same as for setGripper(int, int)
operation - same as for setGripper(int, int)
targetState - target gripper state
energy - the energy used while moving in Joules, or -1 if unavailable
time - the time spent moving in seconds
Returns:
the fault state after moving

getGripperSlop

protected double getGripperSlop()

Return slop below which gripper state should snap to ShadyCommonAPI.CLOSED_STATE or ShadyCommonAPI.OPEN_STATE.

Default impl returns DEFAULT_GRIPPER_SLOP.


reallySetGripper

protected abstract double reallySetGripper(int barrel,
                                           double targetState)

Really actuates the gripper.

Implementations should have this method do whatever is necessary to actuate the requested gripper, updating state appropriately. Checking if the gripper is already closed/open would have already happened in setGripper(int, int). All accounting info management is also done in setGripper(). This method must simply


isGripperAligned

public boolean isGripperAligned(int barrel,
                                Point.OnSegment point)

Check whether the mechanism considers the specified gripper to be "properly aligned" over an environment segment.

Closed grippers are always properly aligned.

An open gripper may be closed iff it is properly aligned. If so, it is expected that the close operation will succeed and that the gripper will subsequently be attached to the environment.

The precise definition of "properly aligned" is implementation dependent.

Implementations should not do anything which could affect the state of the mechanism, or which could cause a fault, during the execution of this method.

If barrel is closed this impl returns true.

If we have a non-null and full pose, we return ShadyPose.isDistalBarrelAligned(Point.OnSegment). Otherwise this impl returns true.

Specified by:
isGripperAligned in interface ShadyCommonAPI
Parameters:
barrel - the barrel containing the gripper to check, ShadyCommonAPI.LEFT or ShadyCommonAPI.RIGHT
point - the point on the Environment where the caller intends the gripper to close, or null if unknown. If the caller has this piece of information it should provide it because it may improve performance of some impls.
Returns:
true iff the mechanism considers the specified gripper to be "properly aligned" over an environment segment

isGripperOpen

public boolean isGripperOpen(int barrel)

Convenience method to check whether a gripper is logically open.

This impl uses getGripperSlop().

Specified by:
isGripperOpen in interface ShadyCommonAPI
Parameters:
barrel - the barrel containing the gripper to check
Returns:
true iff the gripper is logically open

isGripperClosed

public boolean isGripperClosed(int barrel)

Convenience method to check whether a gripper is logically closed.

This impl uses getGripperSlop().

Specified by:
isGripperClosed in interface ShadyCommonAPI
Parameters:
barrel - the barrel containing the gripper to check
Returns:
true iff the gripper is logically closed

isGripperAligned

public boolean isGripperAligned(int barrel)

Same as ShadyCommonAPI.isGripperAligned(int, Point.OnSegment) but for use only when the caller cannot provide gripPoint.

If barrel is closed this impl returns true.

If we have a non-null and full pose, we return ShadyPose.isDistalBarrelAligned(). Otherwise this impl returns true.

Specified by:
isGripperAligned in interface ShadyCommonAPI

getGripQuality

public double getGripQuality(int barrel)

Check the gripping quality of a closed gripper.

Implementations should not do anything which could affect the state of the mechanism, or which could cause a fault, during the execution of this method.

Default impl is sugar over getState(). A closed gripper is considered to have quality 1.0.

Specified by:
getGripQuality in interface ShadyCommonAPI
Parameters:
barrel - the barrel containing the gripper to check, ShadyCommonAPI.LEFT or ShadyCommonAPI.RIGHT
Returns:
a double in the range [0.0, 1.0] indicating the quality of grip, from worst to best, or < 0.0 if the indicated gripper is not closed

closeShade

public int closeShade()

Close the shade to 0 in opposite direction of ShadyCommonAPI.getShadeOpenAngle().

This impl checks if the shade is already closed, then asks rotateShade(double) to do the required motion, if any.

Specified by:
closeShade in interface ShadyCommonAPI
Returns:
0 iff the motion was successful, otherwise the fault that occurred

openShade

public int openShade()

Open the shade to ShadyCommonAPI.getShadeOpenAngle().

This impl checks if the shade is already open, then asks rotateShade(double) to do the required motion, if any.

Specified by:
openShade in interface ShadyCommonAPI
Returns:
0 iff the motion was successful, otherwise the fault that occurred

rotateShade

public int rotateShade(double dt)

Incrementally rotate the shade.

This impl chains to reallyRotateShade(double) unless there is a fault or motion accumulation is turned on.

Specified by:
rotateShade in interface ShadyCommonAPI
Parameters:
dt - a positive or negative real number giving the incremental rotation in degrees

reallyRotateShade

protected abstract double reallyRotateShade(double dt)

Really rotates the shade.

Implementations should have this method do whatever is necessary to rotate the shade the requested amount, updating state appropriately. This method must simply


getShadeOpenAngle

public double getShadeOpenAngle()

Get the signed CCW angle in degrees at which the shade is considered open.

This impl returns DEFAULT_SHADE_OPEN_ANGLE.

Specified by:
getShadeOpenAngle in interface ShadyCommonAPI
Returns:
the signed CCW angle in degrees at which the shade is considered open

isShadeOpen

public boolean isShadeOpen()

Check if the shade is open.

Specified by:
isShadeOpen in interface ShadyCommonAPI
Returns:
true iff the shade is open

isShadeClosed

public boolean isShadeClosed()

Check if the shade is closed.

Specified by:
isShadeClosed in interface ShadyCommonAPI
Returns:
true iff the shade is closed

beginAccumulatingMotion

public void beginAccumulatingMotion()

Begin accumulating barrel and shade rotations.

While accumulation is enabled these motions do not take effect immediately, but are deferred until ShadyCommonAPI.endAccumulatingMotion().

Has no effect if motion accumulation is already enabled.

Specified by:
beginAccumulatingMotion in interface ShadyCommonAPI

endAccumulatingMotion

public int endAccumulatingMotion()

End accumulating barrel and shade rotations.

The accumulated incremental rotations, if any, are executed as a ShadyCommonAPI.simultaneousMotion(double, double, double).

Has no effect if motion accumulation is already enabled.

Specified by:
endAccumulatingMotion in interface ShadyCommonAPI
Returns:
the current fault, if any

isAccumulatingMotion

public boolean isAccumulatingMotion()

Check whether barrel and shade rotation accumulation is currently enabled.

Specified by:
isAccumulatingMotion in interface ShadyCommonAPI
Returns:
true iff barrel and shade rotation accumulation is currently enabled

simultaneousMotion

public int simultaneousMotion(double leftBarrelDT,
                              double rightBarrelDT,
                              double shadeDT)

Execute a simultaneous barrel rotation and shade motion.

The final state of the mechanism should be the same as if the corresponding sequential calls were made to ShadyCommonAPI.rotateBarrel(int, double) and ShadyCommonAPI.rotateShade(double), but the motion should happen simultaneously on all actuators if possible.

Motion should be aborted as soon as a fault is detected.

Specified by:
simultaneousMotion in interface ShadyCommonAPI
Returns:
the current fault, if any

doSimultaneousMotion

protected abstract double doSimultaneousMotion(double leftBarrelDT,
                                               double rightBarrelDT,
                                               double shadeDT)

Implementation of simultaneousMotion(double, double, double).


getShadeSlop

protected double getShadeSlop()

Return slop below which shade state should snap to closed (0 deg) or open (getShadeOpenAngle()).

Default impl returns DEFAULT_SHADE_SLOP.


getState

public ShadyState getState()

Get the current state of the mechanism.

Note that this is only a snapshot of the mechanism state at some after this method was called and before it has returned. The actual state at any later time may be different.

Default impl returns a clone of state.

Specified by:
getState in interface ShadyCommonAPI
Returns:
an independent copy of the current state of the mechanism

getState

public ShadyState getState(ShadyState dest)

Same as ShadyCommonAPI.getState() but returns in dest.

Helps avoid generating a lot of garbage.

Default impl returns a copy of state.

Specified by:
getState in interface ShadyCommonAPI
Parameters:
dest - the destination, if null then cons a new one

setState

public boolean setState(ShadyState state)

Set the mechanism state.

This is not intended to cause actuation. Rather it is intended for use with implementations which are amenable to arbitrary state changes (i.e. simulators). Implementations tied to hardware should probably return false.

This impl sets state by copy and returns true.

Specified by:
setState in interface ShadyCommonAPI
Parameters:
state - the state to set, not null
Returns:
true iff the state was actually set

getBarrelAngle

public double getBarrelAngle(int barrel)

Get the current angle of the specified barrel, in degrees.

Default impl is sugar over getState().

Specified by:
getBarrelAngle in interface ShadyCommonAPI
Parameters:
barrel - the barrel for which to get the angle, ShadyCommonAPI.LEFT or ShadyCommonAPI.RIGHT
Returns:
the current angle of the specified barrel, in degrees

getGripperState

public double getGripperState(int barrel)

Get a gripper state.

Default impl is sugar over getState().

Specified by:
getGripperState in interface ShadyCommonAPI
Parameters:
barrel - the barrel containing the gripper to get
Returns:
the state of the gripper in the range [0.0, 1.0], with 0.0 open and 1.0 closed

getShadeAngle

public double getShadeAngle()

Get the shade angle in CCW degrees.

@return the shade angle in CCW degrees

Default impl is sugar over getState().

Specified by:
getShadeAngle in interface ShadyCommonAPI

getCurrentPower

public double getCurrentPower()

Get the current power used by the mechanism in Watts.

Default impl is sugar over getState().

Specified by:
getCurrentPower in interface ShadyCommonAPI
Returns:
the current power used by the mechanism in Watts

getNumActiveActuators

public int getNumActiveActuators()

Get the number of actuaturs currently active.

Default impl is sugar over getState().

Specified by:
getNumActiveActuators in interface ShadyCommonAPI
Returns:
the number of actuaturs currently active

getFault

public int getFault(java.lang.String[] faultDetails)

Get the current fault, if any.

Default impl is sugar over getState().

Specified by:
getFault in interface ShadyCommonAPI
Parameters:
faultDetails - if non-null and containing at least one element, and there is a current fault, the first element of this array is set on return to the current fault details
Returns:
the current fault, 0 if none

getFault

public int getFault()

Get the current fault, if any.

Default impl is sugar over getState().

Specified by:
getFault in interface ShadyCommonAPI
Returns:
the current fault, 0 if none

getFaultDetails

public java.lang.String getFaultDetails()

Get a human-readable detail string about the current Fault, if any.

Default impl is sugar over getState().

Specified by:
getFaultDetails in interface ShadyCommonAPI
Returns:
a human-readable detail string about current Fault, if any, or null if none

getPose

public ShadyPose getPose()

Get a copy of the current pose.

Specified by:
getPose in interface ShadyCommonAPI

getPose

public ShadyPose getPose(ShadyPose dest)

Get a copy of the current pose.

This impl copies pose into dest, unless the former is null, in which case only state is copied, and the rest of the parts of dest are unset.

Specified by:
getPose in interface ShadyCommonAPI
Parameters:
dest - the destination, if null then cons a new one

setPose

public boolean setPose(ShadyPose newPose)

Set the mechanism pose (by copy).

Note that if the distal barrel is closed after setting newPose that newPose.distalPoint and newPose.invertDistalSense must be valid and consistent.

Specified by:
setPose in interface ShadyCommonAPI
Parameters:
newPose - the pose to set, null for none. State will be copied only if pose and pose.state are not null.
Returns:
true iff the state was set

resetAccounting

public void resetAccounting()

Reset all accounting.

See ShadyAccountingInfo.

This also happens implicitly at reboot.

Counts are set to zero, averages are set to thier nominal values.

totalBatteryEnergy set from reallyGetTotalBatteryEnergy().

currentBatteryEnergy set from reallyGetCurrentBatteryEnergy(), unless that returns negative, in which case it's kept at its previous value.

Specified by:
resetAccounting in interface ShadyCommonAPI

reallyGetTotalBatteryEnergy

protected double reallyGetTotalBatteryEnergy()

Get the total battery capacity, when fully charged, in Joules.

Default impl returns NOMINAL_TOTAL_BATTERY_ENERGY.

Returns:
the total battery capacity, when fully charged, in Joules

reallyGetCurrentBatteryEnergy

protected double reallyGetCurrentBatteryEnergy()

Get the remaining battery energy in Joules.

Implementations can actually make a battery measurement here or they can return a negative number to indicate they do not implement this function. In the latter case the default machinery in ShadyCommon will assume that the battery was full on boot and will decrement the accountingInfo.currentBatteryEnergy automatically as energy is used.

Default impl returns -1.0.

Returns:
the remaining battery energy in Joules

getAccountingInfo

public ShadyAccountingInfo getAccountingInfo()

Get the accounting info accumulated since reboot or since the last ShadyCommonAPI.resetAccounting().

Default impl returns a clone of accountingInfo.

Specified by:
getAccountingInfo in interface ShadyCommonAPI
Returns:
an independent copy of the accounting info accumulated since reboot or since the last resetAccounting()

getAccountingInfo

public ShadyAccountingInfo getAccountingInfo(ShadyAccountingInfo dest)

Same as ShadyCommonAPI.getAccountingInfo() but returns in dest.

Helps avoid generating a lot of garbage.

Default impl returns a copy of accountingInfo.

Specified by:
getAccountingInfo in interface ShadyCommonAPI
Parameters:
dest - the destination, if null then cons a new one

getBarrelRotationLimit

public double getBarrelRotationLimit()

Get the barrel rotation limit, in degrees.

This value is constant for any implementation.

Double.POSITIVE_INFINITY if unlimited motion is allowed.

In any implementation, both barrels must have the same limit. The limit is always symmetric, so the barrel angle is in the range [-limit, limit].

Default impl returns NOMINAL_BARREL_ROTATION_LIMIT.

Specified by:
getBarrelRotationLimit in interface ShadyCommonAPI
Returns:
the barrel rotation limit, in degrees

getCenterToCenterDistance

public double getCenterToCenterDistance()

Get the center-to-center distance between barrel rotation axes, in meters.

This value is constant for any implementation.

Default impl returns NOMINAL_CENTER_TO_CENTER_DISTANCE.

Specified by:
getCenterToCenterDistance in interface ShadyCommonAPI
Returns:
the center-to-center distance between barrel rotation axes, in meters

getTotalLength

public double getTotalLength()

Get the tip-to-tip mechansim length, in meters.

This value is constant for any implementation.

Default impl returns NOMINAL_TOTAL_LENGTH.

Specified by:
getTotalLength in interface ShadyCommonAPI
Returns:
the tip-to-tip mechanism length, in meters

getGripperWidth

public double getGripperWidth()

Get the width of the gripper paddles, in meters.

This value is constant for any implementation.

Default impl returns NOMINAL_GRIPPER_WIDTH.

Specified by:
getGripperWidth in interface ShadyCommonAPI
Returns:
the width of the gripper paddles, in meters

setName

public void setName(java.lang.String name)

Set the name of this Shady.

Specified by:
setName in interface ShadyCommonAPI
Parameters:
name - the name of this Shady

getName

public java.lang.String getName()

Get the name of this Shady.

This impl returns the simple name of the runtime type unless setName(java.lang.String) has been called with a non-null name.

Specified by:
getName in interface ShadyCommonAPI
Returns:
the name of this Shady

isNameSet

public boolean isNameSet()

Check whether the name of this Shady has been explicitly set.

Specified by:
isNameSet in interface ShadyCommonAPI
Returns:
true iff the name of this Shady has been explicitly set non-null by a call to ShadyCommonAPI.setName(java.lang.String)

pick

public boolean pick(Point p,
                    double threshold)

Check if this Shady is picked by p in world coordinates (meters) within a given threshold in meters.

This impl chains to pick(Point, double, Point.OnSegment), always conses a new projectionPoint.

Specified by:
pick in interface ShadyCommonAPI
Parameters:
p - the pick point in world coordinates (meters)
threshold - the distance threshold in meters, negative for no threshold
Returns:
true iff this Shady is picked by the specified point within threshold

pick

public boolean pick(Point p,
                    double threshold,
                    Point.OnSegment projectionPoint)

Determine whether p is within threshold of its projection onto this Shady's body segment.

Parameters:
projectionPoint - if non-null then this will be used as scratch to project p onto ccSegment, else cons
Returns:
true iff p is within threshold of its projection onto this Shady's body segment

getClock

public vona.time.Clock getClock()

Get the clock this Shady is using.

This impl returns clock.

Specified by:
getClock in interface ShadyCommonAPI
Returns:
the clock this Shady is using

toString

public java.lang.String toString()

Same as toString(DoubleFormatter) but uses no formatter.

Overrides:
toString in class java.lang.Object

toString

public java.lang.String toString(DoubleFormatter formatter)

Same as toString(DoubleFormatter, boolean) but uses no HTML.


toString

public java.lang.String toString(DoubleFormatter formatter,
                                 boolean html)

Same as toString(DoubleFormatter, boolean, java.awt.Color[], java.awt.Color) but uses no colors.


toString

public java.lang.String toString(DoubleFormatter formatter,
                                 boolean html,
                                 java.awt.Color[] barrelColor,
                                 java.awt.Color faultColor)

Get a human-readable string representation of this Shady.

Parameters:
formatter - the number formatter to use, null for none
html - whether to use HTML
barrelColor - the barrel colors to use, null for none
faultColor - the color to use for fault, null for none
Returns:
a human-readable string representation of this Shady

appendHTMLFontTag

protected java.lang.StringBuffer appendHTMLFontTag(java.lang.StringBuffer buf,
                                                   java.awt.Color color)

Append a colored HTML font tag.

Parameters:
buf - the buffer in which to write
color - the font color, not null
Returns:
buf

appendBarrelString

protected java.lang.StringBuffer appendBarrelString(java.lang.StringBuffer buf,
                                                    DoubleFormatter formatter,
                                                    int barrel,
                                                    boolean html,
                                                    java.awt.Color[] barrelColor)

Append a human-readable string representation of barrel.

Parameters:
buf - the buffer in which to write
formatter - the number formatter to use, null for none
barrel - the barrel to write
html - whether to use HTML
barrelColor - the barrel colors to use, null for none
Returns:
buf

update

protected void update(double dt)

By default this is called at the period getUpdateTime() by updateThread.

Default impl calls updateState(double), then updates the time-integrated members of accountingInfo.

Default impl uses checkEnergy(double, java.lang.String) to see if less than NOMINAL_MIN_ENERGY is available.

Parameters:
dt - the time since the last update, in seconds

updateState

protected void updateState(double dt)

This is used by the default impl of update(double).

By default, this will be called while synchronized on state.

Default impl just calls reestablishState().

This is a hook: implementations may override this to change the way state is updated but still use the rest of the default update(double) machinery.

Parameters:
dt - the time since the last update, in seconds

makeClock

protected vona.time.Clock makeClock()

Instantiate clock.

This is a hook to allow subclasses to implement the clock differently.

This impl just returns a new Clock.

Returns:
the clock

getUpdateTime

protected double getUpdateTime()

Get the update period, in seconds.

Used by the default impl of makeUpdateThread().

Default impl returns DEFAULT_UPDATE_TIME.

#return the update period in seconds


makeUpdateThread

protected java.lang.Thread makeUpdateThread()

Instantiate updateThread.

Default impl assumes we have a clock and returns a new vona.time.AccelTime.PeriodicThread from clock that calls update(double) with period getUpdateTime().

This is a hook to allow subclasses to implement the update thread differently.

Returns:
the update thread, not started

makeState

protected ShadyState makeState()

Instantiate state.

Default impl returns a new ShadyState.

This is a hook to allow subclasses to use a subclass of ShadyState but to retain the rest of the default statea machinery.

Returns:
the state instance

makeAccountingInfo

protected ShadyAccountingInfo makeAccountingInfo()

Instantiate accountingInfo.

Default impl returns a new ShadyAccountingInfo.

This is a hook to allow subclasses to use a subclass of ShadyAccountingInfo but to retain the rest of the default accountingInfo machinery.

Returns:
the accounting info instance

setFault

public int setFault(int fault,
                    java.lang.String details)

Try to set a fault.

Has no effect if there was an existing fault.

accountingInfo is updated iff the fault was set.

Parameters:
fault - the fault to set
details - the fault details
Returns:
the resulting fault state, either fault or the existing fault

setWouldDuelOverride

public void setWouldDuelOverride(boolean wouldDuelOverride)

Set whether to override generation of ShadyCommonAPI.WOULD_DUEL faults.

Specified by:
setWouldDuelOverride in interface ShadyCommonAPI
Parameters:
wouldDuelOverride - whether to override generation of ShadyCommonAPI.WOULD_DUEL faults

setWouldTiltOverride

public void setWouldTiltOverride(boolean wouldTiltOverride)

Set whether to override generation of ShadyCommonAPI.WOULD_TILT faults.

Specified by:
setWouldTiltOverride in interface ShadyCommonAPI
Parameters:
wouldTiltOverride - whether to override generation of ShadyCommonAPI.WOULD_TILT faults

getCurrentTime

protected double getCurrentTime()

Covers clock.getCurrentTime() iff clock is set, else uses the system clock.