Arm Link Reference

The Arm Link library, firmware, and software will allow you to control InterbotiX arms by sending an absolute value to each coordinate. These coordinates are sent over a serial port connection to the ArbotiX Robocontroller that controls the arm. The ArbotiX Robocontroller will receive the coordinates, do any required calculations, and then move the servos appropriatley.

Contents

Arm Modes

Each arm can be controlled using one of two IK engines (Cartesian or Cylindrical) or by controling each joint individually (Backhoe). The IK modes also have 90° Wrist options that default the wrist to 90° downward.

Cartesian Mode - Normal Wrist Angle

In thise mode you can send an X/Y/Z Coordinate to the arm and the end effector (the gripper) will go to the desired point.

The wrist angle joint will default to 0° so that it is parrallel with the ground. Adjusting the wrist angle joint will move the other joints to maintain the correct X/Y/Z position.

Cartesian Mode - 90° Wrist Angle

This mode is very similar to the previous mode. However in this mode the wrist angle will be set to -90° so that the wrist is perpendicular to the ground. This mode will also set the appropriate limits for the 90° mode.

Cylindrical Mode - Normal Wrist Angle

In thise mode you can send an Y/Z Coordinate to the arm and the end effector (the gripper) will go to the desired point.

The base servo can now be controlled absolutley. This increases the overall workspace of the arm. To control the base servo, you will send a raw servo value (0-1023 for the Reactor/Pinchter Arm and 0-4095 for WidowX arm)

The wrist angle joint will default to 0° so that it is parrallel with the ground. Adjusting the wrist angle joint will move the other joints to maintain the correct X/Y/Z position.

Cylindrical Mode - 90° Wrist Angle

This mode is very similar to the previous mode. However in this mode the wrist angle will be set to -90° so that the wrist is perpendicular to the ground. This mode will also set the appropriate limits for the 90° mode.

Backhoe/Joint Mode

This mode allows you to control each indididual joint in the arm. This is a good solution if your computer will be taking care of IK calulcations, or if you need to reach a position outside the reach of one of the IK engines.

To control the base servo, you will send a raw servo value. This will be 0-1023 for the all the joints in the Reactor/Pincher Arm. For the Base, Shoulder, Elbow and Wrist Angle joints on the WidowX arm this will be 0-4095 and 0-1023 for the wrist rotate and gripper joints.

NOTE: Keep in mind that those are absolute limits for the servos, and not necessarily limits for the joints in the arm. Please see the limits for each arm/value below.

Note: The firmware on the Robot Arm will handle double joints like those found in the PhantomX Reactor. Simply send the position for the joint and the code will mirror the inverse value to the second joint.

Tips

When the Robot Arm moves to a new mode, it will first return to its defualt position for this mode. This will also set the gripper to its default position.

Arm Link Packet Structure

The Arm Link packet holds the coordinate data to be sent from a computer or other controller to the ArbotiX Robocontroller. The packet is always 17 bytes long. The content of each byte will vary slightly based on the mode your arm is in.

To support the Arm Link protocol, your language will need to support sending byte data over a serial port. See the documentation for your language to see if it is capable of sending byte packets over a serial port.

Packet # Cartesian Mode Cylindrical Mode Backhoe Mode
1 Header (0xFF/255)
2 X-Axis Coordinate High Byte Base Servo Rotation High Byte
3 X-Axis Coordinate Low Byte Base Servo Rotation Low Byte
4 Y-Axis Coordinate High Byte Shoulder Servo Rotation High Byte
5 Y-Axis Coordinate Low Byte Shoulder Servo Rotation Low Byte
6 Z-Axis Coordinate High Byte Elbow Servo Rotation High Byte
7 Z-Axis Coordinate Low Byte Elbow Servo Rotation Low Byte
8 Wrist Angle High Byte
9 Wrist Angle Low Byte
10 Wrist Rotate High Byte
11 Wrist Rotate Low Byte
12 Griper High Byte
13 Gripper Low Byte
16 Delta Byte
15 Button Byte
16 Extended Instruction Byte
17 Checksum

Low Byte/High Byte Calculations

Arduino serial communications sends data as discrete byte-sized packets. An 8-bit byte can only hold values from 0-255. This is too small for the X/Y/Z coordinate values and the absolute servo positions values. To compensate for this, each parameter is split into two bytes - a low byte and a high byte. Once received by the Robot Arm, these bytes will be combined into the original value.

Examples
Value (Decimal) High Byte (Decimal) Lower Byte (Decimal) Value (Binary) High Byte (Binary) Lower Byte (Binary) Value (Hex) High Byte (Hex) Lower Byte (Hex)
128 0 128 0000000010000000 00000000 10000000 0080 00 80
781 3 13 0000001100001101 00000011 00001101 030D 03 0D
1023 3 255 0000001111111111 00000011 11111111 03FF 03 FF
1435 05 155 0000010110011011 00000101 10011011 059B 05 9B

The low byte corresponds to the first 8 bits of the value. To obtain this value we simply remove anything past the first 8 bits of the value. This can be done many ways, but the easiest way is to use the modulus operator (%).

Low Byte Pseudo Code

//coordinate is a previosuly defined integer value 
byte lowByte = coordinate % 256 ;

The low byte corresponds to the second 8 bits of the value. First we will shift the second byte down 8 values. To do this we can divide the value by 28 or 256. As these operations are being done on integers/bytes, the lower byte is discarded. Once we have shifted the second byte, we will use the modulus operator to ensure that only a single byte is isolated.

High Byte Pseudo Code

//coordinate is a previosuly defined integer value 
byte highByte = (coordinate / 256)%256;

Here's an alternative way to come up with the high/low byte using bitwise operators

//coordinate is a previosuly defined integer value 
	byte highByte = (coordinate >> 8) & 0xFF; //shift the value down 8 bits and mask it with 255/0xFF to isolate the byte 
	byte lowByte = coordinate & 0xFF; //mask the value with 255/0xFF to isloate the byte 

Delta

The Delta value

Button Byte Structure

The button byte can control digital outputs 1-7 on the ArbotiX Robocontroller. The first bit/Digital Output (0) is used by the ArbotiX Robocontroller and is not available through Arm Link. This bit is ignored

Bit # 8 7 6 5 4 3 2 1
ArbotiX Digital Output 7 6 5 4 3 2 1 N/A
Examples
Hex Decimal Binary Digital Outputs Active
0x00 0 00000000 none
0x01 1 00000001 none
0x02 2 00000010 1
0x0f 15 00001110 1,2,3
0xF2 242 11111110 1,2,3,4,5,6,7

Extended Byte Structure

The extended instruction byte allows the user to perform various actions or request data from the arm.
Hex Decimal Action
0x00 - 0x10 0-16 No Action
0x11 17 Emergency Stop - turns the torque off on all servos immediately
0x20 32 Change Mode to 3D Cartesian / Straight Wrist & Go to Home
0x28 40 Change Mode to 3D Cartesian / 90 ° Wrist & Go to Home
0x30 48 Change Mode to 3D Cylindrical / Straight Wrist & Go to Home
0x38 56 Change Mode to 3D Cylindrical / 90 ° Wrist & Go to Home
0x40 64 Change Mode to BackHoe / Joint Control & Go to Home
0x50 80 Move to Home / Straight Wrist in Current Mode (N/A for BackHoe Mode)
0x50 88 Move to Home / 90° Wrist in Current Mode (N/A for BackHoe Mode)
0x60 96 Put Arm in Sleep mode - move to sleep position and turn servo torque off
0x70 112 ID Packet Request
0x80 128 IK Status Reqeust (Not Implemented)
0xC8 200 Request Analog Packet on Analog 0
0xC9 201 Request Analog Packet on Analog 1
0xCA 202 Request Analog Packet on Analog 2
0xCB 203 Request Analog Packet on Analog 3
0xCC 204 Request Analog Packet on Analog 4
0xCD 205 Request Analog Packet on Analog 5
0xCE 206 Request Analog Packet on Analog 6
0xCF 207 Request Analog Packet on Analog 7

Checksum

The checksum is a dynamic value that will change if any of the values in the packet changes. This allows the arm to confirm the packet was received without any errors. The checksum can be calculated as follows:

  • Add up bytes 2 - 16 (do not include the header)
  • Isolate the low-byte of the sum (%256)
  • Invert the byte (255-)

The Psuedo Code for this operation would be

	sum = xHighByte + xLowByte +  yHighByte + yLowByte +  zHighByte + zLowByte +  wristAngleHighByte + wristAngleLowByte +  wristRotateHighByte + wristRotateLowByte +  gripperHighByte + gripperLowByte + deltaValBytes + buttonByte + extValBytes;//add up bytes 2-16
	invertedChecksum = sum % 256;//isolate the lowest byte
	checksum = 255 - invertedChecksum; //invert value to get file checksum

Negative/Offset Values

The parameters X and WristAngle both can have negative values. However all of the values transmitted via the ArmControl serial packet are unsigned bytes that are converted into unsigned integers - that is, they can only have positive values. To compensate for this fact, X and WristAngle are transmitted as offset values.

Add 512 to X to obtain the value to transmit over Arm Link.

Transmitted Value Interpreted X-Coordinate Value
312 -200
512 0
812 300

Add 90 to Wrist Angle to obtain the value to transmit over Arm Link.

Transmitted Value Interpreted Wrist Angle
45 -45
90 0
135 45

Arm Limits & Defaults

Pincher Arm Limits / Defaults

Click here to see the limits

Reactor Arm Limits

Click here to see the limits

WidowX Arm Limits

Click here to see the limits

Shared Limits / Defaults

Delta 0 255 128
Button 0 255 0
Extended 0 255 0

Notes on Values

Gripper

A '0' value will open the gripper all the way while a '1023' value will close it all the way.

Reading Analog Data

It is possible to read Analog Data from the ArbotiX RoboController and send the data back over the serial link. Sending the arm a specific extended instruction will cause the arm to report the current value of the correspnding analog value. See the Extended Table to see which instructions correspond to which analog ports.

Packet # Packet Info
1 Fixed Header - 0xff
2 Extended Instruction Echo
3 Analog Value High Byte
4 Analog Value Byte
5 Checksum

Arm ID Response Packet

Sending a packet with the extended instruction of 112 will cause the arm to send an ID response packet. This can be useful for determing what arm you are communicating with, or just to check if the arm is available.

The arm will also send this ID packet after its mode is changed, including sleep mode

The arm will respond with a 5-byte packet with the following data.

Packet # Packet Info
1 Fixed Header - 0xff
2 Arm ID#
3 IK Mode
4 Fixed - 0
5 Checksum
Arm IDs
Robot Arm Arm ID
InterbotiX PhantomX Pincher Arm Arm 1
InterbotiX PhantomX Reactor Arm Arm 2
InterbotiX WidowX Arm Arm 3
RobotGeek Snapper Arm 5
IK mode
Robot Arm Arm ID
Cartesian - Normal Wrist 1
Cartesian - 90° Wrist 2
Cylindrical - Normal Wrist 3
Cylindrical - 90° Wrist 4
Bakchoe/Joint Mode 5

Arm Link Packet Calculator

You can find a basic Arm Link calculator here