Arm Link Reference

mt_ignore
Reference Material

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

Contents

Firmware and Software

The Arm Link Library and Firmware examples are installed within the ArbotiX Hardware and Libraries files installed during the ArbotiX Getting Started Guide. Alternatively they can be found here. Details on installing the library manually and loading the ArmLinkSerial firmware can be found here.

A demo application, the Arm Link PC Control Software is also available. This open source application allows a computer to control the robot arm. This application can switch arm modes, set arm position, as well as control digital I/O and read analog input.

Arm Modes

Each arm can be controlled using one of two IK engines (Cartesian or Cylindrical) or by controlling 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 parallel 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 absolutely. 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/Pincher Arm and 0-4095 for WidowX arm)

The wrist angle joint will default to 0° so that it is parallel 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 individual joint in the arm. This is a good solution if your computer will be taking care of IK calculations, 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 default position for this mode. This will also set the gripper to its default position.

Serial Port Settings

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.

Your serial connection should have the following settings to communicate with the Robot Arm.

  • Baud: 38400
  • Parity: None
  • Data Bits: 8
  • Stop Bits: 1

When you open the serial port connected to the Robot Arm, you will automatically reset the ArbotiX-M Microcontroller. There is a 10 second delay before the ArmLink connection is available. Part of this delay is the ArbotiX-Ms boot-loader. The boot-loader waits several seconds when the board is reset. Until this delay passes, the Arm Link firmware does not respond to command packets. Because opening the serial port will reset the connection, a delay is introduced every time you open the port. There are 2 ways around this initial delay.

I. Remove Jumper 'J2' Physically remove the 'J2' reset jumper on the ArbotiX-M Robocontroller. This will stop the board from resetting when the serial port is opened on your computer. Keep in mind that the jumper is required for proper programming. For more information, read here.

II. Remove The Boot-loader It is also possible to remove this delay totally by overwriting the boot-loader via an ISP program. See here for more details.

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.

Positional packets can be sent discretely or at a regular interval. The Arm will finish a movement before it performs the next movement. If you are sending packets at an interval, do not send them faster than 30hz (one packet every 33ms).

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 previously 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 previously 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 previously 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 isolate the byte 

Delta

The Delta value determines how long it will take for the arm to move from its current position to the new position. The amount of time that the move takes is calculated by multiplying Delta by 16. The result will give you the time interval in milliseconds.

Time Interval = Delta * 16 

For example, a delta of 125 means that the move will take 2000 milliseconds, or 2 seconds.

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 0 Move Arm to Position*
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 Request (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

*Sending the arm an extended byte of 0 will send it to the current coordinates based on packets 2-15. Sending a packet with any other extended byte will ignore packets 2-15

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

The following list of limits are all 'interpreted' values. Parameters with a '*' must be offset to a positive range before transmission.

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

Parameter Lower Limit Upper Limit Default
Delta 0 255 128
Button 0 255 0
Extended 0 255 0

Notes on Values

Gripper

A '0' value will close the gripper all the way while a '512' value will open 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 corresponding 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 determining 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 1
InterbotiX PhantomX Reactor Arm 2
InterbotiX WidowX 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
Backhoe/Joint Mode 5

Arm Link Packet Calculator

You can find a basic Arm Link calculator here

Arm Link Packet Examples

You can find basic Arm Link example packets here