BHandSupervisoryRealtime Class Reference

This class provides methods from Supervisory and RealTime modules. More...

#include <BHandSupervisoryRealTime.h>

Inherits Poco::Runnable.

Inherited by BHand.

Public Member Functions

 BHandSupervisoryRealtime (BHand *bhand, int priority=THREAD_PRIORITY_TIME_CRITICAL)
int InitSoftware (int port, int priority=THREAD_PRIORITY_TIME_CRITICAL)
 Initialize this BHand instance.
int Init (int port, int priority, BHCommunication comm, bool async=false)
 Initialize this BHand instance.
bool IsInitialized ()
int ComRequest (int requestNumber)
 Sends a request to the low-level communication thread.
int ComWaitForCompletion (unsigned int timeout)
 Waits for low-level communication thread to complete processing.
bool ComIsPending ()
 Checks for a low-level pending communication request.
int ComGetError ()
 Checks the low-level thread for communication errors.
BHandSupervisoryResultGetResult ()
 Obtain command results after the supervisory command has finished running.
void SetWaitCallbackFunc (BHCallback waitCallbackFunc)
int InitHand (const char *motor)
 Sends the "Hand Initialize" command to the hand.
int Reset (bool *responseReceived=0)
 Sends the "Reset" command to the hand.
int Close (const char *motor)
 Sends the "Close" supervisory command to the hand.
int Open (const char *motor)
 Sends the "Open" supervisory command to the hand.
int GoToDefault (const char *motor)
 Sends the "Goto Default" supervisory command to the hand.
int GoToDifferentPositions (int value1, int value2, int value3, int value4)
 Sends the "GoTo Different Position" supervisory command to the hand.
int GoToHome (const char *motor="")
 Sends the "GoTo Home" supervisory command to the hand.
int GoToPosition (const char *motor, int value)
 Sends the "GoTo Position" supervisory command to the hand.
int StepClose (const char *motor)
 Sends the "Step Close" supervisory command to the hand.
int StepClose (const char *motor, int stepAmount)
 Sends the "Step Close" supervisory command to the hand.
int StepOpen (const char *motor)
 Sends the "Step Open" supervisory command to the hand.
int StepOpen (const char *motor, int stepAmount)
 Sends the "Step Open" supervisory command to the hand.
int TorqueClose (const char *motor)
 Sends the "Torque Close" supervisory command to the hand.
int TorqueOpen (const char *motor)
 Sends the "Torque Open" supervisory command to the hand.
int Get (const char *motor, const char *propertyName, int *result)
 Sends the "Get" command to the hand.
int Set (const char *motor, const char *propertyName, int value)
 Sends the "Set" command to the hand.
int PGet (const char *propertyName, int *result)
 Sends the "PGet" command to the hand.
int PSet (const char *propertyName, int value)
 Sends the "PSet" command to the hand.
int Default (const char *motor)
 Sends the "Default" command to the hand.
int Load (const char *motor)
 Sends the "Load" command to the hand.
int Save (const char *motor)
 Sends the "Save" command to the hand.
int Temperature (int *result)
 Sends the "Temperature" request command to the hand.
int Command (const char *send, char *receive=0)
 Sends a command to the hand and is able to receive a response.
int Delay (unsigned int msec)
 Sends the "Delay" command to the hand.
int StopMotor (const char *motor)
 Sends the "Stop Motor" command to the hand.
int Baud (unsigned int baud)
 Sends "Baud" command to the Barrett Hand.
void setSyncMode (BHSyncMode syncMode)
BHSyncMode getSyncMode ()
void setRequestTimeout (unsigned int timeout)
unsigned int getRequestTimeout ()
void setpCallback (BHCallback funcPtr)
BHCallback getpCallback ()
int RTStart (const char *motor, BHMotorProtection motorProtection=BHMotorTSTOPProtect)
 Sends "Start" RealTime Mode Command to the Barrett Hand.
int RTUpdate (bool control=true, bool feedback=true)
 Sends "Update" RealTime Mode Command to the Barrett Hand.
int RTAbort ()
 Sends "Abort" RealTime Mode Command to the Barrett Hand.
int RTSetFlags (const char *motor, bool LCV, int LCVC, bool LCPG, bool LFV, int LFVC, bool LFS, bool LFAP, bool LFDP, int LFDPC)
 Sends "Set Flags" RealTime Mode Command to the Barrett Hand.
int RTSetFlags (const char *motor, bool LCV, int LCVC, bool LCPG, bool LCT, bool LFV, int LFVC, bool LFS, bool LFAP, bool LFDP, int LFDPC, bool LFBP, bool LFAIN, bool LFDPD, bool LFT)
 Sends "Set Flags" RealTime Mode Command to the Barrett Hand.
int RTUpdate (const char *motor, const char *property, int *values)
 This method will "Update" Puck properties while in RealTime Mode.
int RTSetVelocity (const char motor, int velocity)
 Sets RealTime control velocity reference for the desired motor.
int RTSetGain (const char motor, int gain)
 Sets RealTime control proportional gain for the desired motor.
int RTSetTorque (const char motor, int torque)
 Sets RealTime control torque for the desired motor.
int RTSetPosition (const char motor, int position)
 Sets RealTime position reference for the desired motor.
char RTGetVelocity (const char motor)
 Gets RealTime velocity feedback for the desired motor.
unsigned char RTGetStrain (const char motor)
 Gets RealTime strain gauge feedback for the desired motor.
int RTGetPosition (const char motor)
 Gets RealTime absolute position feedback for the desired motor.
char RTGetDeltaPos (const char motor)
 Gets RealTime delta position value feedback for the specified motor.
int RTGetBreakawayPosition (const char motor)
 Gets RealTime breakaway position feedback from the Barrett Hand.
int RTGetTemp ()
 Gets RealTime temperature feedback from the Barrett Hand.
unsigned char RTGetAIN (const char motor)
 Gets RealTime analog input feedback from the Barrett Hand.
void RTGetPPS (const char motor, int *pps, int ppsElements)

Data Fields

int syncMode
 This variable determines whether/how the user program waits for the low-level thread to complete the request before it continues.
unsigned int requestTimeout
 This variable specifies the timeout interval (in milliseconds) used in synchronous mode.
BHCallback pCallback
 This variable, if different from NULL, is a pointer to a function that will be called right before the low-level thread signals the user program that processing has finished.

Protected Member Functions

BHandgetBHand ()

Detailed Description

This class provides methods from Supervisory and RealTime modules.

This class provides an device independent way to access the Supervisory and RealTime modules in the BarrettHand. It must be initialized before most methods may be used. In addition there may be a serial communication module included if the API was compiled to support serial communication.

Definition at line 111 of file BHandSupervisoryRealTime.h.


Member Function Documentation

int BHandSupervisoryRealtime::InitSoftware ( int  port,
int  priority = THREAD_PRIORITY_TIME_CRITICAL 
)

Initialize this BHand instance.

The InitSoftware method will initialize communication with the BarrettHand. The BarrettHand API needs to have the Supervisory and RealTime modules initialized as well as having the means to communicate with the hand prior to using Supervisory or RealTime methods.

This method will initialize the Supervisory and RealTime modules given that the parameters are set correctly and serial communication with the hand is established. If this method successfully establishes communication with the hand then a low-level thread is started for executing high-level BarrettHand Supervisory commands. Both reset and init hand commands will also be issued.

Parameters:
port The comport to use for communication (1 for "COM1" in Windows or "/dev/ttyS0" in Linux)
priority The thread priority for the communication thread
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 98 of file BHandSupervisoryRealTime.cpp.

Here is the call graph for this function:

int BHandSupervisoryRealtime::Init ( int  port,
int  priority,
BHCommunication  comm,
bool  async = false 
)

Initialize this BHand instance.

This method will need to be called to initialize the hand for CAN or serial communication. Before Init is called, setHardwareDesc should be called to set the hardware description so that the API knows what hand it will be communicating with. This method will attempt to reset the hand and will report an error if there is a problem. Users may run initialize as a non-blocking call by passing true to the async parameter. This is for advanced applications that need to not block if there is a timeout or problem attempting to reset the hand. Note that all supervisory commands will be run asynchronously until the mode is switched.

Parameters:
port The comport to use for communication (1 for "COM1" in Windows or "/dev/ttyS0" in Linux)
priority The thread priority for the communication thread
async Will set the blocking/non-blocking behavior of Init, default value is false
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 132 of file BHandSupervisoryRealTime.cpp.

Referenced by InitSoftware().

Here is the call graph for this function:

int BHandSupervisoryRealtime::ComRequest ( int  requestNumber  ) 

Sends a request to the low-level communication thread.

The request must be BHREQ_EXIT, BHREQ_REALTIME, BHREQ_SUPERVISE, or BHREQ_CLEAR.

Parameters:
requestNumber One of the request constants listed above
Return values:
int Returns 0 on success or an error code on failure

Definition at line 363 of file BHandSupervisoryRealTime.cpp.

Here is the call graph for this function:

int BHandSupervisoryRealtime::ComWaitForCompletion ( unsigned int  timeout  ) 

Waits for low-level communication thread to complete processing.

Blocks until the communication thread completes processing in the given amount of time. It will return 0, a positive hand error code, or a negative timeout error code.

Parameters:
timeout Number of milliseconds to wait for completion (may be INFINITE)
Return values:
int Returns 0, a positive hand error code, or BHERR_TIMEOUT if there is a timeout

Definition at line 417 of file BHandSupervisoryRealTime.cpp.

Referenced by ComRequest().

bool BHandSupervisoryRealtime::ComIsPending (  ) 

Checks for a low-level pending communication request.

Return values:
bool Returns true if a communication request is pending and false otherwise

Definition at line 438 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::ComGetError (  ) 

Checks the low-level thread for communication errors.

Communication errors are set to zero before communication begins with the low-level thread and is set after completion to the value that would be returned by the Supervisory command if run synchronously. Use this to get the last error, which is the only method available to access the error code in asynchronous mode. Call this after ComIsPending() returns false or the application receives a callback on a method that the supervisory command has executed.

Return values:
int Returns the most recent communication error

Definition at line 455 of file BHandSupervisoryRealTime.cpp.

BHandSupervisoryResult * BHandSupervisoryRealtime::GetResult (  ) 

Obtain command results after the supervisory command has finished running.

The last command run should be a supervisory command that returns a result. Ensure that the command has finished running. Use ComIsPending() or received the finished command event through a callback method. Usually, a cast is needed to receive useful information from the result returned as appropriate.

Return values:
BHandSupervisoryResult Pointer to most recent result

Definition at line 469 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::InitHand ( const char *  motor  ) 

Sends the "Hand Initialize" command to the hand.

The purpose of this command is to determine encoder and motor alignment for commutation. It moves all fingers and spread to open positions.

Example:

  // Initializes all finger motors
  char motor[2] = "G";
  err = bh.InitHand(motor);

InitHand() needs to be called after the hand has been reset. This command must be run before any other motor commands, once the hand is turned on.

Parameters:
motor Specifies which motors to initialize
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 855 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::Reset ( bool *  responseReceived = 0  ) 

Sends the "Reset" command to the hand.

Resets the firmware loop in the BarrettHand and sets the baud rate to the default baud rate of 9600 bps unless it is set differently with the BHandSerialDriver::SetDefaultBaud method.

Example:

  // resets the hand
  err = bh.Reset();

After resetting the BarrettHand you will need to call InitHand() before issuing any motion commands.

Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 878 of file BHandSupervisoryRealTime.cpp.

Referenced by Command(), and Init().

int BHandSupervisoryRealtime::Close ( const char *  motor  ) 

Sends the "Close" supervisory command to the hand.

Commands the selected motor(s) to move finger(s) in the close direction with a velocity ramp-down to target limit, CT.

Example:

  // closes grasp
  char motor[4] = "123";
  err = bh.Close(motor);

Finger(s) close until the joint stop(s) are reached, the close target is reached, or an obstacle is encountered.

Parameters:
motor Specifies which motors will be closed
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 902 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::Open ( const char *  motor  ) 

Sends the "Open" supervisory command to the hand.

Commands the selected motor(s) to move finger(s) in the open direction with a velocity ramp-down at target limit, OT.

Example:

  // Opens the spread
  char motor[2] = "S";
  err = bh.Open(motor);

Finger(s) open until the open target is reached or an obstacle is encountered. The motor argument passed to the function needs to be a pointer to a string.

Parameters:
motor Specifies which motors will be opened
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 926 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::GoToDefault ( const char *  motor  ) 

Sends the "Goto Default" supervisory command to the hand.

Moves all motors to default positions defined by the default property DP.

Example:

  // move grasp to default positions
  char result;
  err = bh.GoToDefault(motor);

The motor argument passed to the function needs to be a pointer to a string.

Parameters:
motor Specifies which motors will be moved
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 948 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::GoToDifferentPositions ( int  value1,
int  value2,
int  value3,
int  value4 
)

Sends the "GoTo Different Position" supervisory command to the hand.

Moves all motors to specified encoder positions.

Example:

  // moves finger F1 to 2000, finger F2 to 3000, finger F3 to 4000, and spread
  to 1000
  err = bh.GoToDifferentPositions(2000, 3000, 4000, 1000);

Encoder positions will be validated before setting "DP" property and going to the desired encoder positions.

Parameters:
value1 Specifies the encoder position for motor 1
value2 Specifies the encoder position for motor 2
value3 Specifies the encoder position for motor 3
value4 Specifies the encoder position for motor 4
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 974 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::GoToHome ( const char *  motor = ""  ) 

Sends the "GoTo Home" supervisory command to the hand.

Moves the specified motors to position 0. If any fingers are sent home then all fingers will be sent home. Spread is sent home last and only if it is commanded to return to the home posiiton.

Example:

  // moves all motors to the home position
  err = bh.GoToHome();
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1008 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::GoToPosition ( const char *  motor,
int  value 
)

Sends the "GoTo Position" supervisory command to the hand.

Moves motors to specified encoder position.

Example:

  // moves finger F3 to position 10000
  char motor[2] = "3";
  err = bh.GoToPosition(motor, 10000);

Encoder position will be validated to be in the range of the "DP" property for each included motor.

Parameters:
motor Specifies which motors will be moved to the encoder position
value Specifies the encoder position to move to
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1032 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::StepClose ( const char *  motor  ) 

Sends the "Step Close" supervisory command to the hand.

Incrementally closes the specified motors. The property DS contains the default increment size that will be used.

Example:

  // step close finger F2 1500 encoder counts
  char motor[2] = "2";
  err = bh.StepClose(motor, 1500);
Parameters:
motor Specifies which motors will be closed
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1091 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::StepClose ( const char *  motor,
int  stepAmount 
)

Sends the "Step Close" supervisory command to the hand.

Incrementally closes the specified motors. The property DS contains the default increment size that will be used.

Example:

  // step close finger F2 1500 encoder counts
  char motor[2] = "2";
  err = bh.StepClose(motor, 1500);

Step size will be validated to be in the range of the "DS" property for each included motor.

Parameters:
motor Specifies which motors will be closed
stepAmount Specifies the step size amount in encoder ticks
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1064 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::StepOpen ( const char *  motor  ) 

Sends the "Step Open" supervisory command to the hand.

Incrementally opens the specified motors. The DS property contains the default increment size that will be used.

Example:

  // step open finger F2 by DP encoder counts
  char motor[2] = "2";
  err = bh.StepOpen(motor);
Parameters:
motor Specifies which motors will be opened
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1147 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::StepOpen ( const char *  motor,
int  stepAmount 
)

Sends the "Step Open" supervisory command to the hand.

Incrementally opens the specified motors. The property DS contains the default increment size that will be used.

Example:

  // step open the grasp 2000 encoder counts
  char motor[2] = "G";
  err = bh.StepOpen(motor, 2000);

Step size will be validated to be in the range of the "DS" property for each included motor.

Parameters:
motor Specifies which motors will be opened
stepAmount Specifies the step size amount in encoder ticks
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1119 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::TorqueClose ( const char *  motor  ) 

Sends the "Torque Close" supervisory command to the hand.

Commands velocity of selected motor(s) in the direction that closes the finger(s) with control of motor torque at stall.

Example:

  // closes grasp with torque control
  char motor[4] = "123";
  err = bh.TorqueClose(motor);
Parameters:
motor Specifies which motors will be closed with torque control
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1170 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::TorqueOpen ( const char *  motor  ) 

Sends the "Torque Open" supervisory command to the hand.

Commands velocity of selected motor(s) in the direction that opens the finger(s) with control of motor torque at stall.

Example:

  // opens grasp with torque control
  char motor[4] = "123";
  err = bh.TorqueOpen(motor);
Parameters:
motor Specifies which motors will be opened with torque control
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1191 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::Get ( const char *  motor,
const char *  propertyName,
int *  result 
)

Sends the "Get" command to the hand.

Gets motor properties.

Example:

  // gets the maximum close velocity for finger F1 and stores it in result
  char motor[2] = "1";
  char property[4] = "MCV";
  int result;
  err = bh.Get(motor, property, &result);

Refer to the BH8-Series User Manual or the BHControl GUI for a list of motor properties and their functions. Verify that the size of the result variable can hold all values returned. For example, if you request the values for motors F1, F2, and F3, make sure you pass a pointer to an array with at least 3 valid locations.

Parameters:
motor Specifies which motor's property to get
propertyName Specifies which motor property you want to get
result Specifies a pointer to where the result(s) will be stored
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1226 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::Set ( const char *  motor,
const char *  propertyName,
int  value 
)

Sends the "Set" command to the hand.

Sets motor properties.

Example:

  // set finger F1 maximum close velocity to 20
  char motor[2] = "1";
  char property[4] = "MCV";
  err = bh.Set(motor, property, 20);

Refer to the BH8-Series User Manual or the BHControl GUI for a list of motor properties and their functions. Set validates desired property value first.

Parameters:
motor Specifies which motor's properties to set
propertyName Specifies which motor property will be set
value Specifies the desired value of the property
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1262 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::PGet ( const char *  propertyName,
int *  result 
)

Sends the "PGet" command to the hand.

Gets the value of a global property.

Example:

  // get over temperature fault value
  char property[6] = "OTEMP";
  int result;
  err = bh.PGet(property, &result);

Refer to the BH8-Series User Manual or the BHControl GUI for a list of motor properties and their functions.

Parameters:
propertyName Specifies which global property to get
result Specifies a pointer to where the result will be stored
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1293 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::PSet ( const char *  propertyName,
int  value 
)

Sends the "PSet" command to the hand.

Sets the value of a global property.

Example:

  // set over temperature fault to 585 (58.5 degrees Celsius)
  char property[6] = "OTEMP";
  err = bh.PSet(property, 585);

Refer to the BH8-Series User Manual or the BHControl GUI for a list of motor properties and their functions. PSet validates desired property value first.

Parameters:
propertyName Specifies which global property will be set
value Specifies the desired value of the property
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1325 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::Default ( const char *  motor  ) 

Sends the "Default" command to the hand.

Loads factory default motor properties from EEPROM into active property list.

Example:

  // loads factory default properties for the grasp
  char motor[2] = "G";
  err = bh.Default(motor);

This command only changes the active properties, to write the properties to EEPROM use Save(). The motor argument passed to the function needs to be a pointer to a string.

Parameters:
motor Specifies which motor's default properties to load
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1355 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::Load ( const char *  motor  ) 

Sends the "Load" command to the hand.

Loads the saved motor properties from EEPROM into active property list.

Example:

  // loads previously saved properties for the grasp
  char motor[2] = "G";
  err = bh.Load(motor);

The motor argument passed to the function needs to be a pointer to a string. All of the settable firmware properties will be loaded into RAM.

Parameters:
motor Specifies which motor's properties to load
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1378 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::Save ( const char *  motor  ) 

Sends the "Save" command to the hand.

Saves present motor properties from the active properties list to EEPROM. These values can be loaded later. Storing the values in EEPROM allows you to reset the BarrettHand and retain preferred motor properties.

Example:

  // saves the grasp motor properties
  char motor[2] = "G";
  err = bh.Save(motor);

The properties can be recalled into the active properties list by using the function Load(). The motor argument passed to the function needs to be a pointer to a string. However, this command should not be performed more than 5,000 times or the Hand electronics may need repair.

Parameters:
motor Specifies which motor's properties to save
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1405 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::Temperature ( int *  result  ) 

Sends the "Temperature" request command to the hand.

Returns temperature from the BarrettHand. For the 262 hand, this is CPU temperature and for the 280 hand it is the maximum temperature read from any of the Pucks.

Example:

  // stores the temperature in result
  int result;
  err = bh.Temperature(&result);
Parameters:
result A pointer to where the temperature value will be stored (in degrees Celsius)
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1427 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::Command ( const char *  send,
char *  receive = 0 
)

Sends a command to the hand and is able to receive a response.

Send an ASCII character string to the BarrettHand. The hand is expected to respond in Supervisory mode. If the receive buffer is supplied, the function will copy the hand response into the buffer. If not and you are using serial, you can obtain the hand response using the command Response().

Example:

  // gets maximum close velocity of motor F3 and stores
  // the resultant string value in receive
  char command[10] = "3FGET MCV";
  char receive[10];
  err = bh.Command(command, receive);

This function can be used to implement a simple terminal control. The command argument passed to the function needs to be a pointer to a string. The receive buffer for the response must be allocated by the user and be large enough to hold the response for the sent command.

Parameters:
send String to send to the BarrettHand (any variation of letters and numbers)
receive Pointer to a buffer where the response will be stored
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1473 of file BHandSupervisoryRealTime.cpp.

Here is the call graph for this function:

int BHandSupervisoryRealtime::Delay ( unsigned int  msec  ) 

Sends the "Delay" command to the hand.

Insert a delay into sequence of commands.

Example:

  // Inserts a delay of 3 seconds
  unsigned int time = 3000;
  err = bh.Delay(time);
Parameters:
msec The desired delay in units of milliseconds
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1643 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::StopMotor ( const char *  motor  ) 

Sends the "Stop Motor" command to the hand.

Stops actuating motors specified.

Example:

  // stops actuating the spread motor
  char motor[2] = "S";
  err = bh.StopMotor(motor);

Use StopMotor() command, when possible, to reduce the amount of heat generated by the motor.

Parameters:
motor Specifies which motors will be terminated
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1673 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::Baud ( unsigned int  newbaud  ) 

Sends "Baud" command to the Barrett Hand.

Changes the baud rate of both the associated hand and the COM port on the host PC to the new value. The possible values are the standard baud rates up to 38400.

Example:

  // sets hand and serial port to 9600 baud
  unsigned int baudrate = 9600;
  err = bh.Baud(baudrate);

The baud rate of the hand is reset to the default baud rate by issuing the Reset() command. Baud rate can be saved between resets by executing the "PSAVE" command after the Baud command. Examples and demos work only with the hand starting up at 9600 bps so saving higher baud rates should only be done by experienced users.

Parameters:
newbaud The desired baud rate should be stored in this variable
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1730 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTStart ( const char *  motor,
BHMotorProtection  motorProtection = BHMotorTSTOPProtect 
)

Sends "Start" RealTime Mode Command to the Barrett Hand.

Call this function after desired loop mode properties have been set and you are ready to enter RealTime control. Only one active motor control mode may be active or RTStart may return an error (e.g. don't try to control motor torques and velocities at the same time).

Example:

  // Enter motor F2 into RealTime control
  char motor[2] = "2";
  err = bh.RTStart(motor);

The motor argument passed to the function needs to be a pointer to a string. Motor protection is an optional argument that is used to set the desired motor protection level for the 280 hand only. The default value is BHMotorTSTOPProtect. This will protect motors from overheating and damage if a motor comes to a stop after TSTOP milliseconds. The motor mode will be returned to idle mode to protect the motor so RTAbort and RTStart will need to be called again to regain control of the stopped motor(s). Another option available is to set the motorProtection argument to BHMotorTorqueLimitProtect. This will limit the maximum torque to motors to a safe amount during RTUpdate calls. It is important that RTUpdate is called frequently or a stalled motor may not have its torque limited. If a user program is not calling RTUpdate then motors may overheat and be damaged.

Parameters:
motor Determines which motors will be controlled in RealTime
motorProtection See above for detailed description
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1774 of file BHandSupervisoryRealTime.cpp.

Referenced by Command().

int BHandSupervisoryRealtime::RTUpdate ( bool  control = true,
bool  feedback = true 
)

Sends "Update" RealTime Mode Command to the Barrett Hand.

This command is used to trigger the sending and receiving of data between the host PC and the Hand.

Example:

  // Set Velocity to 30 and read position for motor 2, stop when position > 3000
  char motor[2] = "2";
  char parameter[2] = "P";
  int pos[1];

  err = bh.RTSetFlags(motor, TRUE, 1, FALSE, FALSE, 1,
        FALSE, TRUE, FALSE, 1, TRUE, FALSE);
  err = bh.Get(motor, parameter, pos);
  err = bh.RTStart(motor);

  while (pos[1] < 3000)
  {
     err = bh.RTSetVelocity(`2`, 30);
     err = bh.RTUpdate(TRUE, TRUE);
     pos = bh.RTGetPosition(`2`);
  }
Parameters:
control Indicates if control data should be sent
feedback Indicates if feedback data should be received
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1809 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTAbort (  ) 

Sends "Abort" RealTime Mode Command to the Barrett Hand.

Ends RealTime mode and returns to Supervisory mode.

Example:

  // Ends RealTime control
  err = bh.RTAbort();
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1827 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTSetFlags ( const char *  motor,
bool  LCV,
int  LCVC,
bool  LCPG,
bool  LFV,
int  LFVC,
bool  LFS,
bool  LFAP,
bool  LFDP,
int  LFDPC 
)

Sends "Set Flags" RealTime Mode Command to the Barrett Hand.

Sets the nine of the parameters relevant for RealTime mode, for the specified motors. See BH8-Series User Manual for a list of relevant RealTime Parameters and their functions.

Example:

  // Prepares flags and variables to send control velocity
  // and receive absolute position to/from motor F2
  bool control_velocity_flag = TRUE,
       control_propgain_flag = FALSE,
       feedback_velocity_flag = FALSE,
       feedback_strain_flag = FALSE,
       feedback_position_flag = TRUE,
       feedback_deltapos_flag = FALSE;

  int control_velocity_coefficient = 1;
  int feedback_velocity_coefficient = 1;
  int feedback_delta_position_coefficient = 1;

  char motor[2] = "2";

  err = bh.RTSetFlags(motor,
                      control_velocity_flag, control_velocity_coefficient, control_propgain_flag,
                      feedback_velocity_flag, feedback_velocity_coefficient, feedback_strain_flag,
                      feedback_position_flag, feedback_deltapos_flag, feedback_delta_position_coefficient);

This function is provided for convenience, the same effect can be achieved with multiple calls to the Set() function. However, RTSetFlags can only define some of the parameters that can be defined with Set(). The motor argument passed to the function needs to be a pointer to a string.

Parameters:
motor Determines which motor parameters will be set
LCV Loop Control Velocity Flag
LCVC Loop Control Velocity Coefficient
LCPG Loop Control Proportional Gain Flag
LFV Loop Feedback Velocity Flag
LFVC Loop Feedback Velocity Coefficient
LFS Loop Feedback Stain Flag
LFAP Loop Feedback Absolute Position Flag
LFDP Loop Feedback Delta Position Flag
LFDPC Loop Feedback Delta Position Coefficient
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1916 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTSetFlags ( const char *  motor,
bool  LCV,
int  LCVC,
bool  LCPG,
bool  LCT,
bool  LFV,
int  LFVC,
bool  LFS,
bool  LFAP,
bool  LFDP,
int  LFDPC,
bool  LFBP,
bool  LFAIN,
bool  LFDPD,
bool  LFT 
)

Sends "Set Flags" RealTime Mode Command to the Barrett Hand.

Sets the fourteen of the parameters relevant for RealTime mode, for the specified motors. See BH8-Series User Manual for a list of relevant RealTime Parameters and their functions.

Example:

  // Prepares flags and variables to send control velocity
  // and receive absolute position and temperature to/from motor F2
  bool control_velocity_flag = TRUE,
       control_propgain_flag = FALSE,
       control_torque_flag = FALSE,
       feedback_velocity_flag = FALSE,
       feedback_strain_flag = FALSE,
       feedback_position_flag = TRUE,
       feedback_deltapos_flag = FALSE,
       feedback_breakaway_position_flag = FALSE,
       feedback_analog_input_flag = FALSE,
       feedback_delta_position_discard_flag = FALSE,
       feedback_temperature = TRUE;

  int control_velocity_coefficient = 1;
  int feedback_velocity_coefficient = 1;
  int feedback_delta_position_coefficient = 1;

  char motor[2] = "2";

  err = bh.RTSetFlags(motor,
                      control_velocity_flag, control_velocity_coefficient, control_propgain_flag, control_torque_flag,
                      feedback_velocity_flag, feedback_velocity_coefficient, feedback_strain_flag,
                      feedback_position_flag, feedback_deltapos_flag, feedback_delta_position_coefficient,
                      feedback_breakaway_position_flag, feedback_analog_input_flag, feedback_delta_position_discard_flag, feedback_temperature);

This function is provided for convenience, the same effect can be achieved with multiple calls to the Set() function. However, RTSetFlags can only define some of the parameters that can be defined with Set(). The motor argument passed to the function needs to be a pointer to a string.

Parameters:
motor Determines which motor parameters will be set
LCV Loop Control Velocity Flag
LCVC Loop Control Velocity Coefficient
LCPG Loop Control Proportional Gain Flag
LCT Loop Control Torque Flag
LFV Loop Feedback Velocity Flag
LFVC Loop Feedback Velocity Coefficient
LFS Loop Feedback Stain Flag
LFAP Loop Feedback Absolute Position Flag
LFDP Loop Feedback Delta Position Flag
LFDPC Loop Feedback Delta Position Coefficient
LFBP Loop Feedback Breakaway Position Flag
LFAIN Loop Feedback Analog Input Flag
LFDPD Loop Feedback Delta Position Discard Flag
LFT Loop Feedback Temperature Flag
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1995 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTUpdate ( const char *  motor,
const char *  property,
int *  values 
)

This method will "Update" Puck properties while in RealTime Mode.

This command will efficiently request property values from the given Pucks and wait until the properties have been read and stored in the array passed to this method. It is provided to be able to read properties in between calls to RTUpdate(bool, bool).

Example:

  // Set Velocity to 30 and read position for motor F2, stop when position > 3000
  char motors[2] = "G";
  char prop[] = "JP";
  int jointPositions[4]; // must be of the number of motors in the hand

  ...

  while (1)
  {
     ...
     err = bh.RTUpdate(TRUE, TRUE);
     err = bh.RTUpdate(motors, prop, jointPositions);
  }

The size of the array passed into this method must be equal to the number of motors in the hand. Ensure that the array is large enough to hold values for each motor of the hand even if not all motor property values are read.

Parameters:
motor Determines which motor properties to retrieve in RealTime mode
property The name of the Puck 2 property
values Pointer to an array that will contain retrieved results
Return values:
int Returns 0 on success and a BHERR error code on failure

Definition at line 1865 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTSetVelocity ( const char  motor,
int  velocity 
)

Sets RealTime control velocity reference for the desired motor.

Example:

  // Set control velocity references for motors F1, F2, and F3 to 50
  err = bh.RTSetVelocity(`1`, 50);
  err = bh.RTSetVelocity(`2`, 50);
  err = bh.RTSetVelocity(`3`, 50);

The loop control velocity (LCV) flag must be set to send velocity references to the hand.

BH8-280 Puck motor controllers implement velocity mode on top of a position controller updated at a kilohertz. Velocity references in units of encoder ticks/ms are added to the present commanded position each servo cycle. KP, KI, and KD affect both position and velocity PID gains.

BH8-262 motor controllers responds by applying motor torque according to the following equation in the HCTL-1100 datasheet:

MCn = (K/4) * Yn

Where K depends on the loop control proportional gain (LCPG) flag. If LCPG is set then K is set with RTSetGain, otherwise K is equal to the value of the "FPG" property. Yn is the velocity error and equals:

Loop Control Velocity Reference * Loop Control Velocity Coefficient - Actual Velocity

In proportional velocity control mode, the HCTL-1100 tries to match the desired motor control reference velocities by applying motor torques proportional to the velocity error. The proportional gain "K" may be set at runtime. The actual velocity is in units of encoder ticks per 10 milliseconds.

The motor will not actually be sent this control velocity reference until RTUpdate() is called. Only one motor velocity reference can be set at a time.

Parameters:
motor Determines which motor velocity reference will be set
velocity Desired control velocity for the specified motor
Return values:
int Returns 0 on success and BHERR_MOTORINACTIVE if motor is inactive

Definition at line 2231 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTSetGain ( const char  motor,
int  gain 
)

Sets RealTime control proportional gain for the desired motor.

Example:

  // Set gain parameters of motors 1 and 2 to 150
  err = bh.RTSetGain(`1`, 150);
  err = bh.RTSetGain(`2`, 150);

This method should only be used for the BH8-262 hand.

The loop control proportional gain (LCPG) flags must be set to send proportional gains to the hand. The gains for the motors will not actually be set until RTUpdate() is called. In RealTime control, the motors are controlled using a proportional velocity mode. The proportional gain affects the motor command according to the Velocity Control equations. See RTSetVelocity method for more information.

Parameters:
motor Determines which motor gain will be set
gain Desired proportional gain for the specified motor
Return values:
int Returns 0 on success and BHERR_MOTORINACTIVE if motor is inactive

Definition at line 2292 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTSetTorque ( const char  motor,
int  torque 
)

Sets RealTime control torque for the desired motor.

Example:

  // Set control torque parameters of motors F1, F2, and F3 to 50
  err = bh.RTSetTorque(`1`, 50);
  err = bh.RTSetTorque(`2`, 50);
  err = bh.RTSetTorque(`3`, 50);

The loop control torque (LCT) flag needs to be set to send 16-bit torque references to the hand.

BH8-262 motor torque references will be used in position mode to apply motor torques. The desired motor torque will be added to the present motor encoder position and be submitted as the commanded position.

The BH8-280 will control motor currents directly by using the desired torque reference.

The motor will not actually be set to this control torque until RTUpdate() is called. Only one motor control torque can be set at a time.

Parameters:
motor Determines which motor torque will be set
torque Desired control velocity for the specified motor
Return values:
int Returns 0 on success and BHERR_MOTORINACTIVE if motor is inactive

Definition at line 2264 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTSetPosition ( const char  motor,
int  position 
)

Sets RealTime position reference for the desired motor.

Example:

  // Set positions of F3 and spread to be in the center position
  err = bh.RTSetPosition(`3`, -100000);
  err = bh.RTSetPosition(`S`, -18000);

RealTime position control is only possible with the 280 hand.

The loop control position (LCP) flag needs to be set to send desired position references to the hand. The new reference positions will not actually be set until RTUpdate() is called. Only one motor control position reference can be set at a time.

Parameters:
motor Determines which motor position will be set
position Desired position for the specified motor
Return values:
int Returns 0 on success and BHERR_MOTORINACTIVE if motor is inactive

Definition at line 2318 of file BHandSupervisoryRealTime.cpp.

char BHandSupervisoryRealtime::RTGetVelocity ( const char  motor  ) 

Gets RealTime velocity feedback for the desired motor.

Example:

  // Get velocity feedback of motor F1
  char velocity = bh.RTGetVelocity(`1`);

BH8-262 velocity feedback is divided by the loop feedback velocity coefficient (LFVC) before it is sent by the hand. This value can be set with the RTSetFlags method. The returned velocity units are encoder ticks per 10 milliseconds and will be scaled accordingly with a LFVC greater than 1.

BH8-280 velocity feedback is in encoder ticks per millisecond. Velocity feedback with this method will be clipped to limit the range to be from -127 to 127.

The loop feedback velocity (LFV) flag must be set to receive velocity feedback. Only one motor velocity can be retrieved at a time.

Parameters:
motor Determines which motor velocity will be retrieved
Return values:
int Returns the velocity for the specified motor

Definition at line 2027 of file BHandSupervisoryRealTime.cpp.

unsigned char BHandSupervisoryRealtime::RTGetStrain ( const char  motor  ) 

Gets RealTime strain gauge feedback for the desired motor.

Example:

  // Gets strain gauge value for motor 3
  unsigned char strain = bh.RTGetStrain(`3`);

This method may only return 8-bit values so it will scale strain readings to be from 0 to 255. Better resolution can be achieved for BH8-280 users by calling RTUpdate with the "SG" property name passed as a parameter.

The loop feedback strain (LFS) flag must be set to receive strain gauge feedback if using just the RTUpdate(bool, bool) method. Only one motor strain gauge reading can be retrieved at a time.

Parameters:
motor Determines which finger strain gauge values will be retrieved
Return values:
unsigned char Returns the strain gauge value for the specified motor

Definition at line 2052 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTGetPosition ( const char  motor  ) 

Gets RealTime absolute position feedback for the desired motor.

Example:

  // Gets absolute position for motor 1
  unsigned char position = bh.RTGetPosition(`1`);

The loop feedback absolute position (LFAP) flag must be set to receive absolute position feedback. The hand also needs to be intialized with the HI command. Only one motor position can be retrieved at a time.

Parameters:
motor Determines which motor's absolute position will be retrieved
Return values:
int Returns the absolute position of the motor

Definition at line 2073 of file BHandSupervisoryRealTime.cpp.

char BHandSupervisoryRealtime::RTGetDeltaPos ( const char  motor  ) 

Gets RealTime delta position value feedback for the specified motor.

Example:

  // Get delta position value for finger F1
  int deltaposition1 = bh.RTGetDeltaPos(`1`);

The loop feedback delta position (LFDP) flag must be set to receive delta position feedback. Delta position is the change in position from the last reported position and is limited to one signed byte. The present position is read and compared to the last reported position. The difference is divided by the RealTime variable LFDPC, clipped to a single signed byte, and then sent to the host. The value sent to the host should then be multiplied by LFDPC and added to the last reported position.

Example (with LFDPC set to 2): What will delta position feedback look like if last reported position was 1500 and the position jumps to 2000? The first feedback block will include the delta position value 127. This value should be multiplied by LFDPC on the host machine resulting in 254. The hand will internally update the reported position to 1754. The next feedback block will include the delta position 123, which should be multiplied by LFDPC resulting in 246. The reported position will be updated to 2000. Subsequent feedback blocks will include the delta position value 0 (until the next position change).

Delta position feedback is only implemented on the BH8-262 hand in order to increase the servo rate. Only one motor delta position can be retrieved at a time.

Parameters:
motor Determines which motor's delta position value will be retrieved
Return values:
char Returns the delta position value for the specified motor

Definition at line 2153 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTGetBreakawayPosition ( const char  motor  ) 

Gets RealTime breakaway position feedback from the Barrett Hand.

Example: Get breakaway position of finger 1 int bp = bh.RTGetBreakawayPosition(`1`);

The loop feedback breakaway position flag must be set to receive the breakaway positions. Open, toque open, and hand initialize commands will reset the breakaway detected (BD) flag and clear the breakaway position (BP). Initialization hit count (IHIT) is used to get a consistent origin for finger motors and thus a consistent breakaway force. Initialization Offset affects the force required to cause breakaway. Properties that affect the breakaway position are the breakaway detection acceleration threshold (BDAT). Breakaway stop (BS) flag is used to stop a finger motor as soon as breakaway is detected. The user is refered to the BH8-262 user manual for information concerning breakaway. Only one motor breakaway position can be retrieved at a time.

Definition at line 2178 of file BHandSupervisoryRealTime.cpp.

int BHandSupervisoryRealtime::RTGetTemp (  ) 

Gets RealTime temperature feedback from the Barrett Hand.

Example:

  // Get temperature
  int handtemperature = bh.RTGetTemp();

The global loop feedback temperature (LFT) flag must be set to receive temperature feedback. BH8-262 temperature is returned as stated in the user manual. BH8-280 temperature will return the maximum of the present TEMP readings from the Pucks.

Return values:
int Returns the temperature value

Definition at line 2094 of file BHandSupervisoryRealTime.cpp.

unsigned char BHandSupervisoryRealtime::RTGetAIN ( const char  motor  ) 

Gets RealTime analog input feedback from the Barrett Hand.

Example:

  // Get analog input value for finger F1
  int analog1 = bh.RTGetAIN(`1`);

The loop feedback analog input (LFAIN) flag must be set to receive analog input feedback. This is will only work on the BH8-262 hand.

Parameters:
motor Determines which motor's analog value will be retrieved
Return values:
unsigned char Returns the analog input value for the specified motor

Definition at line 2114 of file BHandSupervisoryRealTime.cpp.


Field Documentation

This variable determines whether/how the user program waits for the low-level thread to complete the request before it continues.

Values:

  • BHMODE_SYNC: User program waits for completion of low-level thread.
  • BHMODE_ASYNCNOW: Try to send request now (error if another request is being processed), do not wait for completion.
  • BHMODE_ASYNCWAIT: Wait for completion of previous request, then send request and return immediately
  • BHMODE_RETURN: Send only requests for parameters (Temperature or Get commands), disregard all other requests, run the callback function and return.

Default: BHMODE_SYNCH

Notes: Setting the variable to asynchronous mode allows you to continue program execution while the request is still being processed.

Do not use asynchronous mode when a result is to be returned.

Definition at line 325 of file BHandSupervisoryRealTime.h.

Referenced by ComRequest().

This variable specifies the timeout interval (in milliseconds) used in synchronous mode.

Values: position integers

Default: INFINITE

Notes: INFINITE specifies that the user program does not resume until the low-level thread is finished processing the present request

Definition at line 336 of file BHandSupervisoryRealTime.h.

Referenced by ComRequest().

This variable, if different from NULL, is a pointer to a function that will be called right before the low-level thread signals the user program that processing has finished.

Values: any function

Default: NULL

Notes: The function will be executed with high priority so it should not be computationally intensive. The callback function types is: typedef void (*BHCallback)(class BHand*). Following is an example:

      void RealTimeCallbackFunction(BHand *nopotr)
      {
        // Insert code to be executed here
      }

In your main() function use the following assignment:

      pCallBack = RealTimeCallbackFunction;

Definition at line 366 of file BHandSupervisoryRealTime.h.

Referenced by ComRequest().


Generated on Tue Dec 28 20:59:19 2010 for Barrett Hand API by  doxygen 1.6.1