robotsim(1)

NAME
robotsim -- RCI robot simulation program.

USAGE
robotsim [-s] [-i] [-r <interval>] [-noauto]
         [-ng] [-X11] [-bg <background>] [-fg <foreground>] [-wf]
         [-nocfg] [-f <configFile>] [-pendant]
         [ <robotName> [-nc] [-p <position>]
           [-clf <CartesianLogFile>] [-jlf <jointLogFile>] ]

DESCRIPTION
This is the RCCL/RCI robot simulator program. It is used to simulate robots controlled by RCCL/RCI programs, and is useful for debugging such programs at the trajectory control level.

NOTE: The current version of robotsim described here is still in a state of development, and is likely to undergo considerable changes in the future.

The simulator program runs as a separate process that emulates one or more robots and their controllers. Starting up the simulator program is equivalent to "switching on the controllers", and the simulator will continue to run for the duration of multiple RCCL/RCI programs, retaining a consistent notion of each robot's state between these programs. The simulator starts up with each robot in a known position. There are options for displaying joint angles and other state information as the simulator runs, and there is also an interactive keyboard mode that allows single step operation. The latter is particularly useful for debugging applications.

At the present time, the simulator does only 3D graphic/kinematic simulation; it does not calculate robot dynamics (except, in some cases, for gravity loading), and does not do collision detection. The simulator has been designed, however, to allow introduction of these features at a later date.

The operational characteristics of the simulator can be controlled through a combination of command line arguments and specifications contained in a configuration file. The command line arguments normally take precedence over the configuration file. The default configuration file is called .robotsim, and the program looks for this file first in the current directory, then in the user's home directory, and finally in the the directory $RCCL/conf. A configuration file with a different name can be specified using the -f option.

Graphics Support

The simulator supports graphics output for X windows, SunView, and the SGI graphics library "GL". On X windows and SunView, a wireframe display is produced, while under GL there is support for both wire frame and solid shaded graphics. Normally, robotsim will attempt to create a graphics window at startup time unless it is given the command line option -ng. The type of graphics window is chosen according to the following sequence of rules:

o   X windows will always be chosen if the command line option -X11 is given. The environment variable DISPLAY must be set appropriately in order for this to work.

o   GL will be chosen next, if it is available. Solid shaded graphics will be selected unless the command line option -wf (wire frame) is given.

o   X windows will be chosen if the environment variable DISPLAY is set.

o   SunView will be chosen if the environment variable WINDOW_PARENT is set (this may not be the most reasonable way to determine if SunView is active; please advise the authors if you know of a better way).

Connecting to the Simulator

RCCL/RCI programs connect to the simulator using the special device driver "sim", defined in the "drivers" directory. This is an RCI I/O device (see IOdevice(7)) which works by setting up a socket connection to the simulator process rather than accessing some robot interface on an I/O bus.

To get an RCCL/RCI program to connect to the simulator, instead of a real robot, it must be run in simulator mode. There are different ways of doing this. The utility programs (move, pumacal, etc.) will run in simulator mode if the option -sim is given to them. All RCCL programs will run in simulator mode if the simulate keyword is set in the RCCL parameter set of the to run in simulation mode using the routine rcclSetSimulator().

The simulator works using TCP/IP. It is therefore possible to connect an RCCL/RCI program to a simulator running on a remote machine. When a simulator is started on a particular machine, it gives itself a name (which is usually the user name under which the simulator is running) and registers itself, and the names of all the robots it is simulating, with a server daemon. The server daemon, called RCISimMuxd, is a separate task which is spawned if necessary. Other RCCL/RCI programs can then connect to a "robot" provided by the simulator by specifying the name of the robot, the name of the simulator, and an Internet address for the machine where the simulator is running. The full syntax for specifying this is a string that looks like

        <robotName>:<simulatorName>@<hostName>

It is not usually necessary for the user of an RCCL/RCI program to specify this entire string. For instance, in the case of an RCCL program, a simulator connection is often specified by setting the simulate parameter in the .rciparams file. If this is set to 1, as in

        simulate=1

the RCCL program will try to connect its robots to a simulator running under the same user name, and on the same host machine, as itself. To attach to a simulator running under the same user name, but on a different machine, one would set

        simulate=@<hostName>

where <hostName> is an appropriate Internet address.

The -sim option to the utility programs (move, pumacal, free) can be set similarly.

For more details on the address string format for a simulator, see the manual page simAddress(5).

Notice from the above description that simply specifying simulate = 1 will not enable a program to connect to a simulator running under a different user name. This was done in order to allow simulator processes to be more or less "private" to a given user.

COMMAND LINE ARGUMENTS

Basic Arguments

robotsim accepts the following command line arguments:

-s --
    Silent mode. This option causes all messages concerning robot activity to be suppressed. It is useful when the program is being run on the same terminal/window as the RCI/RCCL program.

-i --
    Interactive mode. This option invokes a Ctree-matcher shell that allows the user to set various simulated I/O conditions, single or multi-step the control cycle interaction, and examine variables. This mode is described in detail in the OPERATION section.

-r <interval> --
    Sample rate. The base simulated sample rate is set to interval milliseconds.

-noauto --
    Start the simulator up with autocycling disabled. This means that the simulator cycles can be controlled using the step command in interactive keyboard mode.

-ng --
    No graphics. Do not attempt to open a graphics window.

-X11 --
    Use X11 graphics.

-bg <background> --
    Background color. Set the background color as specified by the integer background; see the section "Specifying Colors". On black and white displays, setting this to a non-zero value creates a reverse video display.

-fg <foreground> --
    Foreground color. Set the foreground color as specified by the integer foreground; see the section "Specifying Colors". This hasn't been completely implemented yet.

-wf --
    Use wire frame graphics.

nocfg --
    No config file. Do not attempt to read in a configuration file. This will override the -f option.

-f <filename> --
    Configuration file. Read in the configuration file specified by <filename> instead of the default .rciparams file.

-pendant --
    Create a simulated teach pendant for the robots which are being simulated. See the section TEACH PENDANT, below.

Robot Arguments

robotsim also accepts the following arguments describing the robots it is simulating. Each of these arguments applies to the robot most recently specified on the command line.

<robotName> --
    Name of a robot to be simulated. The program will simulate the specified robot. The "name" must be a robot known to RCI, with the appropriate configuration files set up in $RCCL/conf.

-nc --
    Start the program with the robot uncalibrated. This option is the closest you can get to simulating "turning the controller on"; it is then necessary to "calibrate" the robot before running applications.

-p <position> --
    Gives the name of a position which the simulator will use as the robot's initial position. The <positionName> should be the name of one of the robot positions defined in the file conf/<robotName>.pos.

-jlf <jointLogFile> --
    Maintains a log file containing the joint coordinate values for each control cycle. Each line in the file contains a number indicating the cycle number for the current control session, followed by the joint values (see the description of the keyboard command open joint log, below). The file will remain open until it is closed with the keyboard command close joint log.

-clf <CartesianLogFile> --
    Maintains a log file containing the Cartesian coordinate values for each control cycle. Each line in the file contains a number indicating the cycle number for the current control session, followed by a string indicating the robot configuration, three numbers describing the translational component of the T6 transform, and four numbers forming a unit quaternion representing the rotational component of the T6 transform. (see the description of the keyboard command open cartesian log, below). The file will remain open until it is closed with the keyboard command close cartesian log.

CONFIGURATION FILE

Conceptually, the configuration file contains a set of declarative statements that control what the simulator displays and how it displays them. Most of the information in the configuration file is related to the graphics simulation.

Structure

The basic structural element of the configuration file is the set, which is a list of elements enclosed within angle brackets (< >). Elements can be numbers (integer or floating point), strings, or other sets. Integers are given by sequences of digits, which can be prefixed with 0x to indicate hex, 0o or 0 to indicate octal, or 0b to indicate binary. Floats are denoted by either a decimal point or an exponent e. Strings are enclosed with quotes (""). There is generally no need to separate set entries with anything except white space, although commas can be used if desired; this is sometimes necessary to disambiguate set elements that involve expressions.

A set element can also be tagged with a name. The usual format for this is

        tagName=element

where tagName is composed of alphanumeric or underscore characters and does not begin with a digit. Tag names are case sensitive. White space may be placed around the =, if desired. Another form of tag uses a colon (:), as in

        tagName:element

In the simulator config file, colon tagging is only used for the top level of declarations.

Comments can be introduced with the # character: all characters between # and the end of the current line are ignored. A subset of the C-preprocessor directives is also implemented: #if 0, #if 1, #else, and #endif. As with the C-preprocessor, these must be placed at the beginning of line. They can be used to comment out unwanted declarations, as in

        #if 0
          ... stuff to ignore ...
        #endif

or to introduce different declarations, as in

        #if 1
          ... use these declarations ...
        #else
          ... instead of these ...
        #endif

Variables can be declared using the notation :=, as in

        foo := 12

Legal variable types are floating point numbers, integers, strings, and sets. If declared within a set, then the variable definition is local to that set. Variable names have the same composition requirements as element tags: they must consist of alphanumeric or underscore characters, are case sensitive, and cannot begin with a digit. Once declared, a variable can be used in place of a literal.

Simple arithmetic expressions are supported, with the operators +, -, *, and /, and parentheses (()). Expressions are not currently defined for sets or strings. If all of the components of an expression are integer, then the expression evaluates to an integer; otherwise, the expression evaluates to a float. Expressions can be used in any place that would normally accept a number, including sets or variable definitions. The config file parser is greedy, in that it will attempt to create as long an expression as possible. For instance, in the construction

        < 1  -1 2 2>

the first two tokens would be combined into an expression (1-1), so that the parsed result would be the set <0, 2, 2>. If necessary, these situations can be disambiguated using commas, so that

        < 1, -1 2 2>

would parse to <1, -1, 2, 2>.

The character ? can be used to indicate an empty set element. In some instances, this can be used to indicate a default value.

A set consisting exclusively of numbers (float or integer), and possibly the empty element ?, is considered to be a vector.

Specifying Colors

Some of the options described below will involve setting color values. In general, these can be specified as an integer where the red intensity is given by the first 8 bits, the green intensity is given by the second 8 bits, and the blue intensity is given by the third 8 bits. So for example, 0xff0000 would describe a full intensity blue, 0xffffff would describe white, 0x808080 would describe a medium gray, and 0x0 would describe black. When applicable to black and white displays, a color description will often be interpreted such that zero indicates black and a non-zero value indicates white.

Specifying Locations

Some of the options described below require the setting of spatial locations. In general, these are specified by a vector of numbers. The first part of this vector consists of up to six untagged numbers, where the first three numbers represent the x, y, and z values of a translation vector, and the next three numbers represent successive rotations about the z, y, and x axes. Each rotation is given in degrees and is applied relative to the previous coordinate frame. If the vector has a length of less than six, or if any of the elements are specified by an empty character (?), then the missing values default to zero.

After the untagged numbers, it is possible to add additional numbers tagged with tx=, ty=, tz=, rx=, ry=, or rz=. These taggings denote a translation or rotation operation about the x, y, or z axes, respectively. Rotations are given in degrees. Each operation is applied relative to the previous frame. So for instance,

        < 10 20 rx=10 ry=60 tz=6 rx=90>

describes a location formed by an initial translation along the vector (10,20,0), followed by a rotation of 10 degrees about the x axis, a rotation of 60 degrees about the new y axis, a translation of 6 along the new z axis, and finally a rotation of 90 degrees about the new x axis. There is no set limit to the number of operations that may be specified.

Location Functions

Location functions provide a way to allow an object to move around while the simulator is running. Basically, a location function is specified by a string that identifies a function compiled into the program. The function is called with the following arguments:

        locfxn (trsf, com, arg, ptr)
        TRSF *trsf;
        int com, arg;
        void *ptr;
        {
           ...
        }

trsf is a pointer to a transform data structure for which the function should provide values. com, arg, and ptr are arguments that are normally prespecified inside the program binary, although it is possible to specify the arg parameter from within the config file.

If an object has a location function defined, then the transform T set by the location function defines the location of the object with respect to (a) simulator world coordinates, if the object is defined at the top level, or (b) the coordinate frame of the parent object, if the object is an element of a compound object (compound objects are discussed below). If an explicit location L has also been specified for the object (using the loc parameter in the config file), then this is premultiplied by the final value of the functional transform T, so that the total position of the object is given by T L.

User-defined location functions can be added to robotsim by declaring them in the table locFxnTable, defined in the file robotsim/simFxns.c, along with appropriate values for the com, arg, and ptr arguments. The simulator program must then be rebuilt with the new table and the new functions.

There are several built-in location functions that can be useful for returning dynamic locations associated with the robots. Each built-in function is prefixed with the name of a robot (<robot>), followed by a dot (.), and finally followed by a suffix that explains what the function does. The following location functions are defined:

<robot>.T<n>
    Returns the current value of the transform for link n of the robot <robot>. For instance, the function specified by frank.T5 would return the link 5 transform of the robot frank.

<robot>.HandTX, <robot>.HandTY, <robot>.HandTZ
    Defines a transform in which the translation component along the x, y, or z axis is set to the value of the robot's hand. Other components of the transform are set to the identity. For instance, Zeus.HandTY specifies a function that sets the y translation component to the hand value for the robot Zeus. If the arg parameter is specified, this is used to scale the final value.

<robot>.HandRX, <robot>.HandRY, <robot>.HandRZ
    Defines a transform in which the rotation component about the x, y, or z axis is set to the value of the robot's hand (in degrees). Other components of the transform are set to the identity. If the arg parameter is specified, this is used to scale the final value.

The built-in location functions can be used to specify a compound object as the end effector for a particular robot. The base location of the compound object can be specified with the function <robot>.T6, and appropriate sub-object components can be tied to the hand position functions.

Within the config file, a location function is specified by a parameter set having up to two elements. The first element is a string describing the name of the function; this must match either one of the built-in functions or one of the user-defined functions in locFxnTable. The second argument is an optional integer which specifies the value of the arg parameter.

As an example, a specification for a location function foo, with an argument value of 1200, would look like:

        < "foo", 1200 >

(remember that the commas are optional). As another example, a specification for the built-in function HandTX, applied with respect to a robot called Zeus and with an argument value of 10, would look like:
        < "Zeus.HandTX", 10 >

TOP LEVEL CONFIG DECLARATIONS

The configuration file is itself a set, which accepts the following tagged elements:

windowPos = < x y w h >
    A set of four integers describing, in pixels, the initial placement of the graphics window on the screen. x and y give the coordinates of the lower left corner or the window, and w and h give its width and height. Not all graphics implementations respond to this completely.

viewWindow = < l r b t n f >
    A set of floats describing the graphics "viewing pyramid", in eye coordinates. Eye coordinates are defined so that, as the viewer looks at the screen, the x axis points to the right, the y axis points up, and the z axis points toward the viewer. The viewing pyramid is therefore located entirely in the half space corresponding to z < 0. The l, r, b, and t describe the left, right, bottom, and top coordinates of the near face of the pyramid (the one closest to the viewer). n and f describe the distances (along the -z axis) of the near and far faces.

ortho = on
    An integer which if set to a true (non-zero) value enables orthographic instead of perspective projection.

viewTrans = < locationSpec >
    A location specification describing the transformation from eye coordinates to the simulator world coordinates with respect to which the locations of all objects and robots are defined (see the section "Specifying Locations").

bgColor = colorSpec
    An integer which specifies the color of the background (see the section "Specifying Colors"). For black and white displays, setting this to a non-zero value creates a reverse-video effect.

fgColor = colorSpec
    An integer which specifies the color of the foreground (see the section "Specifying Colors"). This hasn't been completely implemented yet.

ROBOT : < robot params >
    A set of parameters that specifies characteristics for a particular robot. See the section ROBOT DECLARATIONS.

OBJECT : < object params >
    A set of parameters that define an object. An object is a solid shape that can be added to the graphics display. See the section OBJECT DECLARATIONS.

MATERIAL : < material params >
    A set of parameters that define a material. A material is a set of reflecting and light emitting properties that are used to define the shaded illumination behaviour of an object.

LIGHT : < light params >
    A set of parameters that define a light source. Light sources provide the illumination for the object materials. If no light sources are specified, some default sources will be set up.

ROBOT DECLARATIONS

Each parameter set ROBOT: must have as its first parameter an untagged string that gives the name of the robot. This must be a robot which is defined in the RCI database; i.e., it must have The parameter set can then include the following tagged parameters, in any order:

loc = < locationSpec >
    Defines the location of the robot with respect to the simulator world frame. See the section "Specifying Locations".

locfxn = < locationFxnSpec >
    Defines a location function that modifies the location of the robot. See the section "Location Functions".

drawEndEffector = on
    An integer which if set true (non-zero) indicates that the robot display code should draw an end effector for the robot. This will usually be some standard sort of gripper, and may not be too interesting. If you want to define your own gripper object, then you should specify this variable as false. The default value for this parameter is true.

angles = < angles >
    A vector of floats describing the initial joint angles for the manipulator. The default values for these angles are taken from the parkAngles field of the manipulator JLS structure. If the vector is shorter than the number of robot angles, or if any of the elements are specified as ?, then the default values are used for the unspecified angles.

OBJECT DECLARATIONS

Each parameter set OBJECT: must have as its first parameter an untagged string that identifies the type of the object. Then depending on the object type, different tagged parameters may be used to define the object geometry.

Planar objects are defined with respect to the x-y plane, and prismatic objects are defined so that their bottom face lies in the x-y plane. Objects can be relocated from their defining frame by including a loc specification in their definition.

The different object types and their parameters currently include:

box

Defines a rectangular box.

dimen = < w h l>
    A vector of three floats giving the dimensions of the box. w, h, and l give the dimensions along the x, y, and z axes, respectively. This parameter must be specified.

disc

Defines a circular disc.

rad = float
    The radius of the disc. This parameter must be specified.

depth = float
    The height of the disc (along the z axis). This parameter must be specified.

nsides = int
    The number of polygonal faces used to form the curved part of the disc. This parameter is optional.

cone

Defines a cone; this is basically a disc where the radii of the top and bottom faces differ.

rtop = float
    The radius of the top face of the cone. This parameter must be specified.

rbot = float
    The radius of the bottom face of the cone. This parameter must be specified.

depth = float
    The height of the cone (along the z axis). This parameter must be specified.

nsides = int
    The number of polygonal faces used to form the curved part of the cone. This parameter is optional.

sphere

Defines a sphere, centered at the origin.

rad = float
    The radius of the sphere. This parameter must be specified.

polygon

Defines a convex planar polygon. It is possible to define either a regular polygon, using the parameters size and nsides, or an arbitrary polygon, using the parameter face.

size = float
    The length of one of the sides of a regular polygon. This parameter must be specified when defining a regular polygon.

nsides = int
    The number of sides of a regular polygon. This parameter must be specified when defining a regular polygon.

face = < x1 y1 x2 y2 ... >
    A vector of floats listing the x and y coordinates of the vertices of an arbitrary polygon, in counter-clockwise order. The number of elements in this vector must be even (since each vertex has two components) and must be greater than or equal to six (corresponding to a three sided polygon). This parameter must be specified if an arbitrary polygon is being defined.

lines

Defines a set of line segments lying in the x-y plane.

vtxs = < < x1 y1 x2 y2 > < x1 y1 x2 y2 > ... >
    A set of four element vectors, where each vector gives the x and y coordinates of the beginning and end points of a line segment. There is no set limit to the number of line segments that can be specified. This parameter must be specified.

prism

Defines a general prism. This is an convex object with two parallel polygonal faces, each with the same number of sides. Each face is parallel to the x-y plane, with the bottom face lying on the plane.

depth = float
    The depth of the prism, or the distance between the two faces. This can also be interpreted as the height of the prism along the z axis. This parameter must be specified.

botface = < x1 y1 x2 y2 ... >
    A vector of floats defining the x and y coordinates of the bottom face polygon, in counter-clockwise order as seen from above (i.e., z > 0). The number of elements in this vector must be even (since each vertex has two components) and must be greater than or equal to six (corresponding to a three sided polygon). This parameter must be specified.

topface = < x1 y1 x2 y2 ... >
    A vector of floats defining the x and y coordinates of the top face polygon, in counter-clockwise order as seen from above (i.e., z > 0). This parameter is optional. If not specified, then the top face polygon is assumed to be identical to the bottom face polygon. If a top face polygon is specified, then it must have the same number of vertices as the bottom polygon.

smooth = string
    A string of digits, either "0" or "1", with each digit corresponding to a vertex in the top or bottom polygons (recall that the top and bottom polygons must have the same number of vertices). If the digit is "1", then the edge connecting the top polygon vertex with the corresponding bottom polygon vertex is assumed to be "smooth"; i.e., part of a smooth surface. In the case of a wire frame display, the edge will not be drawn. In the case of a shaded illumination display, continuous shading will be applied across the edge. This parameter is optional. If it is omitted, then all edges in the prism are assumed not to be smooth.

compound

In addition to standard objects, it is possible to recursively define compound objects. A compound object is given by a set of strings or parameter sets. A string should give the name of a previously defined object (names can be given to all objects; see the section on generic parameters, below). A parameter set should be one which defines an object, although the top level OBJECT: tag should be omitted.

Generic parameters

The following parameters may be specified for all objects:

loc = < locationSpec >
    Defines the location of the object with respect to its base frame (see the section "Specifying Locations"). For an object defined at the top level, the base frame is the simulator world coordinate frame. For an object which is an element of a compound object, the base frame is the frame of the parent object.

locfxn = < locationFxnSpec >
    Defines a location function that modifies the location of the object. See the section "Location Functions".

name = string
    Defines a name for the object. This name may be used to reference the object later when a compound object is defined.

mat = materialSpec
    Defines a material for the object, which controls the object's illumination characteristics. Material definitions are effectively ignored in the case of a wire frame display. The material specification may be either an actual parameter set defining a material (see MATERIAL DECLARATIONS), or it may be the name of a material already defined. If a material is not defined, then a top level object gets a default material, while a member of a compound object inherits the material of its parent.

MATERIAL DECLARATIONS

The parameters which are used to define a material are adopted from the conventions used by the Silicon Graphics "GL" library. A material may be defined with a parameter set containing one or more of the following elements. If not specified, each of these elements has a default value of 0.

diffuse = colorSpec
    An integer defining the diffuse lighting characteristics of the material. Light of this color is reflected depending on the angle of the object with respect to the light sources.

ambient = colorSpec
    An integer defining the ambient lighting characteristics of the material. Light of this color is reflected depending on the amount of ambient, or background, light created by the light sources.

emission = colorSpec
    An integer defining the emission characteristics of the material. The material will "glow" with this color, independent of the surrounding light sources.

specular = colorSpec
    An integer defining the color of the specular component of the material. Light will be reflected depending on the relationship between the object faces, the light source, and the viewer. This parameter works in conjunction with the shininess parameter.

shine = float
    A floating point number from 0 to 1 that defines the actual shininess of the material. If set to 0, there will be no specular reflection.

alpha = float
    Used in applications involving transparent objects. Not implemented.

LIGHT DECLARATIONS

The first parameter in a light declaration is a vector of three floating point numbers, which gives the x, y, and z components of a vector defining the direction of the light source with respect to the simulator world coordinate frame. This parameter is required. The other parameters are optional, and are set to 0 if not specified:

color = colorSpec
    An integer defining the color of the directional light associated with the source (see the section "Specifying Colors").

ambient = color
    An integer defining the color of the ambient light associated with the source.

KEYBOARD OPERATION

In interactive keyboard mode, program commands are entered using the C-tree matcher, an automatic command completion utility. Full documentation on the C-tree matcher is given in the file doc/CtreeMatch.doc.

Some commands apply to the entire simulator program, while other commands apply only to a specific robot, which is selected using the command robot.

Simulator-Wide Commands

quit
    Quit the program.

autocycling (on | off)
    Enable or disable autocycling. The simulator emulates real time using a fixed sample rate, to which all robot interactions are slaved. When autocycling is enabled (which is true by default), then one time cycle automatically follows another. If autocycling is disabled, then time cycles can be single-stepped using the step command. This is useful for interactive debugging.

step <num>
    This command enables the execution of <num> time cycles when autocycling is disabled.

show sim
    Prints out information about the general state of the simulator, such as the current cycle number.

show graphics
    If graphics is enabled, then this prints out information about the graphics state, including the current parameters for the view transform and viewing pyramid.

postscript ( eps | idraw ) <width> <height> <file>
    If wire frame graphics are being run, then this command executes full hidden line removal for the current image and writes a PostScript description of it to <file>. The parameters <width> and <height> are floats which describe, in inches, the final size of the output PostScript image. With the eps option, encapsulated PostScript is generated. With the idraw option, a set of PostScript macros are generated that can be read by the X11 drawing program idraw.

robot <name>
    Selects the robot to which subsequent robot-specific commands should be applied. It is also possible to select this robot from the graphic teach pendant interface (see TEACH PENDANT, below).

Robot Specific Commands

Most of the robot specific commands are intended to allow the user to set values associated with the various sensor I/O options supported by the simulated robot controller. They can be helpful in debugging RCCL/RCI applications that depend on sensor input, although they can also be rather awkward to use. Some of this stuff should be replaced with graphical/mouse interaction. The teach pendant simulation is particularly ridiculous.

set tool
    Sets the TOOL frame which is used in determining where applied forces and displacements occur. The default TOOL frame is the identity matrix.

set force
    Sets a bias force to be applied at the TOOL frame. This force will affect both joint torques and the Cartesian forces returned to RCI. It is possible to set the value along a specific axis, or all six axes (all).

set displacement
    Sets a Cartesian displacement bias in the TOOL frame. Robot setpoints will be offset by this amount in the TOOL frame. It is possible to set the value along a specific axis, or all six axes (all).

pioIn <channel> <value>
    Sets the values of the parallel input port channel to value, where value is given in hex.

ADC <channel> <value>
    Sets the value of an ADC channel to the indicated signed value.

joystick
    Sets the value associated with input from a 6 DOF joystick. It is possible to set either an individual joystick axis, or all axes (all).

clear tool
    Sets the TOOL frame to the identity matrix.

clear force
    Clears any applied force in the TOOL frame.

clear displacement
    Clears any displacement bias in the TOOL frame.

pendant reset
    Resets the state of the teach pendant input (releases all the buttons).

pendant release
    Releases a button being pushed on the teach pendant.

pendant button <button>
    Simulates the pushing of any of a large number of teach pendant buttons. Once this command is entered, the indicated "button" will be pushed until the pendant release command is entered.

show tool
    Prints the default robot TOOL transform.

show force
    Prints the force being applied in the TOOL frame.

show displacement
    Prints the displacement bias in the TOOL frame.

show pendant
    Prints a bit map of the teach pendant showing what buttons have been pushed. This bit map is equivalent to the map returned to the pendant field of the RCI HOW structure.

show pio

    Prints the bit settings of the input and output channels of the parallel ports.

show ADC/DAC
    Prints the values of the ADC and DAC channels.

show options
    Prints the sensor I/O options available on the simulator.

show controller
    Prints states and control modes associated with the simulated "controller".

show robot
    Displays all robot joint variables, including torques, angles, and hand position.

open cartesian log <filename>
    Opens a log file in which the Cartesian (T6) position of the robot will be printed for all subsequent control cycles until the file is either closed or the program exits. Any Cartesian log file which was previously open is closed. Each T6 position will be printed in the file, one line per entry, according to the following format:

                    cycleNum conf px py pz qc qs1 qs2 qs3

    cycleNum is the cycle number in the current control session. conf is a string describing the robot configuration. px, py, and pz are the T6 translational values. The q numbers are the 4 values of a unit quaternion describing the rotational component of T6. They are obtained from T6 using the function trsfToQtrn.

open joint log <filename>
    Opens a log file in which the joint angles of the robot will be printed for all subsequent control cycles until the file is either closed or the program exits. Any joint log file which was previously open is closed. The joint angles are printed in the file, one line per entry, according to the following format:

                    cycleNum j1 j2 j3 j4 j5 j6

    cycleNum is the cycle number in the current control session, and j1 through j6 are the joint angles.

close cartesian log
    Closes the Cartesian log file.

close joint log
    Closes the joint log file.

TEACH PENDANT

If robotsim is given the command line option -pendant and is run with a graphics display, then a simple simulated teach pendant will be created within the graphic display control panel at the right edge of the window.

Hitting a button on this "teach pendant" is done by moving the mouse cursor over the desired button and pressing the left mouse button.

If more than one robot is being simulated, the teach pendant must be shared between them. The name of the robot which currently "owns" the teach pendant is displayed on an illuminated button above the pendant. Clicking this button will cause ownership of the pendant to pass from one robot to the next. The robot that owns the pendant is the same robot selected for interative keyboard commands, so pendant ownership can also be changed using the keyboard command robot.

The teach pendant layout is patterned roughly after that used on Unimation robot controllers. It should be noted that hitting a teach pendant button will not cause a robot to move per-se, but will simply send back information to the RCCL/RCI application program describing which button(s) are pressed. (This information appears in the pendantInput field of the robot's HOW structure.) It is then up to the application to move the robot. Moving the robot under teach pendant control thus requires running an appropriate RCCL/RCI program, such as teachdemo. Delays may be noticable in some teach pendant interactions, due to the nature of the connection between the teach pendant and the application program.

It might be reasonable to build a teach pendant trajectory generator directly into the simulator program, so that the arm could be moved about locally without requiring an attached RCCL/RCI application.

BUGS

The full hidden line removal algorithm used by the wire frame graphics does not work if any of the defined objects intersect. However, full hidden line removal is generally used only when producing PostScript output.