shady.common
Interface ShadyCommonAPI

All Known Subinterfaces:
MemberShadyCommonAPI, MemberShadySimAPI, ShadySimAPI
All Known Implementing Classes:
MemberShadySim, ShadyCommon, ShadySim

public interface ShadyCommonAPI

Shady API subset that is shared between the simulator and the hardware.

Target: 1.1 JRE.

This is the minimum interface that must be supported by any Shady hardware or simulator. Specific implementations may add functionality as desired.

See also ShadyState, ShadyPose, ShadyAccountingInfo, and Environment.

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

Field Summary
static double CLOSED_STATE
          Identifies a closed gripper.
static int COLLISION
          A collision may have occurred.
static java.lang.String cvsid
          CVS id.
static int ESTOP
          An ongoing motion was reset().
static int GRIPPER_CLOSE
          Identifies a gripper close operation.
static int GRIPPER_OPEN
          Identifies a gripper open operation.
static double[] GRIPPER_OPERATION_TARGET_STATE
          The gripper operation target states.
static int IMPLEMENTATION_FAULT
          Implementation-specific faults start at this number.
static int LEFT
          Identifies the left barrel.
static int LOW_BATTERY
          The battery level is currently too low to perform the requested operation.
static int MOTION_LIMIT
          The specified action may have caused a mechanism DOF to hit or exceed a motion limit.
static double OPEN_STATE
          Identifies an open gripper.
static int OVER_CURRENT
          An over-current condition was reached in an actuator or driver.
static int OVER_TEMP
          An over-temp condition was reached in an actuator or driver.
static int RIGHT
          Identifies the right barrel.
static int TILT
          The mechanism may not be correctly attached to the environment.
static int TIMEOUT
          An implementation-dependent timeout was reached.
static int UNALIGNED
          The gripper may not be properly aligned with an environment segment.
static int UNKNOWN
          An unknown fault occurred.
static int WOULD_COLLIDE
          The specified action might cause a collision.
static int WOULD_DUEL
          You can't rotate if both grippers are connected.
static int WOULD_MOTION_LIMIT
          The specified action might cause a mechanism DOF to go past a motion limit.
static int WOULD_TILT
          The mechanism would not be correctly attached to the environment.
 
Method Summary
 void beginAccumulatingMotion()
          Begin accumulating barrel and shade rotations.
 int closeGripper(int barrel)
          Same as 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.
 int closeShade()
          Close the shade to 0 in opposite direction of getShadeOpenAngle().
 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 resetAccounting().
 ShadyAccountingInfo getAccountingInfo(ShadyAccountingInfo dest)
          Same as 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.
 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.
 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.
 ShadyState getState()
          Get the current state of the mechanism.
 ShadyState getState(ShadyState dest)
          Same as getState() but returns in dest.
 double getTotalLength()
          Get the tip-to-tip mechansim length, in meters.
 boolean isAccumulatingMotion()
          Check whether barrel and shade rotation accumulation is currently enabled.
 boolean isGripperAligned(int barrel)
          Same as isGripperAligned(int, Point.OnSegment) but for use only when the caller cannot provide gripPoint.
 boolean isGripperAligned(int barrel, Point.OnSegment gripPoint)
          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.
 int openGripper(int barrel)
          Open the gripper in barrel.
 int openShade()
          Open the shade to getShadeOpenAngle().
 boolean pick(Point p, double threshold)
          Check if this Shady is picked by p in world coordinates (meters) within a given threshold in meters.
 int reset()
          Attempt to reset the mechanism.
 void resetAccounting()
          Reset all accounting.
 int rotateBarrel(int barrel, double dt)
          Incrementally rotate barrel.
 int rotateBarrelTo(int barrel, double angle)
          Same as rotateBarrel(int, double) but goes to an absolute angle.
 int rotateShade(double dt)
          Incrementally rotate the shade.
 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 WOULD_DUEL faults.
 void setWouldTiltOverride(boolean wouldTiltOverride)
          Set whether to override generation of WOULD_TILT faults.
 int simultaneousMotion(double leftBarrelDT, double rightBarrelDT, double shadeDT)
          Execute a simultaneous barrel rotation and shade motion.
 void stop(boolean estop)
          Stop all ongoing motion.
 

Field Detail

cvsid

static final java.lang.String cvsid

CVS id.

See Also:
Constant Field Values

LEFT

static final int LEFT

Identifies the left barrel.

See Also:
Constant Field Values

RIGHT

static final int RIGHT

Identifies the right barrel.

See Also:
Constant Field Values

CLOSED_STATE

static final double CLOSED_STATE

Identifies a closed gripper.

See Also:
Constant Field Values

OPEN_STATE

static final double OPEN_STATE

Identifies an open gripper.

See Also:
Constant Field Values

GRIPPER_CLOSE

static final int GRIPPER_CLOSE

Identifies a gripper close operation.

See Also:
Constant Field Values

GRIPPER_OPEN

static final int GRIPPER_OPEN

Identifies a gripper open operation.

See Also:
Constant Field Values

GRIPPER_OPERATION_TARGET_STATE

static final double[] GRIPPER_OPERATION_TARGET_STATE

The gripper operation target states.


UNKNOWN

static final int UNKNOWN

An unknown fault occurred.

See Also:
Constant Field Values

TIMEOUT

static final int TIMEOUT

An implementation-dependent timeout was reached.

See Also:
Constant Field Values

LOW_BATTERY

static final int LOW_BATTERY

The battery level is currently too low to perform the requested operation.

See Also:
Constant Field Values

OVER_CURRENT

static final int OVER_CURRENT

An over-current condition was reached in an actuator or driver.

See Also:
Constant Field Values

OVER_TEMP

static final int OVER_TEMP

An over-temp condition was reached in an actuator or driver.

See Also:
Constant Field Values

WOULD_COLLIDE

static final int WOULD_COLLIDE

The specified action might cause a collision.

See Also:
Constant Field Values

COLLISION

static final int COLLISION

A collision may have occurred.

See Also:
Constant Field Values

WOULD_MOTION_LIMIT

static final int WOULD_MOTION_LIMIT

The specified action might cause a mechanism DOF to go past a motion limit.

See Also:
Constant Field Values

MOTION_LIMIT

static final int MOTION_LIMIT

The specified action may have caused a mechanism DOF to hit or exceed a motion limit.

See Also:
Constant Field Values

UNALIGNED

static final int UNALIGNED

The gripper may not be properly aligned with an environment segment.

See Also:
Constant Field Values

WOULD_TILT

static final int WOULD_TILT

The mechanism would not be correctly attached to the environment.

See Also:
Constant Field Values

TILT

static final int TILT

The mechanism may not be correctly attached to the environment.

See Also:
Constant Field Values

ESTOP

static final int ESTOP

An ongoing motion was reset().

See Also:
Constant Field Values

WOULD_DUEL

static final int WOULD_DUEL

You can't rotate if both grippers are connected.

See Also:
Constant Field Values

IMPLEMENTATION_FAULT

static final int IMPLEMENTATION_FAULT

Implementation-specific faults start at this number.

See Also:
Constant Field Values
Method Detail

faultName

java.lang.String faultName(int fault)

Get the name of a fault.

Parameters:
fault - the fault for which to get the name
Returns:
the name of fault

reset

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 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 resetAccounting().

Returns:
0 iff reset was successful and no ongoing fault is detected, else the ongoing fault

stop

void stop(boolean estop)

Stop all ongoing motion.

Has no effect if there is no ongoing motion.

Sets an ESTOP fault iff estop is true, there was ongoing motion, and there was no prior fault condition.

Parameters:
estop - whether to enable ESTOP fault generation

rotateBarrel

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. getBarrelAngle(int) can be subsequently queried to determine the actual mechanism state.

Parameters:
barrel - the barrel to rotate, LEFT or 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 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

int rotateBarrelTo(int barrel,
                   double angle)

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

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

Parameters:
barrel - the barrel to rotate, LEFT or RIGHT
angle - the absolute angle, in degrees

closeGripper

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 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 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. isGripperAligned(int, shady.common.Point.OnSegment) may be queried to check if the mechanism considers a gripper to be properly aligned.

Parameters:
barrel - the barrel containing the gripper to close, LEFT or 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

closeGripper

int closeGripper(int barrel)

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


openGripper

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 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 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.

Parameters:
barrel - the barrel containing the gripper to open, LEFT or RIGHT
Returns:
0 iff the gripper opening was successful, otherwise the fault that occurred

isGripperAligned

boolean isGripperAligned(int barrel,
                         Point.OnSegment gripPoint)

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.

Parameters:
barrel - the barrel containing the gripper to check, LEFT or 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:
true iff the mechanism considers the specified gripper to be "properly aligned" over an environment segment

isGripperAligned

boolean isGripperAligned(int barrel)

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


isGripperOpen

boolean isGripperOpen(int barrel)

Convenience method to check whether a gripper is logically open.

Parameters:
barrel - the barrel containing the gripper to check
Returns:
true iff the gripper is logically open

isGripperClosed

boolean isGripperClosed(int barrel)

Convenience method to check whether a gripper is logically closed.

Parameters:
barrel - the barrel containing the gripper to check
Returns:
true iff the gripper is logically closed

getGripQuality

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.

Parameters:
barrel - the barrel containing the gripper to check, LEFT or 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

int closeShade()

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

Returns:
0 iff the motion was successful, otherwise the fault that occurred

openShade

int openShade()

Open the shade to getShadeOpenAngle().

Returns:
0 iff the motion was successful, otherwise the fault that occurred

rotateShade

int rotateShade(double dt)

Incrementally rotate the shade.

Parameters:
dt - a positive or negative real number giving the incremental rotation in degrees

getShadeOpenAngle

double getShadeOpenAngle()

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

Returns:
the signed CCW angle in degrees at which the shade is considered open

isShadeOpen

boolean isShadeOpen()

Check if the shade is open.

Returns:
true iff the shade is open

isShadeClosed

boolean isShadeClosed()

Check if the shade is closed.

Returns:
true iff the shade is closed

beginAccumulatingMotion

void beginAccumulatingMotion()

Begin accumulating barrel and shade rotations.

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

Has no effect if motion accumulation is already enabled.


endAccumulatingMotion

int endAccumulatingMotion()

End accumulating barrel and shade rotations.

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

Has no effect if motion accumulation is already enabled.

Returns:
the current fault, if any

isAccumulatingMotion

boolean isAccumulatingMotion()

Check whether barrel and shade rotation accumulation is currently enabled.

Returns:
true iff barrel and shade rotation accumulation is currently enabled

simultaneousMotion

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 rotateBarrel(int, double) and rotateShade(double), but the motion should happen simultaneously on all actuators if possible.

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

Returns:
the current fault, if any

getState

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.

Returns:
an independent copy of the current state of the mechanism

getState

ShadyState getState(ShadyState dest)

Same as getState() but returns in dest.

Helps avoid generating a lot of garbage.

Parameters:
dest - the destination, if null then cons a new one

setState

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.

Parameters:
state - the state to set, not null
Returns:
true iff the state was actually set

getBarrelAngle

double getBarrelAngle(int barrel)

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

Parameters:
barrel - the barrel for which to get the angle, LEFT or RIGHT
Returns:
the current angle of the specified barrel, in degrees

getGripperState

double getGripperState(int barrel)

Get a gripper state.

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

double getShadeAngle()

Get the shade angle in CCW degrees.

@return the shade angle in CCW degrees


getCurrentPower

double getCurrentPower()

Get the current power used by the mechanism in Watts.

Returns:
the current power used by the mechanism in Watts

getNumActiveActuators

int getNumActiveActuators()

Get the number of actuaturs currently active.

Returns:
the number of actuaturs currently active

getFault

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

Get the current fault, if any.

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

int getFault()

Get the current fault, if any.

Returns:
the current fault, 0 if none

getFaultDetails

java.lang.String getFaultDetails()

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

Returns:
a human-readable detail string about current Fault, if any, or null if none

getPose

ShadyPose getPose()

Get a copy of the current pose.


getPose

ShadyPose getPose(ShadyPose dest)

Get a copy of the current pose.

Parameters:
dest - the destination, if null then cons a new one

setPose

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.

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

void resetAccounting()

Reset all accounting.

See ShadyAccountingInfo.

This also happens implicitly at reboot.


getAccountingInfo

ShadyAccountingInfo getAccountingInfo()

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

Returns:
an independent copy of the accounting info accumulated since reboot or since the last resetAccounting()

getAccountingInfo

ShadyAccountingInfo getAccountingInfo(ShadyAccountingInfo dest)

Same as getAccountingInfo() but returns in dest.

Helps avoid generating a lot of garbage.

Parameters:
dest - the destination, if null then cons a new one

getBarrelRotationLimit

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].

Returns:
the barrel rotation limit, in degrees

getCenterToCenterDistance

double getCenterToCenterDistance()

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

This value is constant for any implementation.

Returns:
the center-to-center distance between barrel rotation axes, in meters

getTotalLength

double getTotalLength()

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

This value is constant for any implementation.

Returns:
the tip-to-tip mechanism length, in meters

getGripperWidth

double getGripperWidth()

Get the width of the gripper paddles, in meters.

This value is constant for any implementation.

Returns:
the width of the gripper paddles, in meters

setName

void setName(java.lang.String name)

Set the name of this Shady.

Parameters:
name - the name of this Shady

getName

java.lang.String getName()

Get the name of this Shady.

Returns:
the name of this Shady

isNameSet

boolean isNameSet()

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

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

pick

boolean pick(Point p,
             double threshold)

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

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

getClock

vona.time.Clock getClock()

Get the clock this Shady is using.

Returns:
the clock this Shady is using

setWouldDuelOverride

void setWouldDuelOverride(boolean wouldDuelOverride)

Set whether to override generation of WOULD_DUEL faults.

Parameters:
wouldDuelOverride - whether to override generation of WOULD_DUEL faults

setWouldTiltOverride

void setWouldTiltOverride(boolean wouldTiltOverride)

Set whether to override generation of WOULD_TILT faults.

Parameters:
wouldTiltOverride - whether to override generation of WOULD_TILT faults