\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{potcal}{1}
\manSection{NAME}
{\tt \manName{potcal}}
\manSection{USAGE}
\cverbatim
potcal [<robotName>] [-sim[=<simaddr>]] [-on]
@endcverbatim
\manSection{DESCRIPTION}
A program used for determining the relationship
between joint potentiometer readings and encoder values on
robots that support potentiometers.

The program produces a first order linear model of encoder values
as a function of potentiometer readings. The model is described by
a {\it slope} and {\it intercept} value for each joint. The model
is used by the PUMA calibration program {\tt pumacal} as part of
the calibration process.

The information obtained from this program is used to fill in
the {\tt potSlope} and {\tt potIntercept} fields of the {\tt JLS}
structure (q.v.) for the robot in question. This is done by entering the
values into the robot's {\tt .jls} file, located in
the directory {\filefont \$RCCL/conf}. The slope values are placed
in the slot marked {\tt potSlope}, and the intercept values are
placed in the slot marked {\tt potIntercept} (see {\tt makejls} for more
information). As a convenience, values computed by the program 
are written into a file called {\tt potcal.out}. 

The program is interactive. Commands are entered using the
{\it C-tree matcher}, an automatic command completion utility.
Full documentation on the C-tree matcher is given in the file
{\filefont doc/CtreeMatch.doc}.

The basic action invoked by the program is the ``calibration
sweep'', which is initiated by the command {\tt calibrate}.
When each joint is calibrated, it is swept through its
range. During this time, a monitor function operating at the control level
samples the potentiometer and encoder values for each control cycle.
A linear model of the encoder values as a function of potentiometer readings
is then created from this data using a least-squares fit. 

The program calibrates the joints one at a time, except for the wrist,
where all three joints may be calibrated together using the command
{\tt calibrate wrist}.

Before asking the program to calibrate a particular joint, the robot
should be positioned so that the joint can be swept completely
through its range without hitting anything. The interactive commands
{\tt move} and {\tt angle} can be used to accomplish this.

\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 basic interactive commands include the following:

\manItem{{\tt help}}
Tells you to look at this man page.
\manItem{{\tt calibrate <jnt>}}
Do a calibration sweep of the indicated joint, and then display
the calculated slope and intercept of the pot/encoder relationship.
This data will also be written into the file {\tt potcal.out}.
By default,
the joint will be
swept through its entire range.
The joint ranges are displayed as part of the {\tt show} command.
\manItem{{\tt calibrate wrist}}
Calibrate all wrist joints at once.
\manItem{{\tt show}}
Print the robot position, joint ranges, pot readings, and variable settings.
\manItem{{\tt angle <jnt> [to|by] <angle>}}
Move the indicated joint to or by {\tt angle} degrees.
\manItem{{\tt move to midpoint}}
Move all the joints to the center of their range of travel.
\manItem{{\tt stop}}
Stop the robot.
\manItem{{\tt set travel speed}}
Set the speed at which the robot responds to motion commands
(degrees per second).
\manItem{{\tt set travel speed}}
Set the speed at which the robot performs a calibration sweep
(degrees per second).
\manItem{{\tt set sweepAngle}}
Set the size of the interval through which the next calibration sweep
will be performed. The sweep will be made along an interval 
which extends {\tt sweepAngle} degrees to either side
of the joint's mid range value. The direction of travel will be assigned so
that the encoder values 
are increasing. This command affects only the next calibration sweep.
\manItem{{\tt unset sweepAngle}}
Clear any sweep angle setting made by {\tt set sweepAngle}.
\manItem{{\tt quit}}
Quit the program.
\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)}.
\manEnd
\end
