Export (0) Print
Expand All

Microsoft ESP Technical Articles:

Monitoring AI Objects

Jessica Zorich

Microsoft Corporation

September 2008

Significance of the Sample

The Monitoring AI Objects Code Sample demonstrates how to retrieve simulation data from a running Microsoft ESP simulation using the SimConnect API. The functionality of the sample lays the groundwork for many practical applications of the SimConnect API, some examples of which include:

  • Storing data collected from a session for:
    • Replay later as an After Action Review component of training
    • Statistical analysis
    • Creating a graphical representation of a session
  • Pushing simulation variable data back into the simulation in order to:
    • Give waypoints to AI objects
    • Place simulation objects directly
    • Affect custom panel gauges

Read more about the extensibility of this sample in the Do More with Monitoring AI Objects section.

Applies To

The guidance in this article applies to the following Microsoft products:

  • Microsoft ESP 1.0
  • Microsoft Flight Simulator X

Requirements

To build the sample solution provided, one of the following is required:

C# .NET

Monitoring AI Objects was developed using C# and the managed wrapper that enables SimConnect clients to be written with .NET languages. All of the same SimConnect features are available through the unmanaged C++ version of the API. Please see Programming SimConnect Clients using Managed Code in the SimConnect SDK documentation for more information on this topic.

SimConnect API Calls

The Monitoring AI Objects sample makes the following SimConnect API calls:

AddToDataDefinition SDK link
SubscribeToSystemEvent SDK link
SetSystemEventState SDK link
RequestDataOnSimObjectType SDK link article bookmark
RequestDataOnSimObject SDK link article bookmark

The bolded entries above are discussed directly in this article.

Overview of the Sample Code

The core functionality of the sample is contained in SimConnect_Monitoring_AI_Objects.cs; snippets in this article are taken from that source file. For a screenshot of the running sample, see figure 1. The focus of the following code discussion is on Requesting Data on Simulation Objects by Type, Requesting Data on Simulation Objects and the relationship between these SimConnect API calls.

Monitoring AI Objects Screenshot

Figure 1. Screenshot of running Monitoring AI Objects.

Prerequisite Knowledge and Setup

The following concepts and setup tasks are essential for the functionality of the Monitoring AI Objects sample:

Preparing Structures for Interaction with SimConnect SDK link
Creating a SimConnect Object and Receiving SimConnect Messages SDK link
Registering Data Structures with SimConnect SDK link
Subscribing to and Activating System Events SDK link, SDK link

All of the above are demonstrated in the sample code, but are not within the scope of this article. Refer to the complete code and the respective sections of the SDK documentation for each of these topics as needed.

The Relationship between RequestDataOnSimObjectType and RequestDataOnSimObject

Key concepts of the Monitoring AI Objects sample include the differences and similarities between the RequestDataOnSimObjectType and the RequestDataOnSimObject SimConnect API calls.

Before we can periodically request simulation variables on a set of simulation objects, we must obtain the object IDs of all the objects we wish to track. RequestDataOnSimObjectType allows us to request the object IDs of all simulation objects within a certain radius of the user’s craft. Once we have a list of object IDs, we can use RequestDataOnSimObject to set up recurring transmission of simulation variables associated with each ID.

RequestDataOnSimObjectType prompts a one-time transmission of object IDs, while RequestDataOnSimObject initiates recurring transmissions of simulation variable data on a schedule defined by the call. Figure 2 illustrates this relationship:

Figure 2. RequestDataOnSimObjectType and RequestDataOnSimObject High-Level Diagram

Cc974114.High-LevelDiagram(en-us,MSDN.10).png

Requesting Data on Simulation Objects by Type

To create the list of object IDs for which to receive data we make a single SimConnect API call:

simconnect.RequestDataOnSimObjectType(DATA_REQUESTS.REQUEST_AI_OBJECT_ID_BYTYPE, DEFINITIONS.AI_Entity_Definition, MONITOR_RADIUS, SIMCONNECT_SIMOBJECT_TYPE.AIRCRAFT);

The following table discusses each parameter in this sample RequestDataOnSimObjectType call from line #304 of the sample:

Parameter Value in Sample Call SDK Parameter Name Parameter Description
DATA_REQUESTS.REQUEST_AI_OBJECT_ID_BYTYPE RequestID Indicates to the sample, on callback, which data request is being replied to. This is a request ID from the DATA_REQUESTS enumeration defined in the sample.
DEFINITIONS.AI_Entity_Definition DefineID Specifies the client-defined data definition that has been registered with the managed wrapper marshaler. This tells SimConnect what data we are requesting and how to organize the repsonse.
MONITOR_RADIUS dwRadiusMeters

Defines how far (in meters) away from the user craft to poll for AI craft. Defined as a constant in the sample:

const uint MONITOR_RADIUS = 200000;

SIMCONNECT_SIMOBJECT_TYPE.AIRCRAFT type Specifies what type of simulation objects for which we want to be notified.

RequestDataOnSimObjectType is called again each time we change which type of craft we want object IDs for.

Replies from SimConnect to RequestDataOnSimObjectType are handled in the sample by the SimConnect_OnRecvSimobjectDataBytype event handler; it is there that we begin to request periodic data updates on the existing list of object IDs.

Requesting Data on Simulation Objects

Once we have a list of object IDs, the next step is to set up the request for recurring transmission of data (in this sample: Lat/Long/Alt/Pitch/Bank/Heading) for each craft that we added to our list. In the case of the user’s craft we make the following call:

simconnect.RequestDataOnSimObject(DATA_REQUESTS.REQUEST_USERAIRCRAFT_DATA, DEFINITIONS.PositionData_Definition, SimConnect.SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD.SECOND, SIMCONNECT_DATA_REQUEST_FLAG.DEFAULT, 0, 0, 0);

The following table discusses each parameter in this sample RequestDataOnSimObject call from line #439 of the sample:

Parameter Value in Sample Call SDK Parameter Name Parameter Description
DATA_REQUESTS.REQUEST_USERAIRCRAFT_DATA RequestID The ID for the user craft. This specifies, on callback, that the user craft is being reported on.
DEFINITIONS.PositionData_Definition DefineID Specifies the client defined data definition registered with the managed wrapper marshaler. This tells SimConnect what data we are requesting and how to organize the repsonse.
SimConnect.SIMCONNECT_OBJECT_ID_USER ObjectID While parameter one of RequestDataOnSimObject serves to identify data on callback for use within the code of the sample, this third parameter is the constant defined by SimConnect that we use to request user craft reporting from SimConnect.
SIMCONNECT_PERIOD.SECOND 0 Period interval

Let’s consider the fourth and seventh parameters in combination:

SIMCONNECT_PERIOD.SECOND is from an enumeration defined within SimConnect. It specifies how frequently SimConnect should callback with new data.

The middle 0 is the integer scaling factor on the SIMCONNECT_PERIOD enumeration value chosen. Zero means that scaling is off, and data is to be transmitted every period (in this case, every second). A scaling factor of 5 would request transmission every five seconds, and so on.

SIMCONNECT_DATA_REQUEST_FLAG.DEFAULT Flags These flags are not used by the SimConnect managed wrapper. Pass in the default value.
0 0 Origin limit

Let’s look at the sixth and eighth parameters in combination:

The first 0 specifies the delay before the first transmission of data is to occur. It is an integer scaling factor of the SIMCONNECT_PERIOD frequency. The default value of zero indicates that data transmission is to begin immediately.

The final 0 specifies the total number of transmissions to occur.

Note that while parameters six and seven are integer scaling factors of SIMCONNECT_PERIOD, parameter eight is a simple integer count. The default value of zero specifies endless transmission of data.

Replies from SimConnect to RequestDataOnSimObject are handled in the sample by the sample’s SimConnect_OnRecvSimobjectData event handler; it is there that we update the list view of the sample with live data from the simulation.

Do More with Monitoring AI Objects

The functionality of Monitoring AI Objects can be extended to receive any combination of the 200+ available simulation variables. One possible extension of the sample would be to graph simulation data, thereby creating a graphical representation of a session.

Another option is to store data for later retreival in the context of an After Action Review. For instance, you could use the SetDataOnSimObject SimConnect call to reposition the user craft using data collected from a previous session. The user craft could be repositioned to a critical point in a past session (for example, right before a landing attempt) in order to provide a quick retry mechanism for a training scenario.

AI craft can also be controlled based on the data generated by the user’s craft or from any other source. Try creating an AI craft with AICreateNonATCAircraft, releasing it from AI control with AIReleaseControl, and then placing it directly with SetDataOnSimObject.

Conclusion

The Monitoring AI Objects sample demonstrates the SimConnect API facilities for obtaining data from a running ESP simulation. This sample successfully achieves the following:

  • Requests object IDs and basic data for all AI craft of a certain type
  • Uses the list of IDs to request periodic transmission of simulation data by object ID
  • Receives and displays data (including Lat/Long/Alt/Pitch/Bank/Heading) in the sample client

To take the next step, refer to the SimConnect SDK documentation and learn about the many other functionalities of the powerful SimConnect API.

Show:
© 2014 Microsoft