RobotGeek Snapper Serial Mode Demo

snapper-joystick-backhoe.jpg
mt_ignore
PC Control
mt_ignore
Serial Control

The Arm Control library, firmware, and software will allow you to control InterbotiX arms by sending an absolute coordinate in X/Y/Z space for the arm to move to. This setup is useful for integrating the arm with software applications and other robotic systems.

This firmware is offered for advanced users with knowledge of serial-level communications.

When the SnapperArmSerial sketch is loaded onto the snapper arm, the arm will respond to a specially formulated serial packet. This packet will contain the absolute goal position of the end-effector (the gripper) in XYZ space, the angle of the wrist servo, the position of the gripper, and the speed of the arm.

This firmware also suports Cylindrical IK and Backhoe/ Joint control mode.

If you have not already, make sure you have gone through the Snapper Arm Getting Started Guide this will help make sure you've downloaded the RobotGeek Tools and Libraries, the demo firmware and have setup and tested the arm.

Project Parts List:

Arm Placement and Setup:

Whenever you program the Snapper arm, you should first manually position the servos in the sleep configuration. This will make the transition from off to on for the arm smoother.

When working with the arm, we recommend that you weigh it down / secure it to the surface you are working on. This will stop the arm from falling over due to sudden movements on startup.

The arm should never be powered by USB. Always connect the DC power before you connect in the USB cable, and disconnect the USB cable before you disconnect the power. If you want to power down the arm but leave the USB plugged in, remove the PWM power jumpers.

Wiring

Device Sensor Shield Port
Servos
Base Rotation RobotGeek Servo Digital 3
Shoulder RobotGeek Servo Digital 5
Elbow RobotGeek Servo Digital 6
Wrist RobotGeek Servo Digital 9
Gripper 9G Servo Digital 10
b_500_500_16777215_00__images_tutorials_rgSnapperArm_snapperArmServosOnly.png

Upload the Firmware

The rest of this guide assumes that you've set up the required libraries and sketches in the Snapper Arm Getting Started Guide. If you'd prefer to install a standalone version of the library and firmware, you can dowload the files here.

File -> Examples -> ArmLink  -> SnapperArmSerial	

Before you can load the code onto your Robot Arm, you'll need to adjust your code to match your gripper type. Around line 72 you should see the following code block

//#define GRIPPER_TYPE ROBOT_GEEK_9G_GRIPPER
//#define GRIPPER_TYPE ROBOT_GEEK_PARALLEL_GRIPPER

If you have any problems finding these lines, just press the 'compile' button and you'll see an error just below the code block.

In the code block, the two lines are Commented Out. Any line that starts with // is not processed by the Arduino IDE. This is useful for making code comments or to de-activate code without deleting the line. You will need to Uncomment one line by removing the slashes as shown below.

If you are using the RobotGeek Parallel Gripper, uncomment the second line. Your code should look like

//#define GRIPPER_TYPE ROBOT_GEEK_9G_GRIPPER
#define GRIPPER_TYPE ROBOT_GEEK_PARALLEL_GRIPPER

If you are using the RobotGeek 9G Gripper, uncomment the first line. Your code should look like

#define GRIPPER_TYPE ROBOT_GEEK_9G_GRIPPER
//#define GRIPPER_TYPE ROBOT_GEEK_PARALLEL_GRIPPER

You can now load the code onto your Geekduino. Remember to have plenty of room for the arm to move before you program it so that the arm doesn't accidently hit anything.

Click the 'Verify' button . If you get any errors, make sure you've setup the RobotGeek Tools and Libraries in the Geekduino Getting Started Guide. If everything worked out then you should see a 'Done Compiling' message under the code.

Now click the Upload button to load the code onto your microcontroller.

Once the firmware is uploaded, the Snapper Arm will move to a 'home' position.

Arm Control Packet Structure

The Snapper Arm will respond to a seventeen byte packet structured as follows:

Packet # Packet Info
1 Fixed Header - 0xff
2 X-Axis Coordinate High Byte
3 X-Axis Coordinate Low Byte
4 Y-Axis Coordinate High Byte
5 Y-Axis Coordinate Low Byte
6 Z-Axis Coordinate High Byte
7 Z-Axis Coordinate Low Byte
8 Wrist Angle High Byte
9 Wrist Angle Low Byte
10 *Wrist Rotate High Byte
11 *Wrist Rotate Low Byte
12 Gripper High Byte
13 Gripper Low Byte
14 Delta Value Byte
15 Button Byte
16 Extended Instruction Byte
17 Checksum

*These packets are not currently used in with the snapper arm. Send a '0' for these values.

A calculator to help determine the serial packet can be found here. This calculator will handle converting the integer values to bytes and calculating the checksum. See below for more details.

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 

Even though the Y, Z and wrist angle parameters can be stored in a single byte, the packet structure still has 2-bytes for each parameter to add support for arms with larger ranges.

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.

X will center at 512, with negative values ranging from 362-511, and positive values ranging from 512-662.

Transmitted Value Interpreted X-Coordinate Value
362 -150
512 0
662 150

WristAngle will center at 90, with negative values ranging from 362-511, and positive values ranging from 512-662.

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

The X value is centered at 512 to add support for arms with larger ranges.

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. It is recommended that you always set this bit to 0.

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

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*
0x20 32 Change Mode to 3D Cartesian / Straight Wrist & Go to Home
0x30 48 Change Mode to 3D Cylindrical / Straight 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)
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

The Arduino Code for this operation would be

checksum=(char)(255 - (xValBytes[1] + xValBytes[0] + yValBytes[1] + yValBytes[0] + zValBytes[1] + zValBytes[0] + wristAngleValBytes[1] + wristAngleValBytes[0] + wristRotValBytes[1] + wristRotValBytes[0] + gripperValBytes[1] + gripperValBytes[0] + deltaValBytes[0] + buttonByte + extValBytes[0])%256);

Gripper

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

Limits

Below are the limits for each parameter. These are the raw values, see above for the 'interpreted' limits of the X value and the WristAngle value.

Parameter Lower Limit Default Upper Limit
X 362 512 662
Y 50 150 200
Z 20 150 250
Wrist Angle 45 90 135
Gripper 0 0 512
Delta 0 125 255

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

Example Packets

Here are several example packets. Each byte is represented as a hex value. To send these packets you can use any program that will allow you to send bytes over a serial terminal. Many programming languages have this built in, or available as an additional library. There are also GUI applications such as RealTerm and Cornflake that will allow you to send these packets. You will need to set your application to the following settings:

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

In applications like realterm, you will need to send the numbers as hex values - simply put a '0x' before each value, as displayed in the example packet.

Example 1: Default Position

0xff 0x2 0x0 0x0 0x96 0x0 0x96 0x0 0x5a 0x00 0x00 0x0 0x0 0x80 0x00 0x00 0xf7
Paramater Value Transmitted Value Interpreted
X 512 0
Y 150 150
Z 150 150
Wrist Angle 90 0
Gripper 0 0
Delta 128 128

Examples 2-6 are variations on the default position

Example 2: X-Axis Left

0xff 0x1 0x38 0x0 0x96 0x0 0x96 0x0 0x5a 0x00 0x00 0x0 0x0 0x80 0x00 0x00 0xc0
Paramater Value Transmitted Value Interpreted
X 362 -150
Y 150 150
Z 150 150
Wrist Angle 90 0
Gripper 0 0
Delta 128 128

Example 3:Y-Axis In

0xff 0x2 0x0 0x0 0x32 0x0 0x96 0x0 0x5a 0x00 0x00 0x0 0x0 0x80 0x00 0x00 0x5b

Paramater Value Transmitted Value Interpreted
X 512 0
Y 50 50
Z 150 150
Wrist Angle 90 0
Gripper 0 0
Delta 128 128

Example 4: Z-Axis Down

0xff 0x2 0x0 0x0 0x96 0x0 0x32 0x0 0x5a 0x00 0x00 0x0 0x0 0x80 0x00 0x00 0x5b
Paramater Value Transmitted Value Interpreted
X 512 0
Y 150 150
Z 50 50
Wrist Angle 90 0
Gripper 0 0
Delta 128 128

Example 5: Wrist at -35 degrees

0xff 0x2 0x0 0x0 0x96 0x0 0x96 0x0 0x37 0x00 0x00 0x0 0x0 0x80 0x00 0x00 0x1a
Paramater Value Transmitted Value Interpreted
X 512 0
Y 150 150
Z 150 150
Wrist Angle 55 -35
Gripper 0 0
Delta 128 128

Example 6: Gripper Closed

0xff 0x2 0x0 0x0 0x96 0x0 0x96 0x0 0x5a 0x00 0x00 0x2 0x0 0x80 0x00 0x00 0xf5
Paramater Value Transmitted Value Interpreted
X 512 0
Y 150 150
Z 150 150
Wrist Angle 90 0
Gripper 512 512
Delta 128 128

Examples 7 and 8 go to the same pose, but with a different delta time.

Example 7: Stand Up - Fast

0xff 0x2 0x58 0x0 0x32 0x0 0xfa 0x0 0x5a 0x00 0x00 0x0 0x0 0x0 0x00 0x00 0x1f
Paramater Value Transmitted Value Interpreted
X 600 88
Y 50 50
Z 250 250
Wrist Angle 90 0
Gripper 0 0
Delta 0 0

Example 8: Stand Up - Slow

0xff 0x2 0x58 0x0 0x32 0x0 0xfa 0x0 0x5a 0x00 0x00 0x0 0x0 0xff 0x00 0x00 0x20
Paramater Value Transmitted Value Interpreted
X 600 88
Y 50 50
Z 250 250
Wrist Angle 90 0
Gripper 0 0
Delta 255 255
×

PC Control These demos and projects allow the robot to be controlled via a computer.

ArbotiX Commander Control - These demos and projects control the Robot using the ArbotiX Commander, the handheld Arduino based remote control.

Direct Control - These demos and projects control the Robot directly from sensors connected directly to the Robot's control board.

Pose Control - These demos and projects allow you to create and playback a sequence of poses.

Serial Control - These demos and projects control the robot using a serial packet protocol.

Standalone - These demos and projects are deisgned to let your robot function without a computer or additional microcontroller.

Wireless Control - These demos and projects allow you to control the robot wirelessly - usually by replacing the Serial Connection with XBee modules.

Reference - These articles have technical details regarding the control and operation of the robot.

×

More info here

Feedback Form


Search