MAK RTIspy API Documentation for HLA Evolved: The simpleTime Example

The simpletime example is a simple C++ example of how to use the time management features of the RTI API. The simpletime federate tries to create a federation and join it. It enables time management in the RTI by becoming both time managed and time constrained. It publishes and subscribes to the BaseEntity object class and registers an object of that class. Using a federation synchronization point, it synchronizes the federation. Then it publishes and subscribes to the WeaponFire and MunitionDetonation interaction classes.

After this initialization process, the federate begins to increase a stored time and position value, update its attribute values accordingly, and, if appropriate, send a fire or detonate interaction. The federate sends the fire interaction when its stored position exceeds a preset value (the phase-line), or you issue a keyboard command instructing the federate to fire. Then a detonation is sent. If no detonations are sent, the federate continues to update its attribute values and increase its time, while regularly printing out its time state information and its stored position.

If you run two or more simpletime federates, each federate discovers the other's object, reflects the other's updated attributes, and receives the other's interactions.

Implementation Details

If you create a federation of two or more simpletime examples, you designate one of them as the master federate. To specify the master federate, use the -m command-line argument, as follows:

simpleTime -m federates

where federates is the numbers of joined federates the master should wait for before initiating federate synchronization. If you want to run the federation execution without synchronizing the federates, run the master federate with the -unManaged argument, which indicates that it should not wait for synchronization before starting to advance time.

The simpletime federate sleeps periodically to keep it from using unnecessary system resources. You can set the sleep time with the -sleepTime time option. A time stepping federate running on a dedicated machine can bypass the sleep steps by starting the federate with -dedicated.

The simpletime and simpletime1516 federates can interoperate using the MAK RTI. Both federates use a narrow string format for the attribute values and tags. The default federation file format is appropriate to the HLA specification for that federate (simpletime uses MAKsimple.fed and simpletime1516 uses MAKsimple.xml). The MAK RTI supports both formats for each of the HLA RTI APIs. However, the MOM specification is different in the two files. If the MOM is enabled in the RID file, then the appropriate federation file must be used.

The federate code must provide the implementation of a Federate Ambassador (an abstract class). The simpletime federate derives from the MAK RTI NullFederateAmbassador class, which is a concrete class definition with an empty body for each Federate Ambassador method. The MyFederateAmbassador class implemented by the simpletime example federate only overrides those Federate Ambassador methods that are necessary for this example.

The main routine of the simpletime example starts by collecting command line arguments that specify the federation name, the federation execution data file (.fed, or for 1516 .fdd or .xml), and the federation type. The code then creates instances of the RTI Ambassador and Federate Ambassador. Before entering the main execution loop the code performs the following steps.

Calls a function that attempts to create a federation execution.
Calls a function to join the federation execution.
Calls a function to publish and subscribe to the object class attributes. This function registers an object instance. It also caches the mapping between the attribute names and the attribute handles.
Registers and issues a synchronization point with the RTI.
Calls a function to publish and subscribe to an interaction class. This call also caches the mapping between parameter names and parameter handles.
Iterates through the attribute handle map to construct an attribute handle value pair set. The value of each attribute is its string name.
The code then enters an execution loop in which it invokes an attribute value update and updates the time state and position of the federate. It sends a fire interaction if you press the Space bar or a preset position is reached. Each execution cycle includes a sleep to pace the updates and to yield the processor. A check of keyboard input allows you to escape the execution cycle.
After the execution loop, the code invokes a function that resigns the federate and attempts to destroy the federation execution.

Compiling the simpletime Example

The example includes project and workspace files for Windows and makefiles for UNIX.

Windows

A solution file (simpletime.sln) appropriate for the compiler version (MSVC ++ 7.1 or 8.0) is installed. The solution file is in ./examples/simpletime/mkwin32. Open the appropriate file in the development environment and build the target(s). The executables simpletime(d).exe and simpletime1516(d).exe are placed in ./examples/simpletime/bin (where "d" indicates the debug version).

The source code files are in ./examples/simpletime/src.

UNIX

The makefile and source files are in ./examples/simpletime/src. Change directory to ./examples/simpletime/src and run make install to build all the targets (or make install targetName to make a specific target). The executables simpletime and simpletime1516 are placed into ./examples/simpletime/bin.

Configuring and Executing the simpletime Example

After you build the simpletime example, the executables and the FED and FDD files will be in the example's bin directory. The simpletime example should use RID settings that enable time management and the rtiexec. The RID file in ./examples/simpletime/bin has the correct settings. If you have RTI_RID_FILE set, make sure that the RID file that it points to is configured for time management.

When you run the example, you can specify the FED file, as follows:

simpletime -fedFile fedFileName.fed

You can run any number of the simpletime example federates. The coordination of the time managed federation requires starting one federate with -m n, which denotes that federate as the master federate and instructs it to wait for n federate object discoveries before registering a synchronization point with the RTI. This ensures that all federates are started and joined before any of them starts advancing time. Each federate registers an object and updates its attributes, and if appropriate, sends an interaction. If two or more simpletime federates are executed, each federate discovers the other's objects, reflects the other's updated attributes, and receives the other's interactions.

To exit, in the console window, enter q.

Source Code

The simpletime code: