Ortho-tweezers User Manual

This page has the following sections:

Ortho-tweezers Setup

The hardware and computer I/O interface to the ortho-tweezers system is described in Eiji Shimada's Hardware Manual. The only addition is an external relay board with eight relays, where relay 1 is used for the Heater On/Off interface. There is one wire to the relay board from the original digital I/O board (which is used for the stepper motor control). The digital outputs are shown in Figure 11 of the Hardware Manual. The heater would be added as digital output 13 in this figure. (Note that the 16 digital outputs are split into two 8 bit outputs in the AdvantechPCL711B interface. Thus digital output 13 is output 5 of the second 8 bits, which is a bit mask of 0x20. See the description below of how the heater interface is added to the code.)

Ortho-tweezers User Guide

Ortho-tweezers is a Java application which provides a user interface for manipulating the ortho-tweezers hardware and also allows you to run Python scripts. To install and compile Ortho-tweezers, see the Source Code and Programmer's Guide section below.

Starting Ortho-Tweezers

Before starting the Ortho-tweezers application, make sure that the power to the ortho-tweezers hardware is turned on. (On our system, don't forget to also turn on the power amplifier for the X probe piezoactuator.) From time to time, you should also calibrate the strain gauge amplifiers to set the offset to zero and the gain to 100. But the Ortho-tweezers application also does software calibration so the hardware calibration of the amplifiers is not so critical. See the description of the Reset Arm Offsets, Reset Tip Offsets and Calibrate functions in the Tweezers menu item section below.

As a Java application, Ortho-tweezers runs in the Java virtual machine. The main class is Orthotweezers in the package orthotweezers. Thus the full class name is orthotweezers.Orthotweezers. The directory structure in which the compiled class files exist follows the package hierarchy. So, when you execute a class from the command line, you should be in the directory at the "top" of the directory structure, which in this case means in the directory which contains the orthotweezers directory. For example on our workstation in 333 Cory, the class files (including Orthotweezers.class) are in d:\Users\jat\orthotweezers, so in a command prompt, I do the following:

cd \Users\jat
java orthotweezers.Orthotweezers

You can set up a Windows shortcut. In our case, there is a shortcut on the desktop where the "Start In" directory is set to
and the "Target" is set to
java orthotweezers.Orthotweezers.

(If you are working on the source code within Forte, you can run the application by selecting menu item Project/Execute Project. Make sure that the main class for the project is set to Orthotweezers.)

Ortho-tweezers Windows

There are two main windows, the control box and the monitor. The control box has buttons to move the stage and the probes. It also has the menu which is described in the next section, "Menu Items". Also in the control box there are buttons for quick access which duplicate the menu items for "Add Frame To Script", "Run Script" and "Use Python Console".

The monitor window constantly displays the stage position, probe positions and tip forces. It also displays a graphic of the probe positions and tip forces.
The graphic shows a green "cross hare" where one green line is the grip axis which connects the two probe tips and the other green line is at right angles to this. The tip forces are shown as red lines which extend perpendicularly from the tips (in the direction of the force). There is also a red line which extends from the center of the green crasher which is a composite of the two tip forces and represents the force balance. When a grip force is balanced, this red line should align with the green crasher line.

Menu Items

In addition to the control box described above, the Ortho-tweezers system is controlled from the menu items described here.

File menu:

Script menu: Stage menu: Tweezers menu:

Python Console

When you select Use Python Console or Run Script, the application invokes the Python Console. For an introduction to Python, see the Python Tutorial.

Accessing Ortho-tweezers manipulation functions

There are two ways to access the ortho-tweezers functions from Python:
  1. The global Python variable control points to the application's OrthoTweezersControl object and tools points to the application's OrthoTweezersTools object. This means you can access every method listed in the javadoc pages for OrthoTweezersControl and OrthoTweezersTools. For example, you can place control.moveToXY(.1, .2) in your Python script to move to position (.1, .2).
  2. Better yet, when invoking the Python console, the application creates easy access functions so that you don't have to type control. or tools. (and you don't have to remember whether the function you want is in control or tools.) For example, you can just type moveToXY(.1, .2). In general, you should use the easy access functions. I only mention the first method because in rare cases you may want to access an obscure methods for which there is not an easy access function, such as control.calibrateStrainErrors().


The menu items Set Location and Get Location above described the location variables which the Ortho-Tweezers application maintains. These location points are saved in the preferences file so that they are available each time you run the application. The Python variable MAX_LOCATIONS gives the number of location points available (currently 10) and the function location(n) returns location number n, where n ranges from 0 to MAX_LOCATIONS-1. Note that the type of a location is Point3d. See the description on the javax.vecmath.Point3d page. Basically, you access the x, y and z members. For example, moveToXY(location(0).x, location(0).y) will move to the X,Y coordinates in location(0). Because Point3d is a real class, you can also use all the useful methods like add, scale, distance, etc. Note that Point3d is also used by stagePoint and moveToPoint.

Although not used in any of the functions, each location can also have a name associated with it. These names appear in the menu and serve as reminders of what the point is for. You can set and get these names with the python array locationNames. For example, in the console you can type locationNames[0]="pallet" to remind the user that location zero is used for the pallet.

Using the Data Capture File

From a script, you can use the functions openCapture, startCapture, captureComment, stopCapture and closeCapture to capture the stage position, probe position and force data to a log file. See the description in the OrthoTweezersMonitor page. For example, to open a capture file and capture the data every 100 milliseconds, use the following Python commands:

openCapture ("c:\\mydata\\capture.txt", 0)
startCapture (100)

The data in the capture file is tab delimited and you can read it into a spreadsheet or Matlab file.


For your convenience, when the Python console is started, the following commands are executed:

from javax.vecmath import *
from math import *

This way, your Python scripts can include math functions such as cos(). Note that the constant pi is also defined.

Source Code and Programmer's Guide

Compiling Ortho-tweezers

To compile Ortho-tweezers, you must first have the Java software development kit installed which you can get from the Sun Java SDK site. Ortho-tweezers is written with the Forte for Java development environment. The source code is distributed in the file orthotweezers.zip. The zip file includes the .java files as well as .form files used by Forte. (On the development Windows workstation in 333 Cory, the source code is in D:\Users\jat\orthotweezers.)

Every class in Java belongs to a package. In this case, each class is in the orthotweezers package. Strictly speaking, you are supposed to pick a globally unique package name which by convention is based on a domain name you control. In this case, perhaps the package should be "edu.berkeley.eecs.robotics.orthotweezers". But right now, the package is just orthotweezers.

In addition to the Ortho-Tweezers source code, you need three jar files as follows:

These jar files belong in the extensions directory of the Java runtime environment. For example, on the development workstation these are in C:\jdk1.3\jre\lib\ext.

To compile, in Forte you can create a project called OrthoTweezers and add all the .java files provided in the source distribution. When compiling, Forte should find all the needed classes from the jar files because they are in the extensions directory for the runtime environment which Forte is using.

Tour of Source Files

The majority of the documentation is in the source files (where it is easier to update when the source code changes) in comment blocks which generate the javadoc documentation. The javadoc documentation in this web page is only a snapshot of the Ortho-tweezers code. To recompile the javadoc files in Forte, go to the file explorer, right click on the orthotweezers folder containing the source code and select Tools/Generate Javadoc.

As a tour of the Ortho-tweezers code and as an overview of what all the class files do, here is a record of how I added a digital output to the system to implement the Heater On/Off primitive. The source code now contains the statements I added. We start with the lowest level classes and work up to the user interface.

This completes the process of adding an interface to the heater.

back to Ortho-tweezers main page