PMDG 737NGX SDK
PMDG 737NGX SDK
PMDG 737NGX
Software Developers Kit
Copyright © 2015
PMDG Simulations
All Rights Reserved
This manual was compiled for use only with the PMDG 737NGX simulation for
Prepar3D™ from Lockheed Martin Corporation. The information contained within
this manual is derived from multiple sources and is not subject to revision or
checking for accuracy. This manual is not to be used for training or familiarity with
any aircraft. This manual is not assumed to provide operating procedures for use
on any aircraft and is written for entertainment purposes.
This manual and all of its contents, pages, text and graphics are protected under
copyright law of the United States of America and international treaties.
Duplication of this manual is prohibited. Permission to conduct duplication of this
manual will not be sub-contracted, leased or given.
Lockheed Martin, the Lockheed Martin logo and Prepar3D are registered
trademarks of the Lockheed Martin Corporation. Boeing, the Boeing name and
certain brand marks are the property of The Boeing Company. Some graphics
contained in this manual were taken directly from the simulator and altered in
order to suit duplication on a printed page. All images contained in this manual
were used with permission.
Produced under license from Boeing Management Company. Boeing 737, 737-
600, 737-700, 737-800, 737-900 & Boeing are among the trademarks owned by
Boeing.
You should also be aware that you may not use this simulation software
for any training, pilot familiarization, recurrent training or operational
awareness training.
Please note that this version of the simulation may or may not accurately
represent the actual operation of many different aircraft systems and no
warranty is made to accuracy or correctness.
This simulation may not be used in any public or private display for which
users are charged admission, usage fees or other revenue generating
charges. Nor may the simulation be used in any manner which reflects
poorly on PMDG, PMDG Simulations, Boeing, Boeing’s employees,
suppliers or customers. The SDK associated with this software may not
be used to create interfaces or devices to be used for commercial
training, entertainment or familiarization, nor may any individual or
company sell or use an interface created with this SDK for use in
commercial training, entertainment or familiarization without the interface
also being paired with an SDK Commercial User’s License and a PMDG
737NGX Commercial User’s License provided by PMDG Simulations,
LLC.
Developers who wish to sell software that uses this SDK to interface with
the PMDG 737NGX line of products in an environment outside of the
retail entertainment market must first obtain and sign a license agreement
with PMDG Simulations, LLC for the commercial use of this SDK in their
products.
TABLE OF CONTENTS
We anticipate that other uses for this SDK will come forward that we have
not yet imagined, and we encourage creative parties to reach out to us if
there are specific items that they feel would enhance their ability to
provide after-market products to support the PMDG 737NGX line of
products.
The SDK provides read-only access to a data block containing the state
of most PMDG 737NGX controls and indications. It also allows controlling
the PMDG 737NGX by triggering control events that request operation of
one or more items in the PMDG 737NGX.
The communication between the third party add-on application and the
PMDG 737NGX is done using the Microsoft SimConnect library that
comes standard with Prepar3D from Lockheed Martin. Please refer to the
SimConnect SDK documentation for advice on the creation of a
SimConnect application.
SDK CONTENTS
The PMDG 737NGX SDK includes the following files:
To enable the data communication output, you will need to open the file
737NGX_Options.ini that is located in the folder <P3D
ROOT>\PMDG\PMDG 737 NGX
Once this folder is open, add the following two lines to the bottom of the
file:
[SDK]
EnableDataBroadcast=1
When you release your product to customers, it will be necessary for your
application installation to set this parameter on the customer’s installation,
else they will not see data connectivity between your application and the
PMDG 737NGX.
Your application will use SimConnect to request data from this block. The
contents of this data block are defined by struct PMDG_NGX_Data in the
PMDG_NGX_SDK.h file.
Then, the event dispatch procedure handles the PMDG 737NGX state
data sent by SimConnect:
void CALLBACK MyDispatchProc(SIMCONNECT_RECV* pData, DWORD cbData, void
*pContext)
{
// Receive and process the NGX data block
switch(pData->dwID)
{
case SIMCONNECT_RECV_ID_CLIENT_DATA:
{
SIMCONNECT_RECV_CLIENT_DATA *pObjData =
(SIMCONNECT_RECV_CLIENT_DATA*)pData;
switch(pObjData->dwRequestID)
{
case DATA_REQUEST:
{
PMDG_NGX_Data *pS =
(PMDG_NGX_Data*)&pObjData->dwData;
ProcessNGXData(pS);
break;
}
}
break;
}
}
}
The control event code defines the aircraft control, switch, selector or
knob that is to be operated. The control events are listed in the
PMDG_NGX_SDK.h file.
Example 1: Sending a value via the numeric parameter will tell the
simulation to place the switch/knob/lever/control into a specific position.
All values below 8192 are treated as a numeric position to which the item
being controlled should be placed.
bool CDU_annunOFST[2];
unsigned char CDU_BrtKnob[2];// Position 0...127
MOUSE_FLAG_RIGHTSINGLE
MOUSE_FLAG_MIDDLESINGLE
MOUSE_FLAG_LEFTSINGLE
MOUSE_FLAG_RIGHTDOUBLE
MOUSE_FLAG_MIDDLEDOUBLE
MOUSE_FLAG_LEFTDOUBLE
MOUSE_FLAG_RIGHTDRAG
MOUSE_FLAG_MIDDLEDRAG
MOUSE_FLAG_LEFTDRAG
MOUSE_FLAG_MOVE
MOUSE_FLAG_DOWN_REPEAT
27FEB15 RTM DO NOT DUPLICATE For Simulator Use Only
PMDG 737NGX 0.00.13
MOUSE_FLAG_RIGHTRELEASE
MOUSE_FLAG_MIDDLERELEASE
MOUSE_FLAG_LEFTRELEASE
MOUSE_FLAG_WHEEL_FLIP
MOUSE_FLAG_WHEEL_SKIP
MOUSE_FLAG_WHEEL_UP
MOUSE_FLAG_WHEEL_DOWN
Control Methods:
There are two methods of sending control events to the PMDG 737NGX.
One involves using the PMDG 737NGX data block, and the other involves
sending P3D events to the simulation, where they are picked up and
processed by the PMDG 737NGX.
Which method you choose will depend on your application and preferred
methods. Both will yield the same results.
Method 1 uses the special control data area monitored by the PMDG
737NGX. (This area was described a few pages ago.) The data area is
initially empty. To send an event, your application writes the event ID and
parameter to this data area. The PMDG 737NGX detects non-zero data
and processes the corresponding event, after which it zeroes the control
data area in order to prepare it for future events.
Note that your application should wait until the command area is zero
before placing another command there.
METHOD 1 EXAMPLE:
The connection to the NGX control data area is set up like this:
PMDG_NGX_Control Control;
...
Control.Event = 0;
Control.Parameter = 0;
hr = SimConnect_AddToClientDataDefinition (hSimConnect,
PMDG_NGX_CONTROL_DEFINITION,
0, sizeof(PMDG_NGX_Control), 0, 0);
Code in the dispatch procedure keeps the data synchronized to the NGX:
case CONTROL_REQUEST:
{
// keep the present state of Control area to know if the server
had received and reset the command
PMDG_NGX_Control *pS = (PMDG_NGX_Control*)&pObjData->dwData;
Control = *pS;
break;
}
Note how the code checks that the NGX has no pending events to
process by checking that Control.Event == 0.
METHOD 2 EXAMPLE:
This is how the direct event triggering is set up:
static enum EVENT_ID {
EVENT_LOGO_LIGHT_SWITCH,
EVENT_FLIGHT_DIRECTOR_SWITCH,
EVENT_HEADING_SELECTOR,
};
...
//EVT_OH_LIGHTS_LOGO
hr = SimConnect_MapClientEventToSimEvent(hSimConnect,
EVENT_LOGO_LIGHT_SWITCH, "#69754");
//EVT_MCP_FD_SWITCH_L
hr = SimConnect_MapClientEventToSimEvent(hSimConnect,
EVENT_FLIGHT_DIRECTOR_SWITCH, "#70010");
//EVT_MCP_HEADING_SELECTOR
hr = SimConnect_MapClientEventToSimEvent(hSimConnect,
EVENT_HEADING_SELECTOR, "#70022");
After this, the logo lights can be switched by triggering the P3D event:
SimConnect_TransmitClientEvent(hSimConnect, 0,
EVENT_FLIGHT_DIRECTOR_SWITCH, MOUSE_FLAG_LEFTRELEASE,
SIMCONNECT_GROUP_PRIORITY_HIGHEST,
SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY);
CONCLUSION
Using the information and tools provided by this SDK, a skilled developer
should be able to control just about any switch, knob, lever or control.
To help you understand your responsibilities when using this SDK, some
of the key points will be digested here in this section, but this digest is by
no means complete. You must read and comply with the full EULA listed
below or risk litigation by PMDG Simulations, LLC. to protect our property
and the limitations we have placed on you.
If you have any questions regarding the use of the application you have
created, please contact us! We will be happy to provide you with
feedback to keep us all working toward the common goal of better
simulation for flight simulation enthusiasts!
TERMINATION
The license will terminate automatically if you fail to comply with the
terms, conditions, or limitations contained in this EULA, including the
payment of applicable license or other fees. You may terminate this
EULA at any time (with no obligation on the part of PMDG Simulations,
LLC.) by destroying all copies of the Software, deleting any copies of the
Software from your hard drives, ceasing all use of the Software and
documentation; and providing satisfactory proof to PMDG Simulations,
LLC. that you have done so.
UPGRADES/ADD-ONS
If the Software is designated by PMDG as an Upgrade or Add-On
product, you may only use the Software if you are also currently a
licensed user of the base product to which the Upgrade or Add-On
applies. Unless the PMDG documentation for an Upgrade or Add-On
specifically provides, you shall not separate upgrade products from base
products, nor transfer them separately. PMDG reserves the sole and
exclusive right to set its policies and prices regarding updates, upgrades
add-ons and enhancements. All other terms of this EULA apply with
equal force to any such Upgrades.
GENERAL/MISCELLANEOUS CLAUSES
This EULA shall be governed by and construed under the substantive
laws applicable to the United States of America. If any provision of this
EULA is held to be unenforceable, the remaining provisions shall remain
in full force and effect.