\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{simSupport}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{simScheduling}},
{\tt \manName{simSetTimer}},
{\tt \manName{simAttachRobot}},
{\tt \manName{simRobotsReady}} --
RCI simulation mode support functions.
}
\manSection{USAGE}
\cverbatim
#include <rci.h>
#include <sys/time.h>

simScheduling (td)
  RCI_DESC *td;

simSetTimer (interval, cycleStartTime)
  int interval;
  struct timeval *cycleStartTime;

simAttachRobot (td, name, addressStr)
  RCI_DESC *td;
  const char *name;
  const char *addressStr;

simRobotsReady (td)
  RCI_DESC *td;

@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt td} --}
Pointer to task descriptor.
\manItem{{\tt interval} --}
Wakeup interval (in milliseconds).
\manItem{{\tt cycleStartTime} --}
Optional argument specifying the time at which the current control cycle
started. 
\manItem{{\tt name} --}
Name of the robot.
\manItem{{\tt addressStr} --}
Optional argument giving additional information identifying
which robot simulator to connect to.
\manSection{RESTRICTIONS}
{\tt simScheduling()} and {\tt simAttachRobot()} 
must be called from the planning level.
\manSection{DESCRIPTION}
These functions are designed to help control an RCI task (particularly
one with robots attached to it) which is being run in simulator mode.

{\tt simScheduling()}, called from the planning level,
puts in a call to {\tt rciScheduling()} specifing
the {\tt ON_SIGNAL} discipline and the UNIX signal {\tt SIGALRM}.

{\tt simSetTimer()}, called from the control level,
schedules a {\tt SIGALRM} to be delivered to the RCI program 
to wake up the control task. This function should be called
prior to each control cycle (i.e., during
the task's {\it startup} function 
and then once during each {\it control} function).
The delay ($d_t$) between when the function is called and when the
signal is delivered is computed as
follows: (a) If {\tt cycleStartTime} is given as {\tt NULL}, then
$d_t$ is set directly equal to the interval time
($t_i$) given by {\tt interval}. (b) Otherwise, {\tt
cycleStartTime} is assumed to represent the time $t_s$ at which the current
control function started. This is used along with the current time $t_c$
to compute $d_t$ from
\manIfTeX
$$
        d_t \;=\; t_i - (t_c - t_s)
$$
\manElse
\cverbatim
        d_t = t_i - (t_c - t_s)
@endcverbatim
\manFi
so that the overall sample interval of the control function
remains as close to $t_i$ as possible. However, $d_t$ is limited to be
at least as large as some fraction of $t_i$ (typically 1/2), in order to
prevent the system from being bogged down by too fast a sample interval.
(This is particularly important if the simulator program is running on the
same CPU, since it will have to execute in whatever time is left over.)

{\tolerance=10000
{\tt simAttachRobot()}, called from the planning level,
puts in a call to {\tt rciAttachRobot()}, 
explicitly specifying the communication device to be {\tt sim},
which is a special driver that implements communication with a simulation
program using TCP Internet domain sockets. The {\tt address} field for the
device is set to the ID of the robot to be connected to, and the supplemental
field {\tt addressStr} is set to a string giving other addressing information
used by the {\tt sim} driver to find the appropriate socket connection.
See the section SIMULATOR ADDRESSING, below, for a full description
of what this string looks like and how it is set up.
If {\tt simAttachRobot()} is successful, it 
returns the same index number returned by {\tt rciAttachRobot()}.

}

{\tt simRobotsReady()}, called by the control level task,
returns true if all the (simulated) robots connected to the
RCI task are ready to communicate. This 
can be used as a task wakeup function 
(specified using {\tt rciWakeupOn()}). When the monitor calls
the wakeup function (which it will do when a {\tt SIGALRM} is 
delivered), this function will check to see that all robots attached
to the task are ready (i.e., their simulator program(s)
are ready for interaction). If this is not true, the function simply requests
that another {\tt SIGALRM} signal be delivered to the process later (when
it can try again). The time delay for the ``try again'' signal is taken to be
one half the value of {\tt tcb->interval}.

\manSection{SIMULATOR ADDRESSING}

When the simulator driver {\tt sim} opens a connection to a simulator, it 
needs to determine which target machine and port number to connect
to. It establishes this by the following protocol: 

\manItem{1.} The driver gets the target machine address from a string
passed to it by {\tt simAttachRobot()}.

\manItem{2.} The driver then connects to a multiplexor daemon
(called {\tt RCISimMuxd}) which runs on the target machine and with which all
simulator programs on that machine register themselves. The port
number for this daemon is determined either by looking up {\tt RCISimMux} in
{\filefont /etc/services}, or by using an explicit port number that may
be contained in the information string provided by {\tt simAttachRobot()}.

\manItem{3.}The driver gives the mutiplexor daemon the name of the robot
plus the name of the simulator program, and the daemon returns the
appropriate port number. All simulator programs running on the target machine
register their names, and the names of the robots they are emulating, with the
multiplexor daemon when they first start up. If the connection desired by the
{\tt sim} driver is not available (e.g., no simulator program is
providing emulation for that particular robot, or the connection is busy), the
daemon will indicate this.

\manItem{4.}The port number returned to the driver by the multiplexor 
daemon is used
to make the final connection to the simulator program.

The above protocol requires that the {\tt sim} driver be given the
following information:
(1) the name of the robot, (2) the name of the simulator, (3) the
address of the target machine, and, optionally, (4) a port number with
which to connect to the
multiplexor daemon. {\tt simAttachRobot()} provides this information 
to the {\tt sim} driver in the form of a 
string which has the following format:

\cverbatim
        robotName:simulatorName@@hostName<portNumber> @endcverbatim
\noindent
The port number contained in angle brackets at the end is optional;
if provided, it indicates a port number for the multiplexor.
The host name is an Internet address, in
either symbolic or numeric form. 

{\tt simAttachRobot()} creates this string based on a combination of
default information plus information passed to it by the caller. The caller
can optionally specify the simulator name, the host name, or the port number
through the argument {\tt addressString}. The format of this string is
similar to the one described above; for a full description, 
see {\tt simAddress(5)}.

\manSection{DIAGNOSTICS}
{\tt simAttachRobot()} returns the same errors as {\tt rciAttachRobot()}.

{\tt simScheduling()} returns the same errors as {\tt rciScheduling()}.

{\tt simScheduling()} and {\tt simAttachRobot()} will abort the program
if called from the control level.
\manSection{SIDE EFFECTS}
{\tt simSetTimer()} uses the UNIX signal {\tt SIGALRM}, so other
calls within the program should not use this signal. This includes the routine
{\tt sleep()}; the local routine {\tt nap()} should be used instead ({\tt
nap()} is implemented using the timeout features of {\tt select()}).
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rciScheduling(3)}, {\tt rciAttachRobot(3)}, {\tt find_robot(3)},
{\tt rciWakeupOn(3)}.

\manEnd
\end
