1
Download User Guide FSX AI Spotter
Transcript
geniX Software Development User Guide FSX AI Spotter for FSX Version 1.5.X Date: 2/6/2015 Table of Contents 1 ABOUT THIS GUIDE ................................................................................................................................ 3 1.1 2 3 4 5 WHO SHOULD USE IT ............................................................................................................................. 3 INTRODUCTION ....................................................................................................................................... 4 2.1 PURPOSE ................................................................................................................................................ 4 2.2 SCOPE .................................................................................................................................................... 4 2.3 SYSTEM ORGANIZATION ........................................................................................................................ 5 2.4 HISTORY ................................................................................................................................................ 5 DESCRIBING THE SYSTEM ................................................................................................................... 7 3.1 KEY FEATURES ...................................................................................................................................... 7 3.2 PROGRAM INVENTORY ........................................................................................................................... 7 3.3 ENVIRONMENT ....................................................................................................................................... 8 3.4 SYSTEM OPERATIONS ............................................................................................................................ 9 STARTING FSX AI SPOTTER ............................................................................................................... 11 4.1 FIRST-TIME USERS ............................................................................................................................... 11 4.2 REGISTER FSX AI SPOTTER ................................................................................................................. 12 4.3 EXIT FSX AI SPOTTER ......................................................................................................................... 13 STEP BY STEP INSTRUCTIONS FOR USING FSXAIS .................................................................... 14 5.1 INSTRUCTIONS ..................................................................................................................................... 14 5.2 ERRORS AND MALFUNCTIONS ............................................................................................................. 16 5.3 FSXAIS SETTINGS WINDOWS ............................................................................................................... 19 5.4 FSXAIS AI AIRCRAFT DATABASE....................................................................................................... 21 FSX AI Spotter User Guide Copyright 2015 Page 2 of 24 1 About this guide This document is divided into the following chapters: Chapter 2, “Introduction”, that expose a briefing of the program. Chapter 3, “Describing the system”, that illustrates the general requirements Chapter 4, “Starting FSX AI Spotter”, that describe a first start of FSXAIS Chapter 5, “Step by step instructions for using FSXAIS”, that contains detailed instructions on how deal with the program. In this document, Microsoft “Flight Simulator X” ® and Microsoft Windows ® are registered trademarks of Microsoft Corporation. 1.1 Who Should Use It This guide is intended for users of different degrees of knowledge and experience with the following applications: MS-Windows Operating Systems MS-FSX (release fsx-sp120070510-2038) MS-SimConnect.dll installed (release 10.0.61242.0 minimum) This guide assumes that you have some knowledge of the operating of the above programs and applications. For more information, see the appropriate related documentation. FSX AI Spotter User Guide Copyright 2015 Page 3 of 24 2 Introduction 2.1 Purpose FSXAI Spotter (FSXAIS) is a software add-on for MS-FSX. This software can create AI Aircraft in departure and arrival conditions simply by loading raw text “traffic files”. Moreover, FSXAIS is able to call any custom Windows Console Application in order to generate these traffic files (for example, an application that connect on internet and arranges for the traffic files based on live airport information), or load, at configurable interval the traffic files itself (for example, traffic files generated by a more complex Windows Application). Purpose of this document is to provide all information on how interact with the program. 2.2 Scope Scope of this guide is to provide a panoramic view of how to play with FSXAIS. Further, some mandatory prerequisites are listed in order to run the program. FSX AI Spotter User Guide Copyright 2015 Page 4 of 24 2.3 System Organization This document applies to: FSX AI Spotter for FSX Version 1.5.x All builds 2.4 History Rel 1.5.0 Now the user can switch from prevalently IATA code aircraft type generation to ICAO one thanks to an utility that modifies aircraft.cfg file adding a IATA model code field. Rel 1.4.4 Capability to convert IATA code (provided by external connectors) to FSX used ICAO one. Max rows to get from external connectors are now 128. Rel 1.4.1 The complete departure/arrival roaster now is visible unchecking the “Full Log” flag. Rel 1.3.1 Improved GUI interface, with some useful info on A/C creation, flight plan assignment and arrival flights queueud. Introduced “separation” concepts on arrival flights. Now is it possible to create arrival flights each x seconds one from the other. This to avoiding multiple A/C created in the same sky zone. Introduce alerts for take-off and landing aircrafts providing destination runway info, too. Try to fix SimConnect server problem on slow PC. The aircraft are created right, but some mandatory info are missed by Microsoft. FSXAIS try to fix these in order to provide better A/C status retrievement. FSX AI Spotter User Guide Copyright 2015 Page 5 of 24 Rel. 1.1.6 Old log files are automatically deleted from the folder. From now on, FSXAIS will not use A/C Tail as search-key but it will try to use all the airline variants of the same A/C. Example, if an airport schedule presents more than one Ryanair B738, and FSX has more than one Ryanair B738 “Title” A/C to provide, the program will use one of each to fill the schedule. Rel. 1.0.0 First public release of the program. FSX AI Spotter User Guide Copyright 2015 Page 6 of 24 3 Describing the System 3.1 Key Features FSXAIS is indicated for people loving airports environments and air-watching in the world of MSFSX (AI Spotters…yes!). The program, using the user installed AI Aircraft, is able to create both departure and arrival flights in a certain airport, starting from a couple of simple text (Comma Separated Values) files describing the flights themselves. In order to perform this kind of works, the AI aircraft must have the appropriate values for a couple of properties in the aircraft.cfg file. An alerting system will provide informations on aicraft landing and departing directly into MSFSX ® main window. 3.2 Program Inventory FSX AI Spotter is composed by the following files: File Note Ais_traffic.xml XML raw DB containing airline traffic information Ais_aircrafts.xml XML raw DB containing user AI aircraft available in FSX Midas.dll Internal library of FSXAIS Airlines.xml XML raw DB containing real world airline information (not used in 1.x) Standard.xml FSX standard xml template for flight-plan (not used in 1.x) FSXAIS.exe.manifest .net extension used to load the RTM version of Simconnect.dll FSXAIS.exe Main FSXAIS executable FSX AI Spotter User Guide Copyright 2015 Page 7 of 24 FSXAIS.ico Main FSXAIS icon FSXAIS.ini Main FSXAIS configuration file FSXAIS.sub Internal file for aircraft substitution (filled with samples) Standard.org FSX standard template for flight-plan Iata-icao2.cds File for matching ICAO code (used by FSX) with IATA code (used sometimes by Airport Data Providers) when available/defined Release notes FSXAIS latest release notes User Manual FSXAIS user manual That must be all togheter into the destination folder selected by the original setup. 3.3 Environment To run FSXAIS is necessary: MS-Windows Me / XP / 2000 / Vista / Win 7 Operating system MS-SimConnect.dll installed (release 10.0.61242.0 minimum). A running MS-FSX SP1 A default printer assigned into MS-Windows Minimum 5 Mb of free disk space About 7Mb of free RAM memory FSUIPC.dll (from P.Dowson) 4.5 minimum We assume also that the system hardware configuration where FSXAIS will run are adequate to run MS-FSX first. FSX AI Spotter User Guide Copyright 2015 Page 8 of 24 3.3.1 AI aircraft.cfg recommendation In order to display the best aircraft for a certain flight, FSXAIS needs that: 1. atc_parking_codes is equal to the effective 3-letters ICAO code of the aircraft’airline. 2. atc_model is equal to the effective 3-letters ICAO code for the aircraft1. When more than one airline-ac type aircraft is present in FSX, the assigning phase of an aircraft “title” for a certain flight is based on a cyclical algorithm. In this manner, at list one different ac title will be assigned for each different flights. Note: FSX AIS has an utility that can add a new couple of key-value in the aircraft.cfg, “iata_model”, under General section. Using this value, some aircraft type could be more specific (ie ICAO code hasn’t the definition for the 757-200 winglet as IATA in the 75W value). Note: For those people that seems give low importance expecially to atc_parking_code, we remember that aspects of a full correct behaviour of the MS-FSX is related on HOW are corrects the aircraft.cfg files along textures and other things. Infact, these configurations will affects FIRST your FSX AI environment, next FSXAIS behaviour. 3.4 System Operations FSXAIS must be started after MS-FSX but, only for configuration purpose, it can be started alone. This case is when you need to rebuild FSXAIS internal DB of AI Aircraft configuration or install a connector. 1 A good source for A/C codes is http://homepages.mcb.net/bones//Flight_Sim/data/FS_Aircraft_Codes.htm FSX AI Spotter User Guide Copyright 2015 Page 9 of 24 3.4.1 Connectors Connector is the way to define an external Windows Console Application that FSXAIS can execute at a certain interval in order to produce the traffic files. This operation is what we indicate as online mode. Otherwise, in the offline mode, FSXAIS simply load the traffic files at certain interval; in this mode, the user could provide himself to generate the traffic file that the program will load. From the FSXAIS perspective, the master key in such traffic files is the couple ICAO airline code (3 letter)+Flight number. This information is almost used in the whole program. FSX AI Spotter User Guide Copyright 2015 Page 10 of 24 4 Starting FSX AI Spotter 4.1 First-time Users Note: As for the Installation Guide, to start FSXAIS click twice with the mouse on the program desktop icon. The main FSXAIS interface is the following: The figure show the main FSXAIS window Starting from the left, from top to down, we have: FSX Link info box: here are the information on the loaded version of FSUIPC and SIMCONNECT Log view panel: here are the program log lines written during the running of the application. Start button: this button will start the FSXAIS operations. The button will be enabled only when the airport icao code is given, togheter the two connection to FSX. Input ICAO code box: here the user must insert the airport ICAO code where the traffic files must be generated Settings button: this button will display a window with FSXAIS related settings. FSX AI Spotter User Guide Copyright 2015 Page 11 of 24 A/C DB: this button will display the panel that report the current AI Aircraft located on the FSX DPE Settings: This button will show the window with Data Service Provider (connector) settings. Note: The very first time the program starts, it will going to populate the internal AC DB of AI Aircraft first. A window will ask for this: click “Yes” and wait for the DB creation A status bar is also present; during the simulation it will be filled with useful operational informations. 4.2 Register FSX AI Spotter FSXAIS is first released as shareware form, with the following limitation: 2 1. Max 3 flights potentially generated In order to unlock the above limitations, you must have registered the programs buying a personal license from the vendors. Having these data, click on the Settings button, next on the Register button. A dialog box will appears: Inputs for the register windows Type the user-id and serial number you get into the appropriate fields and then click on the Ok button: if the data are valid, your copy of FSXAIS is well registered. Thank you! 2 This means that FSXAIS will count each flight in the traffic files as valid regardless of the creation or not in FSX FSX AI Spotter User Guide Copyright 2015 Page 12 of 24 4.3 Exit FSX AI Spotter To exit FSXAIS program, click on the standard Windows close button, on the upper left corner of FSXAIS main window. Warning: FSX AI Spotter must be closed before MS-FSX ® FSX AI Spotter User Guide Copyright 2015 Page 13 of 24 5 Step by Step Instructions for using FSXAIS In the following chapter, we’ll assume that MS-FSX is up and running: so, before continue reading this user guide, please START FSXAIS BY DOUBLE-CLICKING ITS DESKTOP ICON 5.1 Instructions Referring to the main FSXAIS window, edit the ICAO code text of the airport where you stay located with your vehicle (here KJFK) and next click on the Start button. FSXAIS will start the routine for the connector (if the online mode is enabled), next the routine for cancel all “static” BGL related aircraft, next it will collect the FSX-Time (UTC). The routine from the connector will produce the traffic files and their content displayed in the log window: The main (working) FSXAIS window Depending on the number of aircrafts to be displayed, FSXAIS will work like the following screenshot. One for the departure roaster and one for the arrival. FSX AI Spotter User Guide Copyright 2015 Page 14 of 24 The Log view display informations about operationals routine of FSXAIS. Each departure flight is displayed using the best matched AI Aircraft located in FSX; if no such aircraft is available, that flight will be not visualized. When it is the time to depart, FSXAIS will assign the related flight plan to that aircraft. Main FSX Window with departures working. Each arrival flight is displayed using the best matched AI Aircraft located in FSX; if no such aircraft is available, that flight will be not visualized. Depending on the “A/C proximity” selected (see “Settings” paragraph for further info), FSXAIS will try to display the arrival flight at a distance from the airport respect to the flightplan and according to the arrival time scheduled (more or less). 5.1.1 Status bar info The status bar info are divided into two areas. At the left there is the current MS-FSX ® simulator time plus the UTC shift as they coming from the simulator itself. At the right there are three informations live: AC: aircrafts created (dep+arr). FP: flightplans (created) and assigned to aircrafts. In queue arrivals: if the “Separation” value is greater than 0, all arriving aircrafts will be forced in a queue. Each time interval (separation value) one aircraft will be created and visualized in the FSX when needed. FSX AI Spotter User Guide Copyright 2015 Page 15 of 24 5.1.2 Pausing FSXAIS After start working FSXAIS, the Start Button become Stop button. This Stop button is useful when you need to stop working FSXAIS but not the actual AI traffic in the FSX generated by the program, that remain alive. 5.2 Errors and Malfunctions FSXAIS is able to detect some errors and display messages on the Windows desktop. Some windows will be displayed if one of three important files are missed in the main FSXAIS directory: ais_aircrafts.xml – A box window will appear with the message “AI Aircraft DB not exists! Exiting...” Standard.org - A box window will appear with the message “FSX Standard template plan not exists! Exiting...” ais_traffic.xml - A box window will appear with the message “AI Traffic DB not exists! Exiting...” After the message box, the application will exit. Another message box could be displayed in the case of wrong registration code (or user): “Not a valid registration”. In this case, the program will continue to work in the shareware mode. A warning will be written in the DPS Setting Window, in the space for the connector information if these are missed once loaded a connector program: “Warning! No info from connector. Please re-load”. This error could put FSXAIS in the offline mode; the error could be related to the connector itself. FSX AI Spotter User Guide Copyright 2015 Page 16 of 24 5.2.1 FSX AI Spotter Messages These messages could be displayed in the FSXAIS log space: Message Where Why Connector Execution problem ! Problem encounter during execution of the General error. The connector application during its installation phase executable could be (“Load” button in the DPS setting window) the primary cause of this. Error retrieving FSX current state During the checking of FSX freezed state before FSXAIS is not able to any important phase of the program get the current freezed status of FSX. FSX Freezed. Wait next interval. Error retrieving FSX current time! During the checking of FSX freezed state before FSX is not in Ready to any important phase of the program fly mode3. During the checking of FSX time, each minute Heavy load on FSX SimConnect interface Error receiving AC_id for Creation of parked aircraft (Departure phase) or Heavy load on FSX creation of enroute aircraft (Arrival phase). SimConnect interface, no AC-Id assigned4 FP NOT assigned Flightplan not assigned due a problem with FSX Heavy load on FSX SimConnect interface Error calling SetTrafficDensity(0)! Problem aencounter at first start of FSXAIS FSUIPC related call failed The user clicked the “Stop” button or an error was Normal behaviuor in encountered the most cases. During the offline works No traffic files to load. Connector Execution problem: Problem encounter during execution of the General error stopping simulation... connector application during FSXAIS running Stopping simulation offline work suspended: missing text files 3 4 when FSX is loading, or reloading a flight or aircraft or scenery. FSXAIS will try to assign the correct ID as the aircraft, despite this error, is EVEN created. FSX AI Spotter User Guide Copyright 2015 Page 17 of 24 Connector Timeout: stopping Problem encounter during execution of the The remote Web Data simulation... connector application during FSXAIS running Provider didn’t respond in timely manner. Probably Network connection Error: Problem encounter during execution of the The connector works stopping simulation... connector application during FSXAIS running fine but no traffic files where produced; probably a Web Data Provider remote problem. 5.2.2 SimConnect specialized messages Below the table the display FSUIPC (error) messages that can appears in the FSXAIS log space: Message Why SIMCONNECT_EXCEPTION_CREATE_OBJECT_FAILED FSX is not able to load/create the AI Aircraft selected by FSXAIS. Sometimes, for A/C enroutes, this issue is resolved setting a lowest AC proximity value. SIMCONNECT_EXCEPTION_OBJECT_ATC The airport where is FSXAIS working doesn’t have ATC Parking space to accommodate the aircraft SIMCONNECT_EXCEPTION_OBJECT_CONTAINER The A/C is installed in FSX but is not detected. Restarting FSX should resolve the problem. Try also to verify the correct texture folder for that aircraft. Warning: All the SIMConnect error have the form SIMCONNECT_EXCEPTION_xxxxxx, where xxxxxxx is a message string ov variable length. The table above lists only those messages that are most common 5 5 Please report to geniX technical support. FSX AI Spotter User Guide Copyright 2015 Page 18 of 24 5.3 FSXAIS settings windows In this chapter we are going to explain the various optional settings of FSXAIS. 5.3.1 (FSXAIS) Settings Below the screen shot of the dialog box: FSXAIS general settings window The A/C proximity selector tells FSXAIS the distance (more or less), respects the flight-plan, where it should create the enroute aircraft that will landing. The creation is made according with the arrival time for the flight. Note: FSXAIS doesn’t take in account any third party application that manage arrival flight nor FSX policy for landing aircraft. This means that the arrival time could be modified from other programs (such as AISmooth) or FSX AI-Algorithm itself. The offline mode flag permits to tell FSXAIS how manage flights creation: If this flag is checked, FSXAIS will use the timer interval (see DSP settings) only to load the traffic files without calling any external connector. The user is responsible to provide (in any way) such files to FSXAIS.6 The Separation value is used to avoid “groups” of aircraft in the same sky zone. All the arriving flights/aircrafts will be created with the interval selected here. 6 geniXsoft provide for free the Technical Specs for the connector and the traffic files format FSX AI Spotter User Guide Copyright 2015 Page 19 of 24 The clear and save log variable determines how many lines the log windows will contains before clear and save the log7 in a text files. 5.3.2 DPE settings Below the screen shot of the dialog box: FSXAIS Data provider configuration settings window This windows is mainly for “connectors” configuration. The connector configuration box permits the input of User and Password couple for access Data Provider on the internet. These values are passed to the external connector when called. The Max Row for query – that can be optional – is used in the case the connector can ask the DPE for a certain number of flight instead of all. The connector call interval defines the minutes between two consecutive connector call. The connector timeout defines how many seconds FSXAIS should waits before declare a connector timeout. The connector informations box groups the connector data, such as filename and version. The filename for departure and arrivals normally are filled by the connector itself during the loading phase. In order to load a connector, click on the “Load” button. A standard Windows File-Open dialog will appear. Select the connector executable and click “Ok”. The DPE Settings window will filled with the connector name, the release note and the connector traffic files names. 7 Log files are deleted on per-day basis. FSX AI Spotter User Guide Copyright 2015 Page 20 of 24 FSXAIS Data provider connector settings If no connector is specified, the standard names are used8: - sched.txt for departure flight - enrou.txt for arrival flights 5.4 FSXAIS AI Aircraft Database FSXAIS own an internal database of the AI Aircraft that are installed in the user’ FSX simulator. The creation of this aircraft is obviously fundamental for the FSXAIS program. The following chapter will explain the use of the A/C DB windows 5.4.1 A/C DB window Below the screenshot of the A/C DB window: 8 This name must be used in case of user provided application that wish to dela with FSXAIS (offline mode) FSX AI Spotter User Guide Copyright 2015 Page 21 of 24 FSXAIS A/C internal DB settings The magic button is the “Rebuild A/C DB” but it is important also the value for the include a/c with less of xx bitmaps (.bmp/.dds), that the user can set in order to tell FSXAIS to search and include only aircraft wich texure folder count a certain number of bitmap files. In this manner, the AI aircraft DB will contain only the lightest aircraft and so reduce the FSX work to diplay them. The “A/C Type substitutions” is an utility that is used to match the data coming from the external source (by DPE connector) with those of user AI aircraft. The “Enforce iata” setting enable the program to try to get an a/c type suitable for the dep/arr route, searching first for a iata_model value. Infact, we can resume the way FSXAIS get the appropriate A/C type in this way, depending on the above setting (Activate) on or off. For example, the external provider codes a JetBlue Airline (JBU) flight using the a/c type 32A (IATA A320 Sharklets model): what’s happens in FSXAIS? Activate = checked 1. The string UAL-32A is searched in the subst table. If found, the alternate couple is used (for example, UAL-A320). FSX AI Spotter User Guide Copyright 2015 Page 22 of 24 2. If the above point fail, the program will search in the A/C DB an aircraft with the attribute iata_model=32A and atc_parking_codes=UAL. If found, the related “Title” is used to create the route. 3. If the above point fail, the program will search in the A/C DB an aircraft with the attribute atc_model=A320 and atc_parking_codes=UAL. If found, the related “Title” is used to create the route. 4. If the above point fails, FSXAIS will write a row in the log with the missing a/c (sometimes with the a/c description) and a new row in the “Subst” table (UAL-A320=UAL-000). Activate = unchecked 1. The string UAL-32A is searched in the subst table. If found, the alternate couple is used (for example, UAL-320). 2. If the above point fail, the program will search in the A/C DB an aircraft with the attribute atc_model=32A and atc_parking_codes=UAL. 3. The above point fail because the non-existant ICAO code =32A: so the program will search the appropriate (ICAO) code for the “32A” and so will use the atc_model=A320 and atc_parking_codes=UAL. If found, the related “Title” is used to create the route. 4. If the above point fails, FSXAIS will write a row in the log with the missing a/c (sometimes with the a/c description) and a new row in the “Subst” table (UAL-32A=UAL-000). Another example: the external provider codes a JetBlue Airline (JBU) flight using the a/c type A320 (ICAO Airbus A320 generic model): what’s happens in FSXAIS? Activate = checked 1. The string UAL-A320 is searched in the subst table. If found, the alternate couple is used (for example, UAL-320). 2. If the above point fail, the program will search in the A/C DB an aircraft with the attribute iata_model=A320 and atc_parking_codes=UAL. 3. The above point fail because no IATA code exist equal to A320. FSX AI Spotter User Guide Copyright 2015 Page 23 of 24 4. FSXAIS will search in the A/C DB an aircraft with the attribute atc_model=A320 and atc_parking_codes=UAL. If found, the related “Title” is used to create the route. 5. If the above point fails, FSXAIS will write a row in the log with the missing a/c (sometimes with the a/c description) and a new row in the “Subst” table (UAL-A320=UAL-000). Activate = unchecked 1. The string UAL-A320 is searched in the subst table. If found, the alternate couple is used (for example, UAL-320). 2. If the above point fail, the program will search in the A/C DB an aircraft with the attribute atc_model=A320 and atc_parking_codes=UAL. 3. If the above point fails, FSXAIS will write a row in the log with the missing a/c (sometimes with the a/c description) and a new row in the “Subst” table (UAL-A320=UAL-000). Note: The IATA aircraft model specification is more accurate and updated respect the ICAO one (used by MS – Flight Simulators). FSX AI Spotter User Guide Copyright 2015 Page 24 of 24
