JFORCES Gateway Descriptions

(with Tutorial)

This document provides an introduction to the use and application of JFORCES gateways. It also includes a tutorial with all source code to experiment with two different types of gateways. Click here to go to the tutorial


As a distributed system, JFORCES make expensive use of gateways to communicate with:

Indeed, as shown in Figure 1, even when running stand-alone, at a single workstation, with graphics JFORCES employs a gateway named rcvr (short for receiver) to control communications between the simulation and the simulation.














The separate grey boxes for the simulation and the MMI indicate that the simulation and the MMI can be run on separate machines. All communications between the simulation and the MMI pass through the receiver (rcvr) process. This is to provide communications buffering and prevent user lock-outs when there is a high message flow. The user only interacts with the map (for geographic display) and menus processes, the rcvr runs in the background. Repeated experimentation has proven that the employment in this application increases:

  1. Traffic flow

  2. Fault tolerance, and

  3. User response


The receiver (rcvr) process accomplishes this by acting as a message reformatter and mailman for the graphics and maps processes. While this might at first seem an unnecessary process it offloads network communications from these applications and buffers data, thereby preventing communications delays that have consistently resulted in the menu and map applications when the rcvr process is removed. This results in greater user interface response, and thus to greater user acceptance.


Another important benefit is that this method separates the user interface from the JFORCES core. The satellite gateways can be dropped and restored at will (or at need) while maintaining a consistent simulation. This is a fault-tolerant approach that supports the separation and reattachment of interfaces to live applications, user interfaces, testbeds, and other simulations dynamically. Combined with the on-the-fly reconfigurability of the JFORCES simulation this permits the architecture to accommodate changes to scenarios, tests and exercises for any of the following reasons:


While the discussion so far has focused on user interface applications, it is in no means limited to them. Most JFORCES interfaces to live systems is accomplished via live feeds. This is done to prevent a communications outage one a single (or multiple) systems to delay or stop a test that might need to continue real-time execution to support a wide-ranging test. Figure 2 shows that three separate gateways were used to support the Joint Precision System Development testbed connections to operator workstations. And these were in addition to the UI gateway described above.






Figure 2: Realtime Gateways supporting Operator Interfaces in the JFORCES-based JPSD JTT testbed




Gateways are recommended for:


Gateways are based on series of communications servers and clients. This does not limit the architecture to star systems with a monolithic simulation in the center (although this is a common setup). Instead, any gateway can consist of multiple communications servers and clients and multiple gateways, sims and user interfaces can be linked together by combining these components. In some experiments gateways have been up to 5 steps removed from sensor simulations reporting to them and communications were able to fully support the network.


Gateways can range from simple communications relays to full-blown applications with map interfaces and command and control functionality. For programmers the best method to understand the employment of gateways will be to experiment with a simple system, as described in the next section.


Gateway Tutorial

A sample simulation and two types of gateways are included in the interfaces/simple_sample directory. The overview and the operations of the included simple simulation and gateways is included in each directory. It should be mentioned that the intent was add a third gateway in this directory that would catch and forward messages on a non-JFORCES controlled TCP/IP channel, but as the sample code was developed it was recognized that it would be better to direct programmers to the code in the interfaces/gccs_m directory, which does all of this in an application that is actually used to connect to a GCCS-M workstation.


There are three subdirectories in this directory. The programmer should familiarize himself with these subdirectories in the following order:

  1. stupid_sim. As the name implies, this is a REAL simple simulation consisting of a single aircraft flying east from 40N 105W and providing location updates every second and fictious radar reports every 10 seconds.

  2. self_contained_client – feel free to disagree with the name, but this is a traditional JFORCES client. By this I mean that the client checks into the sim and the sim has application code that updates the client with any information the simulation deems important to this client. All messages received by the client application are sent to the receiver routine of that application.

  3. parasitic_client – This is a different client approach. The client still has to check into the sim. But in this case the simulation sends back an invitation to receive copies of any message type desired. The copies can be of any messages sent by this sim, or received by the sim, or both. This is convenient because the sim needs only one application entry designed for this client style and then various client types can employ this interface, selecting messages appropriate for their needs and filtering them accordingly at the client. But as described below there are several pitfalls that have to be avoided when employing this system.


Each of these directories contains its own README for how to build and run the application. In addition each README includes notes on what messages are passed and what operations should be expected. At the expense of repetition, the highlights of will be repeated here to cover the approach in a single top-level document.


Before proceeding, the following notes should be made to programmers:

  1. Each has a main.c file. This is just a starter file and calls the TCL/TK library that JFORCES employs for communications. While required this file can pretty much be ignored for the purposes of understanding the system.

  2. While we're listing things that can be ignored, each also has a stubs.c. This is nothing other than empty shells required to satisfy otherwise unsatisfied calls from included libraries. Feel free to ignore this file.

  3. Each directory has a app_exec_interfaces.c file. This is a key file that specifies how the executive should call and control the underlying application. These entry points (app_init_, app_simtime_event_loop, app_realtime_event_loop, app_version, app_checkpoint, app_remote_init and app_remote_delete, app_verify_msg_validity, app_debug_interface) are REQUIRED for any application hosted under the JFORCES executive. Their functionality is described in the executive writeup (sent earlier), and they are internally documented. So an overview of each will not be provided here. But the details of how these are used in these applications are as follows:

  1. The application code.


Since the operations, build and running instructions are included in the README in the appropriate directories, that information will not be repeated here. Just be aware that you can start the sim and clients in any order, but check the READMEs to see the messages that you'd expect to see if you start the clients before the exec.


You're also encouraged to start multiple clients of either or both types on the same computer or on other computers communicating with the simulation via the LAN. Instructions on how to set up clients for networked communications are in the client READMEs. But be aware networked operations will not work if prevented by firewalls or other network limitations. Also be aware that currently no more that 16 applications of any type can connect to any server. Also, you can not start multiple servers (e.g. Sims) on the same computer unless you change the ports; a server monopolizes the port on the host.


Tailored (self-contained) versus Parasitic clients.

The programmer must choose to decide whether to employ tailored interfaces or parasitic interfaces. These are NOT exclusive, a client can employ a tailored interface and augment it for specific study needs using parasitic connections for specific messages. The decision of whether to use a tailored or parasitic client should evaluate the following concerns:

  1. Is the information required by the client already included in the messages currently sent by the host (be it a simulation, as in this example, or something else. Some of our interfaces come from the user interfaces and support internet services)? You can find the messages their fields currently supported by the JFORCES application by starting up the JFORCES application, going to System Controls->Debug->Review JFORCES ICD. ICD stands for interface control document. This information comes from the Autogeneration functions, so the message structures are guaranteed to be correct, but the field documentation is at the mercy of the programmer. If the information is not available according to this interface you'll have to develop a custom client.

  2. Are you sure that the application will always be sent (or received)? Some applications only send messages if it knows the information is going to at least one explicit destination. For example, some graphics updates are sent only if it's known that there's at least one active MMI. So the application does not call the send_msg_ function. And only messages sent to this function can be rebroadcast. Generally, you're safe expecting state updates and sensor messages to be sent and available for parasitic copies, on anything else you might need to review the underlying simulation code.

NOTE TO PROGRAMMERS: remember this when developing new applications and call the send_msg_ function if you think any external applications might be interested in the message contents even if the number of destinations that you're application knows about is 0. Also always use the fortran-compatible send functions (those ending in an underscore), not the more primitive messages since the primitive messages might bypass the external parasitic client interface.

  1. Avoid parasitic clients if network loading is a concern. Generally, tailored interfaces are more efficient.