Controlling Arduino Robot Arm With Arm Link Software

Want to be cool like Simone Giertz but don't know where to start?

The InterbotiX Arm Link Software provides a simple interface for Arduino-Compatible Robot Arms. Using this software you can control the Robot Arm via a variety of movement modes including Cartesian IK mode, Cylindrical IK mode, and Backhoe/Joint mode.

In addition to directly controlling your Robot Arm, the Arm Link software can also activate digital outputs, read analog inputs, play motion sequences, and display webcam feeds.

This software is offered as a simple control solution for these Robot Arms as well as an example for individuals who wish to integrate the Robot Arms into their own applications and systems. InterbotiX Arm Link is an open source program written in Java in the Processing environment. The Arm Link Software is currently compatible with:

• RobotGeek Snapper Arduino Robotic Arm

• PhantomX Pincher Robot Arm Kit Mark II

• PhantomX Reactor Robot Arm Kit

• WidowX Robot Arm Kit Mark II

For this tutorial, we will cover the setup and usage of a RobotGeek Snapper Arm with the Arm Link Software. If you'd like to set up one of the InterbotiX arms, you can follow this guide, which will get you set up with the proper firmware for your robot arm.

Step 1: Set up your robot arm hardware

The RobotGeek Snapper Robot Arm Kit comes with all of the robotic hardware you need for this tutorial - you'll just need a Windows, Mac or Linux computer.

This project can also be done with the RobotGeek Snapper Core Arm Kit, assuming that you have your own microcontroller, power supply and wiring.

Follow the Getting Started Guide and Assembly Guide to build your robot arm.

Step 2: Firmware Installation

The Arm Link Library and Firmware is automatically installed with the RobotGeek Tools and Library files and does not need to be installed separately. If you wish to manually install the files, download and unzip the InterbotiX Arm Link Library & Firmware files. Open the folder ArmLinkLibrary-master and copy the ArmLink folder into your Arduino Library folder.

Open the ArmLinkSerial firmware from the Arduino IDE.

File -> Examples -> Arm Link -> SnapperArmLinkSerial 

Before you can load the code onto your Robot Arm, you'll need to adjust your code to match your gripper type. In the Arduino IDE, click on the tab GlobalArm.h Around line 16 you should see the following code block

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

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

Now that the gripper type is defined, the code will take care of correctly processing your gripper type. If you are having problems finding these lines, click on the Compile button in the Arduino IDE and it will show an error near the lines you need to change.

Now you can load the firmware onto the Geekduino. Once you are done, leave your USB cable plugged into your computer, as this is how the software will communicate with the Arm.

Step 3: Arm Link Software Installation

Download the Arm Link Control Software

The Arm Link Software is written in Java. We recommend that you download the version with embedded java for your OS (see the Download Page for more information) . The software is compatible with Windows XP, Vista and 7, Mac OS 10.5+, and Linux.

Mac users please see the 'Note for Mac Users' here before following the rest of this guide.

If you have any problems running the Arm Link Software, we recommend you run the software in the processing environment. This process is relativity easy and gives you additional options.

Step 4: Using the Arm Link Software

Use the Auto-Connect button, or pick a serial port and use the Connect button. The arm will move from it's 'sleep' position to a 'home' position. This may take several seconds. Once the arm has moved to its home position and is ready for commands,the various panels will appear. You can adjust the sliders or text panels to adjust the positions of the arm. Use the Update button to send these values to the arm.

You can use the 'Auto-Update' checkbox to send commands to the Robot Arm automatically. Because each pose needs to complete before the next pose can be sent, users may wish to lower the Delta value to make the arm more responsive.

Usage Notes

Missing Serial Ports

Plug in your FTDI-USB cable BEFORE opening the program. The Arm Link software does not currently refresh the serial port list after connection, so the serial port must be available when the program starts up. If the serial port is not available in Arm Link, close and re-open the application. Plugging/unplugging the

Using a Webcam

Webcam support is experimental at this time. We recommend using the RobotGeek VGA webcam with 250mm Gooseneck with the Arm Link Software. Other webcams should work just fine, but have not been tested. The program will try to connect to the first webcam available to it. If you have problems, try plugging the camera directly into your computer (and not through hubs or extenders).

Sequence Panel

Changing mode or wrist orientation via the Mode Panel or the Wrist Panel will remove all of the current poses in the sequence panel. The software does not currently support mixed mode playback.

Packet Data

If you want to watch the packets that you are sending, see here

Analog Feedback and Auto Updating

We do not recommend using 'Auto Update' and 'Analog Input' at the same time. The Analog Feedback function works a little differently from the rest of the controls. All of the other controls issue commands to the Robot Arm, but the analog feedback features requests data. To get a piece of analog data, the program must send a commander packet requesting the current analog value for a specific port. When enabled, the analog feedback will request a new piece of data every 33ms. While auto-updating is turned on, a command packet is sent every 33ms as well. When both of these are working at the same time the responsiveness of the arm may be slower than normal.

Step 5: Playback Sequences

Once your firmware and software are setup, connect to the Robotic Arm in the Arm Link Software. Click the 'New Pose' button in the Sequence Panel to create a new pose. The new pose will be indicated by a numbered panel to the right of the pose panel buttons. This newly created pose will contain the coordinates that the Control Panel currently shows , the default pose.

Now use the Control Panel to choose a new position for the Arm to move to. Click 'Update' to make sure that the arm has moved to the position you intended it to go to. Feel free to make slight adjustments to the arm to the correct position. Once you are happy with the arm's position, click the 'New Pose' Button again and you will see another pose created. This pose will contain the coordinates that the Control Panel currently shows.

Repeat this process of positioning the arm and making new poses until you have the desired number of poses. Click the 'Play Poses' button to see all of your poses in action. Press 'Stop Poses' to stop the playback. Playback will always start with the selected pose, unless no poses are selected, which will start the playback from pose 0.

If you need to adjust a pose, first click on the individual pose to select it. The pose should expand to be larger than the other poses to show it is selected. Now click 'Load Pose' to load the pose into the control panel. You will need to click 'Update' to physically move the arm to that poses's position. You can now make any adjustments to the control panel to adjust the pose. Once you are happy with the pose, click 'Save Pose' to save the pose data back into the selected pose.

You can load a pose, then create new poses to make copies of a specific pose. You can also drag and drop poses to re-order them. Poses will maintain their color, but lose their specific numbering.

There are two timing variables you can adjust. The first is the Delta value (the amount of time it takes to complete the pose). The delta value is unique for each movement. A smaller delta value will create a faster movement, and a larger delta will create a slower movement.

The second variable is the pause value. This value determines how long the arm will wait after the pose is complete before it initiates the next pose. This pose can be set to 0, or any arbitrary value. Simply enter the time value in milliseconds, and each pose will wait for that period of time. In the Arm Link Software, this value is global for all poses, though it is possible to change it per-pose once you've exported the sequence.

Once you are satisfied with your sequence and timing, press 'Save to File'. This will open a window dialog and ask you to pick a folder to put the exported armSequence.h file. Temporarily put the file on your Desktop.

Step 6: Load the Sequence into the Stand Alone Firmware

In the Snapper Arm Getting Started Guide you should have downloaded the Snapper Arm Demo Code and added it to your RobotGeek sketches folder. This file included the SnapperArmPlayback code. Before you open the sketch in your IDE, you will need to copy your armSequence.h file into the SnapperArmPlayback folder. Assuming your Arduino folder is in your Documents folder, you can find the SnapperArmPlayback here:

Documents -> Arduino -> RobotGeek sketches -> SnapperArm -> SnapperArmPlayback

In this folder you will find several files including a default copy of armSequence.h . The default copy of the file moves each axis on the arm sequentially. You can save this file in another folder for later use, or you can delete it. Now copy the armSequence.h file you saved to your desktop into the SnapperArmPlayback folder.

Now you can open the SnapperArmPlayback sketch into your Arduino IDE. In the Arduino IDE, you can find the sketch under:

File -> Sketchbook -> RobotGeek sketches -> Snapper Arm -> SnapperArmPlayback 

Before you can load the code onto your Robot Arm, you'll need to adjust your code to match your gripper type. In the Arduino IDE, click on the tab GlobalArm.h Around line 16 you should see the following code block:

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

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

Now that the gripper type is defined, the code will take care of correctly processing your gripper type. If you are having problems finding these lines, click on the Compile button in the Arduino IDE and it will show an error near the lines you need to change.

Now you can load the sketch onto your Geekduino. The arm should go to its home position while it waits for the sequence to start. You can activate the sequence by pressing the button you have attached to the arm, or by opening the serial monitor (38400 baud) and sending a 1 .

Your arm will now play the sequence you designed. The arm will play the sequence once and then stop on the last pose. The actions should be the same as they were in the Arm Link Software. You can start the pose again by pressing the pushbutton/entering the serial command again.

If you press the button a second time, the arm will stop when it finishes its current pose. If you send a '1' over the serial terminal, the arm will complete its entire sequence and then stop.

Step 7: You're done! What now?

Now that you have your arm set up, are familiar with the way Arm Link works, and can record and play back poses, what can you do?

We had one of our arms:

• feed Kyle a tasty snack

• hack the planet

• open an RFID Lockbox

• dish out the high fives

• help clean up office clutter

• and even drive a hexapod around.

We'd love to see your robot arm doing some crazy things!

Step 8: Advanced Usage

Minimal Code

The folder SnapperArmPlaybackMinimal contains a sketch with the minimum amount of code to play the arm sequence one time. This code may assist you if you wish to integrate the arm playback code into existing projects/code. If you want to add your own sequence into this file, add the contents of the do loop in armSequence.h into the setup loop in SnapperArmPlaybackMinimal.ino

IKSequencingControl() Overview

The armSequence.h file works by making several calls to the IKSequencingControl() function. This function allows you to easily move the arm to a specific position.

The IKSequencingControl() function takes parameters.The snapper arm only uses 8 of these parameters. The 'Wrist Rotate' parameter should be set to a '0' value.

For example, in cartesian mode, the following line will move the arm to (0,150,150) (X,Y,Z) with a 0° wrist angle, and the gripper closed. It will move over a period of 2 seconds and wait for one second after pose completion.

IKSequencingControl(0 , 150 , 150 , 0 , 0 , 0 , 2000 , 1000, 1);

Adjusting Timing

You can fine tune each pose by adjusting the 7th and 8th parameters in the IKSequencingControl() function. Changing the 7th parameter, the delta value will effect the time it takes for the arm to move from its current position to the next position. The previous examples has the arm moving over 2000 milliseconds. If you want the arm to move over 5000 milliseconds, change the code to

IKSequencingControl(0 , 150 , 150 , 0 , 512 , 0 , 5000 , 1000, 1);

Changing the 8th parameter, the pause value will effect the time the arm waits after the pose is completed. The previous examples has the arm waiting for 1000 milliseconds. If you want the arm to move to the next position immediately, change the code to

IKSequencingControl(0 , 150 , 150 , 0 , 512 , 0 , 2000 , 0, 1);

Manually Adjusting Values

Using the Arm Link Software is the best way to generate values for the arms, as it will check limits and let you try out the arm. However it is possible to manually create your own poses from scratch. See the Arm Limits tables to see the ranges of values you can use for each arm/parameter. NOTE:The delta value listed in the previous tables does not apply to the IKSequencingControl() function. See 'Adjusting Timing' above for instructions on adjusting the delta value.

Interrupting Sequences

Once you have sent an command for the arm to move and it has begun moving, the individual pose cannot be interrupted - it will always complete the pose.

The SnapperArmPlayback code can stop a sequence after any pose via the pushbutton. This is because the pushbutton is attached to an interrupt pin. When a change is made to this pin (such as the pushbutton being activated), the currently running code is paused and special interrupt code is executed. This code sets the playState variable to 0 . Any further IKSequencingControl() calls do not execute arm movements because this enable is turned off.

It is also possible to insert additional code in the IKSequencingControl() function to check for additional conditions. This will allow you to interrupt the sequence based on other conditions (like serial events, analog data, and other non-interrupt digital pins).

Advanced Pushbutton Options

If you are NOT using a pushbutton (and instead are relying on the serial terminal or automated sequences) you will need to change line 41 from

#define USE_BUTTON true

to

#define USE_BUTTON false

This will disable the code from trying to read the digital pin (and possible reading noise/activating the arm)

If you are using a Pushbutton with Jumper Wires or any other 2-wire momentary switch, change line 45 should be

#define BUTTON_TRUE LOW

Changing this #define will set the logic up and the pull up resistor for your pushbutton.

If you are using a RobotGeek Pushbutton or a pushbutton with a built in pull-down resistor, you can leave the define as-is.

#define BUTTON_TRUE HIGH