\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{primecal}{1}
\manSection{NAME}
{\tt \manName{primecal}}
-- primary robot calibration.
\manSection{USAGE}
\cverbatim
primecal [<robotName>] [-sim[=<simaddr>]] [-on]
@endcverbatim
\manSection{ARGUMENTS}
\manSection{DESCRIPTION}
This program is used for doing primary calibration on a robot
that calibrates using encoder index referencing (such the PUMA
robots).

Prime calibration is the ``initial'' calibration which sets the relationship
of the robot's joint angles to the outside world. What is done is this: The
robot is put in a known position (by means of a jig, by prepositioning using
the manufacturer-supplied language, or simply by moving the joints and
reading their locations precisely).

Once the robot's absolute position is known, the {\tt angleToEncoder()}
routine for that robot can be called to determine the corresponding encoder
values, and the encoders themselves are set to these values.  The robot has
now been calibrated by ``brute force''.  What we do next, essentially, is
obtain extra information so that the calibration can be done more easily.

Assume the encoder values at the known position are denoted by
$E_1$. Each joint is then put into calibration mode and moved through
increasing encoder values until the first zero index location is found;
at this point motion stops.
Denote the encoder values at this position by $E_2$.
Since the number of encoder counts between zero index locations
is constant (and known), the difference between $E_1$ and $E_2$ can
be used to determine the zero index locations closest to some standard
reference value (like 0). For historical reasons, this program,
and software based on it, uses 32768 (0100000) for all reference values.

The output of the program is the set of encoder values
corresponding to the nearest zero index locations greater than
or equal to 32768. These values are printed
to the file {\filefont primecal.out}, and should be used to
instantiate the {\tt encCalvec} field in the {\tt JLS}
structure for the robot in question.

\manSection{ARGUMENTS}
\manItem{{\tt robotName} --}
Optional robot name. If absent, the name is obtained from the system file
{\filefont \$RCCL/conf/defaultRobot}.
\manItem{{\tt -sim} --}
Causes the program to be run in simulator mode, in which it will attempt to 
connect to a robot simulator program (see {\tt robotsim}) instead of 
connecting to a real robot.
\manItem{}
If unqualified, the {\tt -sim} option causes the program to seek a simulator
running on the same machine under the same user name. A different simulator
can be specified by adding an address string {\tt <simaddr>},
as in {\tt -sim=<simaddr>}. For the format of this
address string, see {\tt simAddress(5)}.

\manItem{{\tt -on} --}
Leave the robot arm power on after the program has exited.

\manSection{OPERATION}
The program first enters into an interactive mode that allows
the user to move the arm into a known location, if necessary.
This interaction is driven by the automatic command completion
utility known as the {\it C-tree matcher}. 
Full documentation on the C-tree matcher is given in the file
{\filefont doc/CtreeMatch.doc}.

Once the arm is
in a known position, the user can enter the command
{\tt primecal}. The program will then ask for the values
of the robot angles corresponding to the
present robot position. It then
performs the primary calibration sequence described above,
printing out the {\tt encCalvec} vector (and writing
it to the file {\filefont primecal.out}) when done.

C-tree matcher commands include the following:

\manItem{{\tt primecal}}
Exit interactive mode and do primary calibration.
\manItem{{\tt quit}}
Quit the program.
\manItem{{\tt show}}
Print the robot encoder values and the values associated with other
program variables.
\manItem{{\tt angle <jnt> (to|by) <angle>}}
Move the specified joint to or by {\tt angle} degrees
(program must be in {\it angle} mode).
\manItem{{\tt encoder <jnt> (to|by) <encoder>}}
Move the specified joint to or by {\tt encoder} counts
(program must be in {\it encoder} mode).
\manItem{{\tt move to encoders}}
The program asks for a vector of encoder values, and the arm is
moved to the corresponding location
(program must be in {\it encoder} mode).
\manItem{{\tt move to angles}}
The program asks for a vector of angle values, and the arm is
moved to the corresponding location
(program must be in {\it angle} mode).
\manItem{{\tt stop}}
Stop the robot.
\manItem{{\tt set speed}}
Set the robot travel speed (degrees/sec.).
\manItem{{\tt set angle mode}}
Put the program into {\it angle} mode.
\manItem{{\tt set encoder mode}}
Put the program into {\it encoder} mode.

\manSection{BUGS}
Some of the code in the program assumes, at the moment, that
the robot has 6 rotary joints. This is mostly C-tree matcher code.
\manSection{SEE ALSO}
\raggedright
{\tt JLS(3)}, {\tt makejls(1)}.

The calibration of the puma robot is well described in the article 
``Breaking away from Val'', an document that originated at Stanford
University in the early days.
\manEnd
\end
