BarrettHand BH8-280 Supervisory Control Mode

An application designed to run and create Supervisory programs, that all users should become familiar with, is the BarrettHand Control GUI. Sequences of most commands may be formed though intuitive input controls, may be added to an execution buffer, and run with the click of a button. Standalone cross-platform compatible C++ programs can be generated with a Makefile that run sequences of Supervisory commands. The electronics and the means of communication in the BH8-SERIES BarrettHands are different as described in Section 9.1. The BH8-280 hand is the newest hand in the BH8-series and has Section 5.6 dedicated documenting how Supervisory mode is used. The following sections pertain to earlier models of the hand and explain the low-level serial protocol.

Overview

An overview of serial protocol for the BH8-262 hand and earlier hands is developed in this first section that forms the structure for all Supervisory mode commands. The hand will send company and product information about the hand on power up followed by a command prompt when the hand is ready. Supervisory commands are executed sequentially, desired commands are initiated by the host, and the hand responds to all commands appropriately with any error message followed by a prompt for the next command.

Commands

When the BarrettHand™ firmware is ready to process a command, it prints a prompt of "=> " to the host computer. A command can then be entered as a single line, terminated by a carriage return character (0x0d). Once the firmware receives the carriage return, it processes the line, executes the command, prints any error result, and then prints a new prompt. Once a command has been started, no configuration changes can be made until the command has completed or has been aborted.

Many of the commands take one or more parameters; space characters should separate these from the command and each other.

Motor commands

Motor commands act on one or more of the four hand motors. By default, all four motors are affected. To select fewer than four motors, a motor prefix must be placed before the command (with no space between the prefix and the command). A motor prefix consists of one or more of the following characters: Table 2 - Motor Prefixes

ValueMotor
1Finger F1
2Finger F2
3Finger F3
4Spread
GFinger F1, Finger F2, Finger F3
SSpread
<No Motor Specified>Finger F1, Finger F2, Finger F3, Spread (see the Firmware EN property in Section 5.3.4)

Examples:

"12<command>" executes the given command on fingers 1 and 2 "3S<command>" executes the given command on finger 3 and the spread "<command>" executes the given command on all fingers and the spread

Status Codes

When a Supervisory mode command encounters an error or unexpected result, the command is terminated, a status code is printed, and then a new prompt is printed to the host PC. The status code is in the format "ERR <value>", where <value> is the sum of the status codes encountered. Note that the status codes are powers of 2 so that the sum may be decomposed into the individual status codes. Table 3 - Hand Status Codes

Hand Status CodeDescription
1No motor board found
2No motor found
4Motor not initialized
8(not used)
16Couldn't reach position
32Unknown command
64Unknown parameter name
128Invalid value
256Tried to write a read only property
512(not used)
1024Too many arguments for this command
2048Invalid RealTime control block header
4096Command can't have motor prefix
8192Overtemperature fault tripped
16384Cntl-C abort command received

Command List

Supervisory mode commands are organized into the following five (5) categories:

  • Movement
  • Motor properties
  • Global properties
  • Administrative
  • Advanced

Movement Commands

Movement commands are motor commands: they immediately affect one or more of the motors. Each can take motor prefixes.

CommandNamePurposeArgumentsExampleNotes
CCloseCommands the selected motor(s) to move fingers in close direction with a velocity ramp-down at target limit. If selected, each finger moves towards the palm, and the spread motor moves so that fingers F1 and F2 are adjacent to finger F3.(none)SCThe C command is similar to a MOVE command, with the value of the Close Target (CT) motor property as the destination. However, unlike the Move command, the C command will not return an ERR32 if it does not reach CT within the maximum position error (MPE) property.
HIHand InitializeInitializes the selected motor controller(s), preparing them for use by other movement commands.(none)HIHI must be run before any other movement command. Generally it is run without a motor prefix, initializing all four motors; although, if desired, a subset of the motors can be specified. After an HI, all motors are in their home position; at 0 encoder counts.
HOMEHomeMoves the selected motor(s) to position 0.(none)SGHOME
IOIncremental OpenOpens the selected motor(s) the given number of counts. If no argument, then the amount to open is specified by value(s) the DS property.Distance to move (0 to 20000) (optional)12IO 5000
ICIncremental CloseCloses the selected motor(s) the given number of counts. If no argument, then the amount to close is specified by the value(s) DS property.Distance to move (0 to 20000) (optional)GIC 5000
LOOPLoopEnters RealTime mode. (none) LOOPSee Section 6 for more information on RealTime mode.
MMoveMoves the selected motor(s) to the given position. If no argument specified, then the motor(s) will move to the position(s) given by DP motor property.Position (0 to 20000) (optional)13M 1000
OOpenCommands the selected motor(s) to move fingers in open direction with a velocity ramp-down at target limits. If selected, F1, F2, and F3 open away from the palm, and the spread motor moves so that fingers F1 and F2 are opposite finger F3.(none)GOThe O command is similar to a MOVE command, with the value of the OT motor property as the destination. However, unlike the Move command, the O command will not return an ERR32 if it does not reach OT within the maximum position error (MPE) property. This command will reset the breakaway detected flag, BD.
TTerminate powerTurns the selected motor(s)'s power off.(none)STAlthough T will return an "ERR 1" if any of the selected motor(s) isn't initialized; it will still turn the selected and initialized motor(s)'s power off.
TCTorque-Controlled CloseCommands velocity of selected motor(s) in the direction that closes the finger(s) with control of motor torque at stall. (none)STC
TOTorque-Controlled OpenCommands velocity of selected motor(s) in the direction that opens the finger(s) with control of motor torque at stall. (none)STO

Motor Property Commands

Motor property commands act on the configuration properties for one or more of the motors. All except FLIST can take motor prefixes. See section 5.3 for a complete list of motor properties.

CommandNamePurposeArgumentsExampleNotes
FSETFinger SetSets the to the given value(s) for one or more motor properties<propertyName> <propertyValue> SFSET DS 100 DP 1500You can set more than one property by listing more than one propertyName/propertyValue pair.
FGETFinger GetGets and prints the property value(s) for the selected motor(s). Each property has its value(s) printed on one line, with one value for each selected motor separated by spaces.<propertyName> SFGET DS DPMore than one property name may be added.
FLOADFinger LoadLoads the selected motor(s)'s properties from non-volatile storage. This is done whenever the firmware starts up.(none) 3FLOADThe non-volatile storage used does not depend on the super capacitor, so it retains its value even if the firmware is lost.
FSAVEFinger SaveSaves the selected motor(s)'s properties to non-volatile storage.(none) 123FSAVEThe non-volatile storage used does not depend on the super capacitor, so it retains its value even if the firmware is lost. However, this command should not be performed more than 5,000 times or the hand electronics may need repair.
FDEFFinger DefaultSets the selected motor(s)'s properties back to their factory default values. (none) SFDEFDoes not save the changed values to non-volatile storage.
FLISTFinger ListLists all of the standard motor properties and their descriptions.(none) FLISTDoes not take a motor prefix.
FLISTVFinger List ValueLists the motor-property values for the selected motor(s). Each property has its value(s) printed on one line, with one value for each selected motor separated by spaces.(none) 3FLISTV

Global Property Commands

Global property commands configure the hand as a whole, without referencing a particular finger or motor. Except for not taking a motor prefix they are identical to the set of motor property commands. See section 5.4 for a complete list of global properties.

CommandNamePurposeArgumentsExampleNotes
PSETProperty SetSets one or more properties to the given value(s)<propertyName> <propertyValue> PSET OTEMP 60 More than one property may be set be listing more than one propertyName/propertyValue pair.
PGETProperty GetGets and prints one or more given property value(s). Each property has its value(s) printed on one line.<propertyName> PGET TEMP UPSECSGet more than one property value by listing more than one property name.
PLOADProperty LoadLoads the global properties from non-volatile storage. This is done whenever the firmware starts up.(none) PLOADThe non-volatile storage used does not depend on the super capacitor, so it retains its value even if the firmware is lost.
PSAVEProperty SaveSaves the global properties to non-volatile storage.(none) PSAVEThe non-volatile storage used does not depend on the super capacitor, so it retains its value even if the firmware is lost. However, this command should not be performed more than 5,000 times or the Hand electronics may need repair.
PDEFProperty DefaultSets the writable global properties to their default values. (none) PDEFDoes not save the changed values to non-volatile storage.
PLISTProperty ListLists all of the standard global properties and their descriptions.(none) PLIST
PLISTVProperty List ValueLists all of the standard global properties' values. Each property has its value(s) printed on one line.(none) PLISTV

Administrative Commands

Administrative commands implement various housekeeping functions.

CommandNamePurposeArgumentsExampleNotes
?HelpLists all of the standard commands. If immediately followed by a command name, then it lists the command name and its description.<commandName> ?HIThere must be no space between "?" and any command name.
RESETResetResets the hand software. Equivalent to doing a power cycle.(none) RESET
ERRErrorIf given an argument, lists the errors represented by that argument. If not given an argument, lists all possible error values and descriptions.<errorNum> ERR 3
VERSVersionPrints the firmware version.(none) VERS

Advanced Commands

Users do not generally need these commands and should avoid using them. They are not listed by the “?" command; they are only listed by the "A?" command.

CommandNamePurposeArgumentsExampleNotes
A?Help AllLists all of the standard and advanced commands.(none) A?Use the ? command to get a description of an advanced command.
FLISTAFinger List AllLists all of the standard and advanced finger property names.(none) FLISTA
FLISTAVFinger List All ValueLists all of the standard and advanced motor property values for the selected motor(s). Each property has its value(s) printed on one line, with one value for each selected motor separated by spaces.(none) 3FLISTAVCan take a motor prefix.
PLISTAProperty List AllLists all of the standard and advanced global property names.(none) PLISTA
PLISTAVProperty List All ValueLists all of the standard and advanced global property values. Each property has its value printed on one line.(none) PLISTAV

Motor Properties

Motor properties are used to determine or retrieve motor-related settings.

Movement

Movement properties affect how a given motor moves.

PropertyNamePurposeValuesDefaultNotes
BDAT Breakaway Detection Acceleration ThresholdUsed to adjust the breakaway detection accuracy0 to 20000 Finger: 1500; Spread: N/AUnits of BDAT are: Encoder counts/(Ticklet2). There are 307 ticklets per millisecond.
BS Breakaway StopUsed to stop finger as soon as breakaway has been detected.0 or 1Finger: 0 Spread: N/AWhen set to 1, the finger motor will stop when breakaway is detected.
DP Default PositionDestination of M command if no argument specified0 to 65,535 Finger: 8500 Spread: 1575 While DP can be set as high as 65,535, its true range of useful values is bounded by the joint limits of the axes (e.g. approximately 0 to 18,000 for fingers and approximately 0 to 3150 for spread).
DS Default StepSize of IC or IO command movement if no argument specified0 to 65,535 Finger: 1700 Spread: 315While DS can be set as high as 65,535, its true range of useful values is bounded by the joint limits of the axes (e.g. approximately 0 to 18,000 for fingers and approximately 0 to 3150 for spread).
HSG Highest Strain Gauge ValueIn O, C, IO, IC, M, TO, TC, and HOME commands, a motor's motion is terminated if its strain gauge value exceeds HSG.0 to 256 256 This command is an alias for MSG. When writing new code, it is recommended to use this command instead of MSG. A value of 255 or 256 disables the strain gage checking during motion commands.
LSG Lowest Strain Gauge ValueIn O, C, IO, IC, M, TO, TC, and HOME commands, a motor's motion is terminated if its strain gauge value falls below LSG.0 to 256 256A value of 255 or 256 disables the strain gage checking during motion commands.
MOV Maximum Open VelocityControls the maximum velocity while opening a motor.16 to 4080Finger: 100 Spread: 60
MCV Maximum Close VelocityControls the maximum velocity while closing a motor.16 to 4080Finger: 100 Spread: 60
MSG Maximum Strain GaugeIn O, C, IO, IC, M, TO, TC, and HOME commands, a motor's motion is terminated if its strain gauge value exceeds MSG.0 to 256 256 HSG is the preferred alias to MSG. When possible, please use HSG in place of MSG. A value of 255 or 256 disables the strain gage checking during motion commands.

Status

Motor status properties are read-only and give useful motor information and feedback.

PropertyNamePurposeValuesDefaultNotes
BD Breakaway-Detected FlagTo determine if breakaway has occurred0 or 1N/AFlag is set when a breakaway is detected. Flag is cleared after an O, TO, or HI command.
BPBreakaway PositionStores position of last breakaway0 or 20000N/AStored position of location of last breakaway. Position is cleared after an O, TO, or HI.
OD OdometerThe total number of counts traveled by the selected motor, divided by 1000.0 to 4 billion N/AThis value is never reset; it is maintained through power failures and firmware downloads.
P PositionThe present position of the motor.Finger: 0 to approximately 17,800 Spread: 0 to approximately 3150N/AThe range of the position property is dependent on the values of the OT (open target) and the CT (close target) properties. If these properties are set beyond the joint stops then the joint stops themselves will dictate the range of position values, in which case the ranges may differ slightly from finger to finger.
S StatusThe present status of the motor. 0 if ready to be used, or a status code otherwise.0, 1, 2, 4,…8192, 16384 and sums of theseN/A See status codes in section 5.1.3.
SG Strain GaugeThe present strain gage value for the motor.0 to 255 N/AReturns 255 if there is no strain gauge.

RealTime

RealTime properties affect exchange of control and feedback data for motors in RealTime mode. See Section 6 for more information on RealTime mode.

LCV Loop Control VelocityIf non-zero, then a velocity byte will be sent in the control block for the motor.0, 1 1
LCVC Loop Control Velocity CoefficientWhen the firmware receives a velocity byte in a control block, it multiplies the value by the value of LCVC before passing it to the affected motor.0 to 2551
LCPG Loop Control Proportional GainIf non-zero, then a Proportional Gain byte will be sent in the control block for the motor.0, 1 1This controls the constant that is multiplied by the velocity error in order to produce the motor torque.
LCT Loop Control TorqueIf non-zero, then a signed 2-byte torque will be sent in the control block for the motor.0, 1 0Motor torque is set using position mode by setting the commanded position reference equal to the actual position plus the desired torque value.
LFAIN Loop Feedback Analog InputIf non-zero, then a 1-byte unsigned analog value will be sent in the control block for the motor.0, 1 0
LFBP Loop Feedback Breakaway PositionIf non-zero, then the firmware sends two unsigned bytes giving the most recently recorded breakaway position for the motor.0, 1 0
LFV Loop Feedback VelocityIf non-zero, then the firmware sends a signed byte giving the present velocity for the motor divided by the LFVC property.0, 1 1
LFVC Loop Feedback Velocity CoefficientBefore sending a Loop Feedback Velocity byte, the firmware divides the velocity by this property's value.0 to 255 1
LFS Loop Feedback StrainIf non-zero, then the firmware sends an unsigned byte giving the strain gauge value for the motor.0, 1 1
LFAP Loop Feedback Absolute PositionIf non-zero, then the firmware sends an unsigned two-byte value giving the present position of the motor.0, 1 1
LFDP Loop Feedback Delta PositionIf non-zero, then the firmware sends a signed byte giving the change in position since the last datum, divided by the value of the LFDPC property.0, 1 1A conflict occurs when the change in position is too great to transmit in a single signed byte, even after scaling. See section 6.3.3 for more information.
LFDPC Loop Feedback Delta Position CoefficientUsed to scale a delta position value.0 to 255 1Delta 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 be multiplied by LFDPC and then added to the last reported position

Advanced

Users do not generally need these properties and should avoid using them. They are not listed by the FLIST or FLISTV commands; they are only listed by the FLISTA and FLISTAV commands.

ACCEL AccelerationMaximum acceleration and deceleration when moving from one position to another.0 to 65,535Fingers: 4 Spread: 2While the ACCEL property has a rather large range of values that it can accept, the motor can only follow a small subset of those values. The range of the subset is based on the motor control properties (e.g. SAMPLE, FPG, FDZ, FIP).
CT Close TargetThis is the position gone to by a C (“Close”) command.0 to 65,535Finger: 17,000 Spread: 3150While CT can be set as high as 65,535, its true range of useful values is bounded by the joint limits of the axes (e.g. approximately 0 to 18,000 for fingers and approximately 0 to 3150 for spread).
EN EnabledIf non-zero, then a motion command with no motor prefix will act on this motor.0, 1 1
FDZ Filter Derivative ZeroUsed to calculate the desired motor torque.0 to 255 0FPG sets B in the HCTL-1100 controller.
FIP Filter Integral PoleUsed to calculate the desired motor torque.0 to 255 0FIP sets A in the HCTL-1100 controller.
FPG Filter Proportional GainUsed to calculate the desired motor torque.0 to 25510FPG sets K in the HCTL-1100 controller.
HOLD HoldIf non-zero, then the motor is left energized after each motion command in order to hold the position constant.0, 1 Finger: 0 Spread: 1Since the fingers are not back-drivable, this is generally set to 1 only for the spread motor.
IHIT Initialization hit countIf non-zero, then while initializing the motor impacts the hard stop the given number of times.0 to 65,535Finger: 2 Spread: 0Barrett recommends not setting IHIT to a value greater than 5. IHIT is used to get a consistent origin for the finger motors, and thus a consistent breakaway force.
IOFF Initialization OffsetThis is the distance this motor’s origin is shifted away from the full open position.0 to 65,535Finger: 50 Spread: 0Adjusting this value on a finger motor also affects the force required to cause breakaway of the TorqueSwitchTM clutch. Larger values result in less compression of the Belleville washer, and so result in lower breakaway forces; smaller values similarly result in higher breakaway forces. Although IOFF can be set as high as 65,535, its true range of useful values is from 0 to approximately 500.
IVEL Initialization VelocityThis value replaces MOV (“Motor Open Velocity”) during initialization; this allows a consistent initialization velocity even if MOV is adjusted.16 to 4080Finger: 300 Spread: 150Barrett Technology does not recommend increasing IVEL beyond its default value. Permanent deformation of Bellville washers could result. This would prevent the finger breakaway mechanism from engaging.
MPE Maximum Position ErrorAfter moving to a desired position, if the position error is less than MPE then the move is considered a success.0 to 65,53550While MPE can be set as high as 65,535, its true range of useful values is bounded by the joint limits of the axes (e.g. approximately 0 to 18,000 for fingers and approximately 0 to 3150 for spread).
OT Open TargetThis is the position gone to by an O (“Open”) command.0 to 65,5350While OT can be set as high as 65,535, its true range of useful values is bounded by the joint limits of the axes (e.g. approximately 0 to 17,800 for fingers and approximately 0 to 3150 for spread).
SAMPLE Sample TimeControls the sample frequency of the motor controller chip.15 to 25531 Barrett Technology does not recommend changing this property from default.
SGFLIPStrain Gage FlipIf non-zero, then all strain gage values for this motor are subtracted from 255 before being sent to the host.0, 1 Used to invert strain gauge readings. This is a legacy command and may not be supported in future releases. It is strongly recommended that you avoid using SGFLIP since it may be dropped in future revisions of the firmware.
TSTOP Time to StopTime in milliseconds before motor is considered stopped.0 to 65,53530WARNING: Please use caution when adjusting this property. Setting TSTOP higher than its default can result in the motors heating up very quickly under moderate to heavy usage.

Global Properties

Global properties are used to configure or observe the hand as a whole.

Configuration

Global configuration properties affect the hand as a whole.

BAUDBaud rateControls the serial port baud rate. Value is baud rate divided by 100.6, 12, 24, 48, 96, 192, 384. 96
LFTLoop Feedback TemperatureIf non-zero, then when in RealTime mode the firmware sends a signed two-byte datum of temperature in each feedback block.0, 1 0
OTEMPOverTemperatureIf non-zero, then if the temperature exceeds this value then any motor command fails with an overtemperature error.0 to 12500 Value is temperature in tenths of a degrees C.

Status

Global status properties are read-only and give information about the state of the hand.

TEMPTemperatureThe present temperature on the CPU board in tenths of a degree C.-550 to 1250N/A
PTEMPPeak TemperatureThe maximum temperature ever experienced by this hand0 to 1250 N/AThis value is never reset; it is maintained through power failures and firmware downloads.
UPSECSUptime SecondsThe total power-up time for this hand.0 to 4 billionN/A This value is never reset; it is maintained through power failures and firmware downloads. This property can accommodate 136 years of power-up time before rolling over.
SNSerial NumberThe serial number of the hand.N/A N/A This value is never reset; it is maintained through power failures and firmware downloads. Hands upgraded to firmware version 4.2 in the field will have a serial number of 0.

Advanced

LFDPDLoop Feedback Delta Position DiscardIf non-zero, then in RealTime mode any position change that cannot be sent in a delta position datum is discarded. If zero, then any unsent position change is accumulated for transmission in the next cycle.0, 1 0

Termination Conditions for Movement Commands

There are eight commands in Supervisory mode that control finger motion:

  • Position commands, absolute: M and HOME
  • Position commands, relative: IO, IC.
  • Velocity commands with ramp-down at target limits: O, C
  • Velocity commands with control of motor torque at stall: TO, TC

In all cases, the command terminates and returns when, for every motor specified in the command, one of the following termination conditions applies:

Case 1: Motor stalls because obstacle(s) stop the motion. The obstacles include foreign objects as well as joint stops and other fingers.

  • When a motor stalls, the controller will continue driving it for TSTOP milliseconds, after which a termination condition occurs.
  • If HOLD is false, the motor is then turned off; if HOLD is true, the motor is servoed to maintain this position.
  • For position commands, if the termination position is not within MPE (Maximum Position Error), the status code ERR16 is returned corresponding to “Couldn’t reach position.”

Case 2: The strain-gage range is exceeded.

  • As soon as the sensor value SG rises above HSG (alias MSG) or falls below LSG, a termination condition occurs for that motor.
  • If HOLD is false, the motor is then turned off; if HOLD is true, the motor is servoed to maintain the position at which the termination condition occurred.
  • For position commands, if the termination position is not within MPE (Maximum Position Error), the status code is ERR16 is returned corresponding to “Couldn’t reach position”.
  • From the PC side of the interface, Case 2 can be distinguished by reading the value of the strain gage, SG, and seeing if it is larger than the specified MSG.

Case 3: Specified goal position is achieved within MPE.

  • As soon as the goal position is reached, a termination condition occurs for that motor.
  • If HOLD is false, the motor is then turned off; if HOLD is true, the motor is servoed to maintain the position at which the termination condition occurred.
  • No status code is returned, and a query to property S returns 0.

Case 4: Control-C character sent

  • As soon as the Control C is received, a termination condition occurs for all motors.
  • For each motor, if HOLD is false, that motor is then turned off; if HOLD is true, that motor is servoed to maintain the position at which the termination condition occurred.
  • The status code returned is 16384.
Last modified 13 years ago Last modified on May 12, 2011, 3:38:42 PM