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
| Value | Motor |
| 1 | Finger F1 |
| 2 | Finger F2 |
| 3 | Finger F3 |
| 4 | Spread |
| G | Finger F1, Finger F2, Finger F3 |
| S | Spread |
| <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 Code | Description |
| 1 | No motor board found |
| 2 | No motor found |
| 4 | Motor not initialized |
| 8 | (not used) |
| 16 | Couldn't reach position |
| 32 | Unknown command |
| 64 | Unknown parameter name |
| 128 | Invalid value |
| 256 | Tried to write a read only property |
| 512 | (not used) |
| 1024 | Too many arguments for this command |
| 2048 | Invalid RealTime control block header |
| 4096 | Command can't have motor prefix |
| 8192 | Overtemperature fault tripped |
| 16384 | Cntl-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.
| Command | Name | Purpose | Arguments | Example | Notes |
| C | Close | Commands 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) | SC | The 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. |
| HI | Hand Initialize | Initializes the selected motor controller(s), preparing them for use by other movement commands. | (none) | HI | HI 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. |
| HOME | Home | Moves the selected motor(s) to position 0. | (none) | SGHOME | |
| IO | Incremental Open | Opens 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 | |
| IC | Incremental Close | Closes 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 | |
| LOOP | Loop | Enters RealTime mode. | (none) | LOOP | See Section 6 for more information on RealTime mode. |
| M | Move | Moves 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 | |
| O | Open | Commands 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) | GO | The 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. |
| T | Terminate power | Turns the selected motor(s)'s power off. | (none) | ST | Although 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. |
| TC | Torque-Controlled Close | Commands velocity of selected motor(s) in the direction that closes the finger(s) with control of motor torque at stall. | (none) | STC | |
| TO | Torque-Controlled Open | Commands 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.
| Command | Name | Purpose | Arguments | Example | Notes |
| FSET | Finger Set | Sets the to the given value(s) for one or more motor properties | <propertyName> <propertyValue> | SFSET DS 100 DP 1500 | You can set more than one property by listing more than one propertyName/propertyValue pair. |
| FGET | Finger Get | Gets 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 DP | More than one property name may be added. |
| FLOAD | Finger Load | Loads the selected motor(s)'s properties from non-volatile storage. This is done whenever the firmware starts up. | (none) | 3FLOAD | The non-volatile storage used does not depend on the super capacitor, so it retains its value even if the firmware is lost. |
| FSAVE | Finger Save | Saves the selected motor(s)'s properties to non-volatile storage. | (none) | 123FSAVE | The 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. |
| FDEF | Finger Default | Sets the selected motor(s)'s properties back to their factory default values. | (none) | SFDEF | Does not save the changed values to non-volatile storage. |
| FLIST | Finger List | Lists all of the standard motor properties and their descriptions. | (none) | FLIST | Does not take a motor prefix. |
| FLISTV | Finger List Value | Lists 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.
| Command | Name | Purpose | Arguments | Example | Notes |
| PSET | Property Set | Sets 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. |
| PGET | Property Get | Gets and prints one or more given property value(s). Each property has its value(s) printed on one line. | <propertyName> | PGET TEMP UPSECS | Get more than one property value by listing more than one property name. |
| PLOAD | Property Load | Loads the global properties from non-volatile storage. This is done whenever the firmware starts up. | (none) | PLOAD | The non-volatile storage used does not depend on the super capacitor, so it retains its value even if the firmware is lost. |
| PSAVE | Property Save | Saves the global properties to non-volatile storage. | (none) | PSAVE | The 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. |
| PDEF | Property Default | Sets the writable global properties to their default values. | (none) | PDEF | Does not save the changed values to non-volatile storage. |
| PLIST | Property List | Lists all of the standard global properties and their descriptions. | (none) | PLIST | |
| PLISTV | Property List Value | Lists 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.
| Command | Name | Purpose | Arguments | Example | Notes |
| ? | Help | Lists all of the standard commands. If immediately followed by a command name, then it lists the command name and its description. | <commandName> | ?HI | There must be no space between "?" and any command name. |
| RESET | Reset | Resets the hand software. Equivalent to doing a power cycle. | (none) | RESET | |
| ERR | Error | If 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 | |
| VERS | Version | Prints 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.
| Command | Name | Purpose | Arguments | Example | Notes |
| A? | Help All | Lists all of the standard and advanced commands. | (none) | A? | Use the ? command to get a description of an advanced command. |
| FLISTA | Finger List All | Lists all of the standard and advanced finger property names. | (none) | FLISTA | |
| FLISTAV | Finger List All Value | Lists 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) | 3FLISTAV | Can take a motor prefix. |
| PLISTA | Property List All | Lists all of the standard and advanced global property names. | (none) | PLISTA | |
| PLISTAV | Property List All Value | Lists 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.
| Property | Name | Purpose | Values | Default | Notes |
| BDAT | Breakaway Detection Acceleration Threshold | Used to adjust the breakaway detection accuracy | 0 to 20000 | Finger: 1500; Spread: N/A | Units of BDAT are: Encoder counts/(Ticklet2). There are 307 ticklets per millisecond. |
| BS | Breakaway Stop | Used to stop finger as soon as breakaway has been detected. | 0 or 1 | Finger: 0 Spread: N/A | When set to 1, the finger motor will stop when breakaway is detected. |
| DP | Default Position | Destination of M command if no argument specified | 0 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 Step | Size of IC or IO command movement if no argument specified | 0 to 65,535 | Finger: 1700 Spread: 315 | While 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 Value | In 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 Value | In 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 | 256 | A value of 255 or 256 disables the strain gage checking during motion commands. |
| MOV | Maximum Open Velocity | Controls the maximum velocity while opening a motor. | 16 to 4080 | Finger: 100 Spread: 60 | |
| MCV | Maximum Close Velocity | Controls the maximum velocity while closing a motor. | 16 to 4080 | Finger: 100 Spread: 60 | |
| MSG | Maximum Strain Gauge | In 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.
| Property | Name | Purpose | Values | Default | Notes |
| BD | Breakaway-Detected Flag | To determine if breakaway has occurred | 0 or 1 | N/A | Flag is set when a breakaway is detected. Flag is cleared after an O, TO, or HI command. |
| BP | Breakaway Position | Stores position of last breakaway | 0 or 20000 | N/A | Stored position of location of last breakaway. Position is cleared after an O, TO, or HI. |
| OD | Odometer | The total number of counts traveled by the selected motor, divided by 1000. | 0 to 4 billion | N/A | This value is never reset; it is maintained through power failures and firmware downloads. |
| P | Position | The present position of the motor. | Finger: 0 to approximately 17,800 Spread: 0 to approximately 3150 | N/A | The 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 | Status | The 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 these | N/A | See status codes in section 5.1.3. |
| SG | Strain Gauge | The present strain gage value for the motor. | 0 to 255 | N/A | Returns 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 Velocity | If non-zero, then a velocity byte will be sent in the control block for the motor. | 0, 1 | 1 | |
| LCVC | Loop Control Velocity Coefficient | When 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 255 | 1 | |
| LCPG | Loop Control Proportional Gain | If non-zero, then a Proportional Gain byte will be sent in the control block for the motor. | 0, 1 | 1 | This controls the constant that is multiplied by the velocity error in order to produce the motor torque. |
| LCT | Loop Control Torque | If non-zero, then a signed 2-byte torque will be sent in the control block for the motor. | 0, 1 | 0 | Motor 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 Input | If 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 Position | If 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 Velocity | If 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 Coefficient | Before sending a Loop Feedback Velocity byte, the firmware divides the velocity by this property's value. | 0 to 255 | 1 | |
| LFS | Loop Feedback Strain | If non-zero, then the firmware sends an unsigned byte giving the strain gauge value for the motor. | 0, 1 | 1 | |
| LFAP | Loop Feedback Absolute Position | If 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 Position | If 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 | 1 | A 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 Coefficient | Used to scale a delta position value. | 0 to 255 | 1 | 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 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 | Acceleration | Maximum acceleration and deceleration when moving from one position to another. | 0 to 65,535 | Fingers: 4 Spread: 2 | While 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 Target | This is the position gone to by a C (“Close”) command. | 0 to 65,535 | Finger: 17,000 Spread: 3150 | While 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 | Enabled | If non-zero, then a motion command with no motor prefix will act on this motor. | 0, 1 | 1 | |
| FDZ | Filter Derivative Zero | Used to calculate the desired motor torque. | 0 to 255 | 0 | FPG sets B in the HCTL-1100 controller. |
| FIP | Filter Integral Pole | Used to calculate the desired motor torque. | 0 to 255 | 0 | FIP sets A in the HCTL-1100 controller. |
| FPG | Filter Proportional Gain | Used to calculate the desired motor torque. | 0 to 255 | 10 | FPG sets K in the HCTL-1100 controller. |
| HOLD | Hold | If non-zero, then the motor is left energized after each motion command in order to hold the position constant. | 0, 1 | Finger: 0 Spread: 1 | Since the fingers are not back-drivable, this is generally set to 1 only for the spread motor. |
| IHIT | Initialization hit count | If non-zero, then while initializing the motor impacts the hard stop the given number of times. | 0 to 65,535 | Finger: 2 Spread: 0 | Barrett 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 Offset | This is the distance this motor’s origin is shifted away from the full open position. | 0 to 65,535 | Finger: 50 Spread: 0 | Adjusting 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 Velocity | This value replaces MOV (“Motor Open Velocity”) during initialization; this allows a consistent initialization velocity even if MOV is adjusted. | 16 to 4080 | Finger: 300 Spread: 150 | Barrett 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 Error | After moving to a desired position, if the position error is less than MPE then the move is considered a success. | 0 to 65,535 | 50 | While 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 Target | This is the position gone to by an O (“Open”) command. | 0 to 65,535 | 0 | While 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 Time | Controls the sample frequency of the motor controller chip. | 15 to 255 | 31 | Barrett Technology does not recommend changing this property from default. |
| SGFLIP | Strain Gage Flip | If 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 Stop | Time in milliseconds before motor is considered stopped. | 0 to 65,535 | 30 | WARNING: 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.
| BAUD | Baud rate | Controls the serial port baud rate. Value is baud rate divided by 100. | 6, 12, 24, 48, 96, 192, 384. | 96 | |
| LFT | Loop Feedback Temperature | If non-zero, then when in RealTime mode the firmware sends a signed two-byte datum of temperature in each feedback block. | 0, 1 | 0 | |
| OTEMP | OverTemperature | If non-zero, then if the temperature exceeds this value then any motor command fails with an overtemperature error. | 0 to 1250 | 0 | 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.
| TEMP | Temperature | The present temperature on the CPU board in tenths of a degree C. | -550 to 1250 | N/A | |
| PTEMP | Peak Temperature | The maximum temperature ever experienced by this hand | 0 to 1250 | N/A | This value is never reset; it is maintained through power failures and firmware downloads. |
| UPSECS | Uptime Seconds | The total power-up time for this hand. | 0 to 4 billion | N/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. |
| SN | Serial Number | The 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
| LFDPD | Loop Feedback Delta Position Discard | If 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 14 years ago
Last modified on May 12, 2011, 3:38:42 PM
