simSupport(3)

NAME
simScheduling, simSetTimer, simAttachRobot, simRobotsReady -- RCI simulation mode support functions.

USAGE
#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;

ARGUMENTS

td --
    Pointer to task descriptor.

interval --
    Wakeup interval (in milliseconds).

cycleStartTime --
    Optional argument specifying the time at which the current control cycle started.

name --
    Name of the robot.

addressStr --
    Optional argument giving additional information identifying which robot simulator to connect to.

RESTRICTIONS
simScheduling() and simAttachRobot() must be called from the planning level.

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.

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

simSetTimer(), called from the control level, schedules a 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 startup function and then once during each control function). The delay (d_t) between when the function is called and when the signal is delivered is computed as follows: (a) If cycleStartTime is given as NULL, then d_t is set directly equal to the interval time (t_i) given by interval. (b) Otherwise, 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
        d_t = t_i - (t_c - t_s)

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.)

simAttachRobot(), called from the planning level, puts in a call to rciAttachRobot(), explicitly specifying the communication device to be sim, which is a special driver that implements communication with a simulation program using TCP Internet domain sockets. The address field for the device is set to the ID of the robot to be connected to, and the supplemental field addressStr is set to a string giving other addressing information used by the 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 simAttachRobot() is successful, it returns the same index number returned by rciAttachRobot().

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 rciWakeupOn()). When the monitor calls the wakeup function (which it will do when a 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 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 tcb->interval.

SIMULATOR ADDRESSING

When the simulator driver 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:

1.
     The driver gets the target machine address from a string passed to it by simAttachRobot().

2.
     The driver then connects to a multiplexor daemon (called 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 RCISimMux in /etc/services, or by using an explicit port number that may be contained in the information string provided by simAttachRobot().

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 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.

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 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. simAttachRobot() provides this information to the sim driver in the form of a string which has the following format:

        robotName:simulatorName@hostName<portNumber>

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.

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 addressString. The format of this string is similar to the one described above; for a full description, see simAddress(5).

DIAGNOSTICS
simAttachRobot() returns the same errors as rciAttachRobot().

simScheduling() returns the same errors as rciScheduling().

simScheduling() and simAttachRobot() will abort the program if called from the control level.

SIDE EFFECTS
simSetTimer() uses the UNIX signal SIGALRM, so other calls within the program should not use this signal. This includes the routine sleep(); the local routine nap() should be used instead (nap() is implemented using the timeout features of select()).

SEE ALSO
rciScheduling(3), rciAttachRobot(3), find_robot(3), rciWakeupOn(3).