Difference between revisions of "ATC-pie user guide"

From FlightGear wiki
Jump to: navigation, search
(r8c)
(r9 released (teacher-student connection type))
Line 2: Line 2:
  
 
This article is a guide to help one download and run '''[[ATC-pie]]'''. It describes some of its major features and lists a few tips. Other sources to learn the program are:
 
This article is a guide to help one download and run '''[[ATC-pie]]'''. It describes some of its major features and lists a few tips. Other sources to learn the program are:
* the '''[https://www.youtube.com/playlist?list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb online video tutorial]''' on ''YouTube'';
+
* the [https://www.youtube.com/playlist?list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb online] '''video tutorial''';
* the in-app '''quick reference''' available from the ''Help'' menu (summary of mouse/keyboard gestures, display conventions, etc.).
+
* the in-app '''quick reference''' available from the ''Help'' menu (summary of mouse/keyboard gestures, display conventions, etc.);
 +
* to play solo!
  
Anyone motivated to write a full user guide is obviously welcome to contact the developer, or improve this article.
+
Anyone motivated to write a full user guide is obviously welcome to contact the developer, or improve this article. For support and troubleshooting, the [[ATC-pie FAQ]] might get you an answer first. Otherwise kindly ask on the FlightGear forum, where we have a dedicated sub-forum, so the discussion is public and its contents shared.
  
 
== Getting ATC-pie to run ==
 
== Getting ATC-pie to run ==
Line 16: Line 17:
 
# extract the files to the directory of your choice.
 
# extract the files to the directory of your choice.
  
To clone the '''repository''':
+
To clone the Git '''repository''':
 
: <code>git clone git://git.code.sf.net/p/atc-pie/code ATC-pie</code>
 
: <code>git clone git://git.code.sf.net/p/atc-pie/code ATC-pie</code>
  
When a new release is announced and if you have cloned the repository, you can update your software with a single command from the downloaded directory:
+
If you choose cloning with Git, you can update your software when a new release is announced with a single command from the downloaded directory:
 
: <code>git pull</code>
 
: <code>git pull</code>
  
Line 29: Line 30:
 
If no ICAO code is given, good old KSFO will be chosen as default.
 
If no ICAO code is given, good old KSFO will be chosen as default.
  
ATC-pie's '''centre mode''' is designed for en-route control centre simulation (CTR). It disables all airport-specific features, and allows to place the radar anywhere on Earth. To start this mode and define a new position, run the command:
+
ATC-pie's '''centre mode''' is designed for en-route control centre simulation (CTR). It disables all airport-specific features, and allows to place the radar anywhere on Earth. To start this mode and define a new centre position, run the command:
: <code>./ATC-pie.py --ctr=code radar_position</code>
+
: <code>./ATC-pie.py --ctr=location_code radar_position</code>
The ''radar_position'' argument specifies the point on which to centre the radar, for example given as world coordinates (see down <code>resources/bg-img/Notice</code> for full point syntax description; look out for any character to escape from shell). Replace ''code'' by a designator of your choice (excluding airport codes), under which to save your location-specific settings. A good idea is to use ICAO airspace designations, e.g. "SBBS" for the Brasilia FIR in central Brazil. Subsequent runs at the same location will then be enabled without the second argument, and with the even more direct command:
+
Replace ''location_code'' by a designator of your choice (excluding airport codes), under which to save your location-specific settings. A good idea is to use ICAO airspace designations, e.g. SBBS for the Brasilia FIR in central Brazil, or LFFF for the Paris region in France. The ''radar_position'' argument specifies the point on which to centre the radar. For example, <code>./ATC-pie.py --ctr=LFFF LFPO</code> will define a CTR location named LFFF and centred on Orly airport. See down <code>resources/bg-img/Notice</code> for a full description of the syntax for point specification (look out for any character to escape from shell, e.g. quoting <code>'LFPO>090,15'</code> for a point 15 NM East of Orly).
: <code>./ATC-pie.py code</code>
+
  
Additional command line options are available:
+
Subsequent runs at the same location will then be enabled without the second argument, and even with the generic command:
 +
: <code>./ATC-pie.py location_code</code>
 +
 
 +
Besides the location code argument, the following '''command line options''' are available:
 
{| class="wikitable"
 
{| class="wikitable"
 
! Option || Effect and argument specification || Default
 
! Option || Effect and argument specification || Default
Line 46: Line 49:
 
| --tower-view-ports=''udp'',''telnet'' || Specify the tower view ports to send/connect to. These can be the same (UDP and TCP on same port), and are used whether the viewer process is internal (child) or external (local or remote). || 5010,5010
 
| --tower-view-ports=''udp'',''telnet'' || Specify the tower view ports to send/connect to. These can be the same (UDP and TCP on same port), and are used whether the viewer process is internal (child) or external (local or remote). || 5010,5010
 
|-
 
|-
| --add-view=''host'':''port'' || Register an additional FlightGear instance to forward MP and solo game packets to. This option can be repeated. || (none)
+
| --add-view=''host'':''port'' || Register an additional FlightGear instance to forward traffic to. This enables to position more viewers freely; the feature is also available from the in-game interface. This option can be repeated. || (none)
 
|-
 
|-
 
| --views-send-from=''port'' || Change the local UDP port number to bind for sending FGMS packets to views. This includes all tower and additional views, but does not affect the multi-player connection ports, chosen on MP connect. || 5009
 
| --views-send-from=''port'' || Change the local UDP port number to bind for sending FGMS packets to views. This includes all tower and additional views, but does not affect the multi-player connection ports, chosen on MP connect. || 5009
Line 57: Line 60:
 
=== Running for the first time ===
 
=== Running for the first time ===
 
A few things you will want to do when running ATC-pie for the first time:
 
A few things you will want to do when running ATC-pie for the first time:
* If you intend to use the radio like you should in multi-player games, check the [[FGCom]] version setting in the ''System'' menu, and try an echo test. Read the <code>resources/fgcom/Notice</code> file if you have problems hearing yourself, and check the FAQ section in this article.
+
* If you intend to use the radio like you should in FlightGear multi-player games, check the [[FGCom]] version setting in the ''System'' menu, and try an echo test. Read the <code>resources/fgcom/Notice</code> file if you have problems hearing yourself, and search for "FGCom" in the [[ATC-pie FAQ]].
 
* In the same menu, if you want to use the tower viewing system and not bother making it external (see feature note below), make sure you have the right paths set for your [[FlightGear]] installation.
 
* In the same menu, if you want to use the tower viewing system and not bother making it external (see feature note below), make sure you have the right paths set for your [[FlightGear]] installation.
 
* Set up the important location-specific settings like airport runway parameters, especially ILS capability if you will be playing solo often at the same location.
 
* Set up the important location-specific settings like airport runway parameters, especially ILS capability if you will be playing solo often at the same location.
  
Note for multi-player games: callsigns for ATCs are typically expected to start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service (twr, gnd, ctr...). Before choosing your callsign on MP connect, make sure it is not already in use, and note that [[FGMS]] restricts callsign length to 7 characters. :-(
+
NB: callsigns for ATCs in FlightGear are expected to start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service (twr, gnd, ctr...). Before choosing your callsign on MP connect, make sure it is not already in use, and note that [[FGMS]] restricts callsign length to 7 characters. :-(
  
 
== Feature notes ==
 
== Feature notes ==
 
This section describes a few major features. A more exhaustive list can be found in the main article.
 
This section describes a few major features. A more exhaustive list can be found in the main article.
  
=== Routing and conflict warnings ===
+
=== Routes and conflict warnings ===
 
ATC-pie analyses routes and assigned vectors to assist traffic management and anticipate path conflicts between controlled aircraft. This feature is essential in centre mode.
 
ATC-pie analyses routes and assigned vectors to assist traffic management and anticipate path conflicts between controlled aircraft. This feature is essential in centre mode.
  
Line 107: Line 110:
 
|}
 
|}
  
=== Solo training mode ===
+
=== Playing solo ===
In solo games, you control virtual IFR planes via the instruction interface, receiving and handing over strips to virtual ATCs depending on your position and aircraft's intentions. ATC-pie allows to train in different situations:
+
In solo games, you control virtual IFR planes, receiving and handing over strips to virtual ATCs depending on your position and aircraft's intentions. ATC-pie allows to train in different situations:
 
* as an en-route controller (CTR) if started in centre mode;
 
* as an en-route controller (CTR) if started in centre mode;
 
* or in airport mode, where three combinable positions are available:
 
* or in airport mode, where three combinable positions are available:
Line 155: Line 158:
 
* CTR mode with a low ceiling to increase the number of conflicts to resolve;
 
* CTR mode with a low ceiling to increase the number of conflicts to resolve;
 
* etc.
 
* etc.
 +
 +
=== Teacher & student connections (ATC tutoring) ===
 +
This connection type is made to bring an ATC student and a teacher together for tutorial or training sessions. The teacher creates and manipulates traffic for the student to work with, controls the weather and decides on the ATC neighbours.
 +
 +
To '''set up a session''', the student must connect to the teacher, so make sure the teacher's session is running first. Only one student can connect to a teacher at a time. To communicate via voice during the session, the two parties may use nearby FGCom frequencies, but a private channel on [[Mumble]] is also an option to avoid interfering with multi-player users sharing the same server. The best choice is probably to tune into unused (guard or secondary) FGCom frequencies for in-simulation transmissions, and to open a separate channel for teacher–student conversations.
 +
 +
When '''playing teacher''':
 +
* The teaching console dock is enabled, which you should keep visible for efficient control of the student's environment.
 +
* New traffic can be created at any time with a simple SHIFT+click&drag on the radar, specifying the place and face heading of the wanted traffic. A dialog pops up and allows you to choose a callsign, altitude and other details or accept the defaults. If near a runway threshold, you can place it on the ground ready for departure.
 +
* Traffic is initially created in an "unspawned" state, in other words visible to you but not to the student. This allows you to change his transponder settings or get it into a certain state or place before spawning it into the student's world.
 +
* Controlling the traffic is done in the same way as in solo sessions, i.e. through the vectoring tool (click&drag on aircraft bodies) and the instruction dock. The only difference is that you physically control the selected aircraft, regardless of your strip links and details. You therefore do not need to link strips with correctly entered callsigns before instructing aircraft. However, if you want ATC-pie to draw vectors and show assigned altitudes, it is a good idea to link a strip to your aircraft (use SHIFT+F2 to create a strip linked to the current selection).
 +
 +
'''Strip exchange''' is possible, either between both parties ("offline" exchanges) or between the student and the virtual ATCs (in-sim handovers). As the teacher, you must drop every strip on "Student" and select whom the strip should appear sent by on the student's side when prompted. As the student, drop your strip on any of the ATCs in the neighbours list to simulate a handover, or on "Teacher" if only showing it to your mentor. All student handovers are made visible to the teacher for supervision.
 +
 +
Note: unlike in FlightGear games where limitations apply (see section further down), all strips are exchangeable in tutorial sessions.
  
 
=== Tower viewing ===
 
=== Tower viewing ===
 
[[File:ATC-pie-screenshot-towerViewing.png|thumbnail|Tower viewing, following a departing aircraft]]
 
[[File:ATC-pie-screenshot-towerViewing.png|thumbnail|Tower viewing, following a departing aircraft]]
This feature allows you to overlook your airport and the connected (MP) or simulated (solo) traffic, like a controller from a '''tower viewpoint'''. It uses the tower position specified in the source data if any, otherwise defaults to somewhere over the airport to allow towering all available airports. It is disabled in CTR mode.
+
This feature allows you to overlook your airport and the connected (multi-player games) or simulated (solo and teaching sessions) traffic, like a controller from a '''tower viewpoint'''. It uses the tower position specified in the source data if any, otherwise defaults to somewhere over the airport to allow towering all available airports. It is disabled in CTR mode.
  
 
There are two ways of activating a tower view. You may let ATC-pie start its own suitably configured FlightGear process, or have it connect to an external viewer, manually set up and accepting connections. The latter way takes a little more effort but allows to run FlightGear on a different machine and thereby relieve your session from the CPU load a local instance induces. If you are going for that, start ATC-pie with <code>--tower-view-external</code> and check the <code>--tower-view-ports</code> and <code>--views-send-from</code> command line options in the table above to set it up correctly.
 
There are two ways of activating a tower view. You may let ATC-pie start its own suitably configured FlightGear process, or have it connect to an external viewer, manually set up and accepting connections. The latter way takes a little more effort but allows to run FlightGear on a different machine and thereby relieve your session from the CPU load a local instance induces. If you are going for that, start ATC-pie with <code>--tower-view-external</code> and check the <code>--tower-view-ports</code> and <code>--views-send-from</code> command line options in the table above to set it up correctly.
Line 168: Line 186:
 
In either case, once activated from the ''View'' menu, the tower view controller pane is enabled and you can turn to runway points, follow selected aircraft, etc. Additionally, use right click and drag directly on the view to look around, and you may use the <code>x</code>/<code>X</code> keys to change the zoom level from the view window (this is direct FlightGear input).
 
In either case, once activated from the ''View'' menu, the tower view controller pane is enabled and you can turn to runway points, follow selected aircraft, etc. Additionally, use right click and drag directly on the view to look around, and you may use the <code>x</code>/<code>X</code> keys to change the zoom level from the view window (this is direct FlightGear input).
  
You can also connect '''additional viewers''' to your session, for example placed around your airport for exciting camera footage of challenging landings. You will not be able to control those viewers from ATC-pie like the tower viewer, but you will be able to activate/stop the connection with a switch in the application ''View'' menu. To do so, append an option <code>--add-view=XXX:YYY</code> to your ATC-pie command for every additional FlightGear viewer started on host ''XXX'' with options <code>--multiplay=out,TTT,HHH,PPP</code> and <code>--multiplay=in,TTT,,YYY</code>. In these options:
+
You can also connect '''additional viewers''' to your session, for example placed around your airport for exciting camera footage of challenging landings. You will not be able to control those viewers from ATC-pie like the tower viewer, but you will be able to activate/stop the connection with a switch in the application ''View'' menu.
 +
 
 +
Every additional FlightGear viewer running on host ''XXX'' should be started with options <code>--multiplay=out,TTT,HHH,PPP</code> and <code>--multiplay=in,TTT,,YYY</code>, and registered in your ATC-pie instance. You can do this from the ''View'' menu (add viewer "''XXX'':''YYY''"), or directly from the command line with an extra option <code>--add-view=XXX:YYY</code>. In these options:
 
* ''HHH'' is the host on which ATC-pie is running (same value for all viewers);
 
* ''HHH'' is the host on which ATC-pie is running (same value for all viewers);
 
* ''PPP'' is the default 5009, or the chosen port number if ATC-pie is started with <code>--views-send-from</code> (same value for all viewers);
 
* ''PPP'' is the default 5009, or the chosen port number if ATC-pie is started with <code>--views-send-from</code> (same value for all viewers);
Line 174: Line 194:
 
* ''YYY'' is the port number used by the viewer for FGMS packet reception.
 
* ''YYY'' is the port number used by the viewer for FGMS packet reception.
  
=== Multi-player strip exchange (handovers) and OpenRadar interoperability ===
+
=== FlightGear strip exchange (handovers) and OpenRadar interoperability ===
 
[[File:ATC-pie-screenshot-receivedStrip.png|thumbnail|Example of a strip received from "DEL"]]
 
[[File:ATC-pie-screenshot-receivedStrip.png|thumbnail|Example of a strip received from "DEL"]]
 
The handover feature in ATC-pie is based on [[OpenRadar]]'s exchange server to enable ATC coordination between users of both software programs. However, it is to note that their philosophies differ in several ways:
 
The handover feature in ATC-pie is based on [[OpenRadar]]'s exchange server to enable ATC coordination between users of both software programs. However, it is to note that their philosophies differ in several ways:
Line 191: Line 211:
 
* ATC-pie to O-R: callsign resolved for the receiver, sender's entry will reappear next time ATC-pie handles the strip;
 
* ATC-pie to O-R: callsign resolved for the receiver, sender's entry will reappear next time ATC-pie handles the strip;
 
* pie-to-pie handovers: strip detail preserved, whether present or absent.
 
* pie-to-pie handovers: strip detail preserved, whether present or absent.
 +
 +
Detail note: wake turbulance category detail does not show in OpenRadar, but is preserved and visible to ATC-pie instances later receiving the strip.
  
 
In practice, in ATC-pie, a strip can be handed over by dropping it on the chosen ATC in the list of connected controllers in range. Received strips appear unlinked on the reserved rack, with an identification of the sender which disappears as soon as the strip is clicked on. For a full presentation about the feature, check [https://www.youtube.com/watch?v=oQIud-cAlT4 tutorial video 6].
 
In practice, in ATC-pie, a strip can be handed over by dropping it on the chosen ATC in the list of connected controllers in range. Received strips appear unlinked on the reserved rack, with an identification of the sender which disappears as soon as the strip is clicked on. For a full presentation about the feature, check [https://www.youtube.com/watch?v=oQIud-cAlT4 tutorial video 6].
Line 204: Line 226:
 
:<code>convert -transparent white input-file.png output-file.png</code>
 
:<code>convert -transparent white input-file.png output-file.png</code>
  
Use the image positioning helper tool in the ''System'' menu if you want to adjust image corners visually rather than programmatically. All visible pixmap images will be moved simultaneously, so you can work with several at a time if you need to. On dialog box close, a file is generated in the <code>output</code> folder for you to open and copy/edit, or use as a direct substitution.
+
ATC-pie comes with two '''helper tools''' related to background images, located in the ''System'' menu:
 +
# The "download OSM background" option facilitates [[OpenStreetMap]] retrieval to import maps as radar background images. After specifying corners and a scale, a PNG map will be generated in the <code>output</code> directory for you to import.
 +
# The "image positioning helper" tool will help you adjust image corners visually rather than programmatically if you have no exact specification for the corner points. All visible pixmap images will be moved simultaneously, so you can work with several at a time if you need to. On dialog box close, a file is generated in <code>output</code> for you to open and copy/edit, or use as a direct substitution if you do not mind all specs changing to world coordinates.
 +
 
 +
=== Text chat ===
 +
ATC-pie has a powerful text chat system for those who use the keyboard extensively, though of course voice radio communications should be encouraged for realism, whenever possible.
 +
 
 +
First, a '''text alias''' is a dollar-prefixed word (like <code>$foo</code>) that ATC-pie will try to replace with a context-dependant value on message send. This allows to write and save formatted messages and avoid typing exact text in every message of the same format. For instance, anybody will enjoy the comfort of sending <code>Current weather is $metar</code>, whose alias will expand to the current primary station weather, instead of typing or copy-pasting a weather look-up for every such message.
 +
 
 +
Aliases can be predefined or custom. Predefined aliases take values that are specified by the program, e.g. <code>$metar</code> standing for the current weather, and are listed in the "quick reference", ''Text aliases'' section, with their meaning. Make sure you take a look. They can depend on the local environment (declination, airport elevation...), on your configuration (transition altitude, runways in use...) or on the current selection (QDM to airport, assigned route...). All other aliases will be considered custom, in other words to take values specified by you. You can define text aliases and replacements on world level, location (airport/centre) level and individual strip level. The first two levels make use of the integrated notepads; the latter looks inside your strip comments.
 +
 
 +
Here is how ATC-pie decides what to do with a text alias of the form <code>$foo</code> on chat message send:
 +
# If it is one of the predefined list, the substitution is the one described. If not, it is a custom alias and we carry on to the next step.
 +
# Look for a line beginning with "foo=" in the general notes (notepad dock). If one is found, the alias is substituted with what follows the '='.
 +
# Perform the same search through the local notes. If nothing is found, consider the current selection.
 +
# If a strip is part of the current selection, look inside the comment field and search likewise.
 +
# Substitution is unsuccessful. ATC-pie will open an edit box so that you can review your message before sending it.
 +
 
 +
NB: You can test all this without polluting any game channel by holding the mouse down on the "Msg" button and selecting "check message". This will allow you to view what replacements would take place.
 +
 
 +
Moreover, ATC-pie strips everything up to the first pipe character (<code>|</code>), if any, before a message is processed and sent. You may check this with test line "stripped part|sent part" and observe that only the "sent part" makes it to the message contents. Since any entry already triggers a filtered pop-up menu of preset messages as yout type, '''pipe shortcuts''' can also make your life easier if you want to recall preset messages without pulling down the preset list. You can prefix your messages with a custom shortcut and a pipe, which will enable the automatic suggestion list to pull up the desired message line as you start typing the prefix. For example, the following preset message enables something like a dot-command for sending a bearing to your base airport in a few key strokes:
 +
: <code>.qdm|Heading to airport $qdm</code>
 +
 
 +
Lastly, if a troll or angry user is polluting your session with undesired messages, click and hold the ''Dest.'' tool button in the text chat dock to add their callsign to the '''senders blacklist'''. All messages from the user will then be filtered out from the message pane. You can view and clear this list at any time during the game.
  
 
== Tips ==
 
== Tips ==
Line 222: Line 267:
 
The grouped tick marks along the '''localiser line''' (when shown) indicate best altitudes AMSL for final approach along the defined flight path angle: every mark in a group is 1,000 ft.
 
The grouped tick marks along the '''localiser line''' (when shown) indicate best altitudes AMSL for final approach along the defined flight path angle: every mark in a group is 1,000 ft.
  
=== Radio and text communications ===
+
=== Radio communications ===
Several radios can be opened and tuned in at once, and you can talk on either one by holding the PTT mouse button down for the chosen radio box. The <code>left-Ctrl</code> keyboard key will also let you PTT on selected frequencies. You can transmit on several at once, for example to service GND+TWR frequencies in view of splitting them seemlessly again if a controller is expected soon to fill one of the two positions. Tick the ''Kbd PTT'' option in the radio boxes of the frequencies to merge. Your keyboard PTT key will then transmit on them all simultaneously. Note that while you will be broadcasting on, and hearing incoming transmissions from, all frequencies, pilots will not be hearing each other across frequencies.
+
'''Multiple radios''' can be opened and tuned in at once, and you can talk on either one by holding the PTT mouse button down for the chosen radio box. The <code>left-Ctrl</code> keyboard key will also let you PTT on selected frequencies. You can transmit on several at once, for example to service GND+TWR frequencies in view of splitting them seemlessly again if a controller is expected soon to fill one of the two positions. Tick the ''Kbd PTT'' option in the radio boxes of the frequencies to merge. Your keyboard PTT key will then transmit on them all simultaneously. Note that while you will be broadcasting on, and hearing incoming transmissions from, all frequencies, pilots will not be hearing each other across frequencies.
  
 
Say you are TWR coordinating with GND at your airport, and you want to '''monitor both radio frequencies''' while you are only in charge of TWR. To set this up, start your radio box on TWR frequency and turn on a second one to monitor GND. Tick "Kbd PTT" only for TWR so that you only transmit to your frequency and don't interfere with the other, and set the volume to "soft" on the latter so that you can tell the radio you are hearing the messages from, and know if it is for you to answer.
 
Say you are TWR coordinating with GND at your airport, and you want to '''monitor both radio frequencies''' while you are only in charge of TWR. To set this up, start your radio box on TWR frequency and turn on a second one to monitor GND. Tick "Kbd PTT" only for TWR so that you only transmit to your frequency and don't interfere with the other, and set the volume to "soft" on the latter so that you can tell the radio you are hearing the messages from, and know if it is for you to answer.
  
 
The '''''PTT turns off sounds''''' option is recommended for those of you who do not wear headsets, as it will avoid GUI sound notifications being picked up by your microphone while transmitting on frequencies.
 
The '''''PTT turns off sounds''''' option is recommended for those of you who do not wear headsets, as it will avoid GUI sound notifications being picked up by your microphone while transmitting on frequencies.
 
For more efficient text chat, '''text aliases''' are available and allowed in both instant and preset chat messages, e.g. <code>$wind</code>, <code>$qnh</code>... When the containing message is sent, they automatically expand to the current context-dependant value. Custom aliases can be used, whose replacement will be searched for in the general and local notes (your notepads) and in the selected strip comments. This allows for variable text by controller, by location (AD or CTR) and by radar contact. Have a look at the ''Quick reference'' available from the ''Help'' menu, ''Text aliases'' section. Unsuccessful replacements will trigger an edit box so that you can review your message before sending it.
 
 
Everything up to the first pipe character (<code>|</code>, if any) in a text chat line will be stripped before the message is processed and sent. For quicker access to preset messages if you use them and the keyboard a lot, you can therefore '''prefix your messages''' with a custom shortcut and a pipe, which will enable the automatic suggestion list to pull up the desired message line as you start typing the prefix. Here is a preset message example enabling something like a dot-command for sending a bearing to your base airport to the currently selected pilot:
 
: <code>.qdm|Heading to airport $qdm</code>
 
 
If a troll or angry user is polluting your session with undesired messages, click and hold the ''Dest.'' tool button in the text chat dock to add their callsign to the '''senders blacklist'''. All messages from the user will then be filtered out from the message pane.
 
  
 
=== Strip and flight plan details ===
 
=== Strip and flight plan details ===
Line 253: Line 291:
 
* to update the online version with your local modifications, double-click the flight plan and tick the "publish" box before saving (if still decorated red, there was a network problem or the change was rejected by the server);
 
* to update the online version with your local modifications, double-click the flight plan and tick the "publish" box before saving (if still decorated red, there was a network problem or the change was rejected by the server);
 
* to discard all local modifications of an online FPL, remove the FPL from the list and check for new flight plans again (the deleted entry should be retrieved with online state).
 
* to discard all local modifications of an online FPL, remove the FPL from the list and check for new flight plans again (the deleted entry should be retrieved with online state).
 
== FAQ ==
 
Questions frequently asked (at least twice) about the program:
 
 
'''Q: How do I start anywhere else than bl*ody KSFO?'''
 
 
Use a command line argument: <code>./ATC-pie.py ICAO</code>
 
 
'''Q: Why am I not seeing this aircraft on my radar? I know it is there: the pilot is sending chat messages and/or it is visible on the online live map...'''
 
 
You only see an aircraft on your screen if your radar picks up a transponder signal from it. The two following cases will therefore prevent you from seeing a connected aircraft:
 
# Its onboard transponder is turned off, i.e. not responding to your radar ping, and you should tell the pilot to switch it on. See the [https://www.youtube.com/watch?v=kpPzRiwzx9Q&list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb&index=1 ATC-pie video tutorial 1]. If the aircraft model does not support the transponder feature, it will be simulated by ATC-pie according to the fallback mode you have selected in the settings dialog; any non-zero mode will make the aircraft visible to you. Alternatively, you can switch on the primary radar system if you want to see aircraft's position, or activate the "radar cheat mode" if you want to go the radical way ([https://www.youtube.com/watch?v=lSyH88HR-4w&index=3&list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb tutorial 3]).
 
# The aircraft is out of range, under the radar floor (minimum signal pick-up height) or too far out. Open the ''General settings'' dialog, check the NM range setting and set the floor to "SFC" to pick up all signals.
 
 
'''Q: What is the strip exchange server? Which one to use?'''
 
 
The strip exchange feature allows you to hand over strips to ATCs who are connected to the same server and within 180 NM from your position. The public server currently open for general multi-player use is <code>http://h2281805.stratoserver.net/FgFpServer</code>. To hand over a strip, drag it from its rack and drop it on the chosen callsign in the ATC handover list. Publicise your frequency so that ATCs around know what to tell pilots for them to contact you!
 
 
'''Q: What nickname should I use for the strip exchange server? Where to create an account?'''
 
 
This feature is not linked to any identification process; just choose any name you would like to be recognised by. It will appear in a tooltip over your callsign in the handover list of ATCs who will connect near enough to see you. In a sense, this feature is more social than technical, but makes sense as typical ATC callsigns remain mostly anonymous over MP. Use this field so that other players can identify you.
 
 
'''Q: Can I draw SID and STAR procedures on the radar?'''
 
 
Yes, and virtually anything else, using background images and hand drawings. To learn how, see the corresponding section above, read the <code>resources/bg-img/Notice</code> file and have a look at the packaged example for KSFO.
 
 
'''Q: How do I assign SIDs and STARs to aircraft?'''
 
 
This question seems asked quite a lot more than it sounds relevant to a real controller's task. Say you could click around the interface and "assign" a STAR to an inbound aircraft; what would the effect be after that? Should this be important to you, you can always freely comment your strips with the information you want to save. But the realistic wishes in relation to this question are already addressed otherwise:
 
* Planning routes
 
*: Published standard departure and arrival procedures (SIDs and STARs) are very often referred to in planned routes, which are assigned prior to departure. Hopefully pulled straight from an existing flight plan, such route is written on the initial flight strip, modified as the flight progresses and passed along with handovers. Like any piece of route specification, you can specify that a SID or STAR is to be followed in the strip route field, e.g. "SID FUBAR en route stuff DUMMY STAR". This will even be recognised by ATC-pie and accounted for in the second line of the radar contact info box when appropriate (see feature note on routing).
 
* Reference for easy text chat communications
 
*: When such route is parsed on the selected strip, text aliases <code>$wpsid</code> and <code>$wpstar</code> will respectively be replaced with the first and last en-route waypoints if the "SID"/"STAR" keywords are present and placed correctly. With the example route above, <code>$wpsid</code> will turn into "FUBAR" and <code>$wpstar</code> into "DUMMY". Now if you specifically want to assign a full published procedure name to a contact, e.g. FUBAR4E, and use it in text chat messages without typing it, include a line "sid=FUBAR4E" in your strip comments. It will pop up with the strip mouse-over tooltip, and create a custom <code>$sid</code> alias that will automatically be filled in your sent messages when that strip is selected.
 
 
'''Q: FGCom radio is not working. What is going on?'''
 
 
There can be a variety of reasons, all of them to rule out before reporting a bug in the program. Start a single ATC-pie instance and try the echo test (''System'' menu). If it works, you may skip directly to item 3 below.
 
# Bad FGCom version setting
 
#: Verify the "FGCom version" set in the ''System'' menu, which should point to the right executable file under <code>resources/fgcom</code> and suit your operating system (see <code>Notice</code> file). Four versions are initially packaged with ATC-pie: Linux64, Linux32, Mac, Win32.
 
# FGCom server down
 
#: This can happen, unfortunately even for up to a few days. Check for responses from the server, e.g. with <code>ping fgcom.flightgear.org</code>.
 
# FGCom subprocess error
 
#: If the server is up (responding to ping), check for errors in the logged FGCom output files in the <code>output</code> directory.
 
# Port mess-up on your side
 
#: If you are running multiple instances of ATC-pie, make sure you have no more than one radio box on every port. In any case, verify you only choose available ports that are not already in use by your operating system for example. Typically, default ports (from 16661 counting up) work fine, but you will have to change them for parallel instances, using the <code>--fgcom-ports</code> command line option (see section: ''starting the program''). To check what port a radio box is using, see its "on/off" button tooltip.
 
 
'''Q: Tower view is not starting. The menu option is ticked but nothing happens.'''
 
 
Ruling out that FlightGear is not installed at all, your system path settings are probably wrong. From a terminal, find the right command to start FlightGear and enter it as ''FlightGear executable'' from the ''System'' menu. Do not add options of any kind; they will be taken care of internally. You may have to enter a ''FlightGear root directory'' as well, especially if you have the program files installed somewhere unexpected. Your entries will be saved after that.
 
 
'''Q: Why is my tower in the middle of the sea, and aircraft water landing/floating?'''
 
 
You are missing the FlightGear scenery data for your location, or ATC-pie does not know where it is. Check out the ''Tower viewing'' feature note in this article.
 
  
 
[[Category:ATC-pie]]
 
[[Category:ATC-pie]]
[[Category:ATC clients]]
 

Revision as of 18:28, 8 May 2016

This article is a guide to help one download and run ATC-pie. It describes some of its major features and lists a few tips. Other sources to learn the program are:

  • the online video tutorial;
  • the in-app quick reference available from the Help menu (summary of mouse/keyboard gestures, display conventions, etc.);
  • to play solo!

Anyone motivated to write a full user guide is obviously welcome to contact the developer, or improve this article. For support and troubleshooting, the ATC-pie FAQ might get you an answer first. Otherwise kindly ask on the FlightGear forum, where we have a dedicated sub-forum, so the discussion is public and its contents shared.

Getting ATC-pie to run

Downloading

There are essentially two ways of downloading ATC-pie: one is to download a tarball to extract locally; the other is to clone the Git repository. The latter requires Git, but will keep you in sync with updates more easily. Your choice. In either case, you will have no compiling to do (make, etc.), but do make sure you have the few dependencies installed, listed in the README file (Python3 + bindings to Qt5).

Downloading the tarball:

  1. get the latest stable version from the project page;
  2. extract the files to the directory of your choice.

To clone the Git repository:

git clone git://git.code.sf.net/p/atc-pie/code ATC-pie

If you choose cloning with Git, you can update your software when a new release is announced with a single command from the downloaded directory:

git pull

Starting the program

Depending on your system and preference, you might be double-clicking, typing stuff or pulling your hair out. In any case what you need is to run a Python3 interpreter on the ATC-pie.py file in the top-level directory. You may start the program in either airport or centre mode, i.e. respectively with or without a base airfield.

The airport mode is typically used for ATC positions like approach or tower control. In this mode, ATC-pie places the radar at the chosen base airfield, depicts its tarmac and runways, and enables features like tower viewing and runway use configuration. To start the airport mode from a system terminal, say with base airfield ICAO, the command to run is:

./ATC-pie.py ICAO

If no ICAO code is given, good old KSFO will be chosen as default.

ATC-pie's centre mode is designed for en-route control centre simulation (CTR). It disables all airport-specific features, and allows to place the radar anywhere on Earth. To start this mode and define a new centre position, run the command:

./ATC-pie.py --ctr=location_code radar_position

Replace location_code by a designator of your choice (excluding airport codes), under which to save your location-specific settings. A good idea is to use ICAO airspace designations, e.g. SBBS for the Brasilia FIR in central Brazil, or LFFF for the Paris region in France. The radar_position argument specifies the point on which to centre the radar. For example, ./ATC-pie.py --ctr=LFFF LFPO will define a CTR location named LFFF and centred on Orly airport. See down resources/bg-img/Notice for a full description of the syntax for point specification (look out for any character to escape from shell, e.g. quoting 'LFPO>090,15' for a point 15 NM East of Orly).

Subsequent runs at the same location will then be enabled without the second argument, and even with the generic command:

./ATC-pie.py location_code

Besides the location code argument, the following command line options are available:

Option Effect and argument specification Default
--ctr=code Start in CTR mode at given location code (see above). Anonymous argument sets/resets the radar position for this location if given. (none)
--map-range=range Define the distance in NM from the radar centre up to which the map will be drawn and navpoints listed in the navigator (accepted values are 20..500). This is a different setting to the radar range configurable in the game settings. 100 in AD mode; 300 in CTR mode
--tower-view-external=host Avoid running an internal FlightGear process for tower viewing, and specify a host on which a viewer is running. This may still be "localhost". (none, start internal process)
--tower-view-ports=udp,telnet Specify the tower view ports to send/connect to. These can be the same (UDP and TCP on same port), and are used whether the viewer process is internal (child) or external (local or remote). 5010,5010
--add-view=host:port Register an additional FlightGear instance to forward traffic to. This enables to position more viewers freely; the feature is also available from the in-game interface. This option can be repeated. (none)
--views-send-from=port Change the local UDP port number to bind for sending FGMS packets to views. This includes all tower and additional views, but does not affect the multi-player connection ports, chosen on MP connect. 5009
--fgcom-server=address Set the server used by internal FGCom radio boxes. fgcom.flightgear.org
--fgcom-ports=list-spec Specify a comma-separated list of port numbers for internally started radio boxes. The first one becomes reserved for echo test and ATIS recording while every other port will allow for an additional radio box in the game. Alternatively, enter a string of the form reserved+nboxes as a shortcut for a contiguous range of nboxes+1 ports. 16665+4 (port 16665 reserved, plus 16666 through 16669 for up to 4 radio boxes)

Running for the first time

A few things you will want to do when running ATC-pie for the first time:

  • If you intend to use the radio like you should in FlightGear multi-player games, check the FGCom version setting in the System menu, and try an echo test. Read the resources/fgcom/Notice file if you have problems hearing yourself, and search for "FGCom" in the ATC-pie FAQ.
  • In the same menu, if you want to use the tower viewing system and not bother making it external (see feature note below), make sure you have the right paths set for your FlightGear installation.
  • Set up the important location-specific settings like airport runway parameters, especially ILS capability if you will be playing solo often at the same location.

NB: callsigns for ATCs in FlightGear are expected to start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service (twr, gnd, ctr...). Before choosing your callsign on MP connect, make sure it is not already in use, and note that FGMS restricts callsign length to 7 characters. :-(

Feature notes

This section describes a few major features. A more exhaustive list can be found in the main article.

Routes and conflict warnings

ATC-pie analyses routes and assigned vectors to assist traffic management and anticipate path conflicts between controlled aircraft. This feature is essential in centre mode.

Route details dialog with world path drawn, available when both end airfields are recognised

A route is parsed for every strip with recognised departure and destination airports (entry fields both turned green), as follows:

  • route tokens are whitespace-separated;
  • each recognised navpoint token (world navigation aid, airfield, fix, RNAV point) creates a waypoint on the path to destination, and a route leg from the previous point (a final leg connects the last point to the destination airport);
  • if ambiguous (navpoint names are not all unique around the world), a waypoint is always the nearest homonym to the point beginning the leg;
  • other tokens are kept as route leg specifications to the following waypoint (allows for airway or procedure names for example).
Assigned routes can be drawn as dotted lines on the radar scope when linked to contacts

Parsed routes on flight plans and strips are viewable in a route dialog, showing leg details and the geodesic paths on a world map. Also, when a route is parsed and linked to a radar contact, ATC-pie works out its current leg based on distance to destination, and:

  • the route to go is drawn as a dotted line on the radar scope (according to scope "show" options);
  • details of the current leg are displayed in the selection info pane, and the route dialog enabled for full route viewing;
  • the strip shows only the remainder of the route for this contact;
  • the info box contains the next waypoint and the heading leading the aircraft to it on a great circle, unless:
    • the current route leg is the first, and the keyword "SID" appears in its specification: "SID wp" is displayed, where wp is the first waypoint on the route;
    • the current route leg is the last, and the keyword "STAR" appears in its specification: "STAR wp" is displayed, where wp is the last en-route waypoint.

If no route can be interpreted (missing or unidentified DEP or ARR), info boxes will show the strip destination detail (ARR) if it is filled, possibly with a heading if it is recognised.

Separation rings, coloured when a conflict is detected and involving the aircraft (see table)
Route conflict depiction

ATC-pie also features a conflict prediction system, which can be activated or turned off from the Options menu. It uses route and vector assignments to anticipate and alert you of path conflicts so you can take action and prevent separation losses.

When looking for conflicts, a horizontal (ground projection) path is considered for every aircraft with a linked strip and a parsed route or an assigned heading vector. An aircraft is assumed to follow its route, unless a heading vector is given in which case it is assumed to be flying the assigned straight course. Path conflicts occur when horizontal paths intersect and the intervals between respective current and assigned altitudes overlap. When no altitude is assigned, the interval is one around the current altitude. When an aircraft's altitude is unknown, any assigned altitude will be considered instead.

Another possible alarm is the separation incident, a serious ATC mistake which calls for immediate action. The table below summarises the different levels of conflicts, ranked in decreasing order of emergency.

Conflict warnings in ATC-pie
Alarm Shown on scope (default colours) Meaning
Separation incident Bright red intersecting circles Separation loss between aircraft
Path conflict Red circles and paths Anticipated paths and altitudes are intersecting
Possible path conflict Yellow circles, red paths Ground projection of paths are conflicting but not all altitudes are known

Playing solo

In solo games, you control virtual IFR planes, receiving and handing over strips to virtual ATCs depending on your position and aircraft's intentions. ATC-pie allows to train in different situations:

  • as an en-route controller (CTR) if started in centre mode;
  • or in airport mode, where three combinable positions are available:
    • tower (TWR), controlling runways and immediate surroundings;
    • departure (DEP), bringing departing traffic to their exit point;
    • approach (APP), vectoring arrivals onto final.

When playing CTR, your task is to transit the aircraft across your airspace, always ensuring separation, and to hand each of them over to the most appropriate neighbouring centre North, South, East or West of your sector. You can specify local navpoints in the location settings so that the system includes them as turning points in the randomised aircraft's routes. In airport mode, traffic is either inbound or outbound. Assuming APP, inbound aircraft must be sequenced and vectored into tower range for handover, unless you are in the TWR position as well. Each inbound aircraft either requests ILS (you must clear them for ILS approach), or visual (they require vectors until they report the expected runway is in sight). Playing TWR, you must clear them to land and hand them over to ground control (GND) once they have vacated the runway. If landing cannot take place (too high, not cleared, etc.), aircraft will climb back up for go-around. Tower also manages outbound traffic, which appears ready holding short of runways. After take-off, hand over your strips to departure control, unless you are assuming DEP yourself. When doing DEP, you must hand outbound aircraft over to the en-route centre (CTR) once they are high enough and close to their exit point if specified.

Handover pane when playing solo in airport mode, assuming all three available positions
Handovers with virtual ATCs in airport mode
Departure strips Arrival strips
Assuming positions Receive from Hand over to Receive from Hand over to
DEP only TWR CTR N/A
APP only N/A CTR TWR
TWR only GND DEP APP GND
APP+DEP TWR CTR CTR TWR
TWR+DEP GND CTR APP GND
TWR+APP GND DEP CTR GND
TWR+APP+DEP GND CTR CTR GND

Vectors are given by means of the vectoring assignment tool: click&drag on radar contact for heading; add SHIFT for altitude/FL and speed (see video 5 of the tutorial). Other instructions (line up and wait, clear to land, etc.) can be sent from the instruction dock. Pull it up from the View menu if it is not visible. Instructions are issued to the callsign entered in the top field, which should fill automatically on aircraft or strip selection if the callsign is known.

Things you can train for:

  • approach in dense traffic: select APP position only and increase traffic density;
  • towering a single runway, optimising its use: select TWR position and an equal balance of departures and arrivals;
  • change of runways (e.g. irl after wind direction change): start with APP+TWR and select a runway for arrivals at least, play for a while and go back to the dialog to change for the opposite runway;
  • CTR mode with a low ceiling to increase the number of conflicts to resolve;
  • etc.

Teacher & student connections (ATC tutoring)

This connection type is made to bring an ATC student and a teacher together for tutorial or training sessions. The teacher creates and manipulates traffic for the student to work with, controls the weather and decides on the ATC neighbours.

To set up a session, the student must connect to the teacher, so make sure the teacher's session is running first. Only one student can connect to a teacher at a time. To communicate via voice during the session, the two parties may use nearby FGCom frequencies, but a private channel on Mumble is also an option to avoid interfering with multi-player users sharing the same server. The best choice is probably to tune into unused (guard or secondary) FGCom frequencies for in-simulation transmissions, and to open a separate channel for teacher–student conversations.

When playing teacher:

  • The teaching console dock is enabled, which you should keep visible for efficient control of the student's environment.
  • New traffic can be created at any time with a simple SHIFT+click&drag on the radar, specifying the place and face heading of the wanted traffic. A dialog pops up and allows you to choose a callsign, altitude and other details or accept the defaults. If near a runway threshold, you can place it on the ground ready for departure.
  • Traffic is initially created in an "unspawned" state, in other words visible to you but not to the student. This allows you to change his transponder settings or get it into a certain state or place before spawning it into the student's world.
  • Controlling the traffic is done in the same way as in solo sessions, i.e. through the vectoring tool (click&drag on aircraft bodies) and the instruction dock. The only difference is that you physically control the selected aircraft, regardless of your strip links and details. You therefore do not need to link strips with correctly entered callsigns before instructing aircraft. However, if you want ATC-pie to draw vectors and show assigned altitudes, it is a good idea to link a strip to your aircraft (use SHIFT+F2 to create a strip linked to the current selection).

Strip exchange is possible, either between both parties ("offline" exchanges) or between the student and the virtual ATCs (in-sim handovers). As the teacher, you must drop every strip on "Student" and select whom the strip should appear sent by on the student's side when prompted. As the student, drop your strip on any of the ATCs in the neighbours list to simulate a handover, or on "Teacher" if only showing it to your mentor. All student handovers are made visible to the teacher for supervision.

Note: unlike in FlightGear games where limitations apply (see section further down), all strips are exchangeable in tutorial sessions.

Tower viewing

Tower viewing, following a departing aircraft

This feature allows you to overlook your airport and the connected (multi-player games) or simulated (solo and teaching sessions) traffic, like a controller from a tower viewpoint. It uses the tower position specified in the source data if any, otherwise defaults to somewhere over the airport to allow towering all available airports. It is disabled in CTR mode.

There are two ways of activating a tower view. You may let ATC-pie start its own suitably configured FlightGear process, or have it connect to an external viewer, manually set up and accepting connections. The latter way takes a little more effort but allows to run FlightGear on a different machine and thereby relieve your session from the CPU load a local instance induces. If you are going for that, start ATC-pie with --tower-view-external and check the --tower-view-ports and --views-send-from command line options in the table above to set it up correctly.

Running internally only requires FlightGear installed on your computer. A basic installation is enough, but:

  • not all aircraft will be drawn properly if you do not have the corresponding models installed—it is up to you to add models or create substitution links (in your FlightGear root directory or in resources/fg-aircraft according to the Notice file), or be happy with the default blue and yellow glider that will stand for any missing model;
  • more importantly, you will need the scenery for your airport if you want anything exciting to see (and not sea!)—go to this page or use TerraSync to download it to your computer, and add it to your FlightGear root directory or set the right scenery directory in the System menu (ATC-pie will pass it on to FlightGear and save your setting).

In either case, once activated from the View menu, the tower view controller pane is enabled and you can turn to runway points, follow selected aircraft, etc. Additionally, use right click and drag directly on the view to look around, and you may use the x/X keys to change the zoom level from the view window (this is direct FlightGear input).

You can also connect additional viewers to your session, for example placed around your airport for exciting camera footage of challenging landings. You will not be able to control those viewers from ATC-pie like the tower viewer, but you will be able to activate/stop the connection with a switch in the application View menu.

Every additional FlightGear viewer running on host XXX should be started with options --multiplay=out,TTT,HHH,PPP and --multiplay=in,TTT,,YYY, and registered in your ATC-pie instance. You can do this from the View menu (add viewer "XXX:YYY"), or directly from the command line with an extra option --add-view=XXX:YYY. In these options:

  • HHH is the host on which ATC-pie is running (same value for all viewers);
  • PPP is the default 5009, or the chosen port number if ATC-pie is started with --views-send-from (same value for all viewers);
  • TTT is the network polling frequency (100 is common practice; change as desired if you know what you are doing);
  • YYY is the port number used by the viewer for FGMS packet reception.

FlightGear strip exchange (handovers) and OpenRadar interoperability

Example of a strip received from "DEL"

The handover feature in ATC-pie is based on OpenRadar's exchange server to enable ATC coordination between users of both software programs. However, it is to note that their philosophies differ in several ways:

  • OpenRadar's basic processing unit is the FGMS callsign, whereas ATC-pie's is the strip;
  • OpenRadar's concept of handover is based on a shared notion of aircraft ownership, whereas ATC-pie allows any controller to pull out a strip, write any callsign and link it to a radar contact;
  • in the OpenRadar philosophy, a handover must be acknowledged by the receiver for the sender to lose ownership and for all neighbouring OpenRadar users to see the handover complete, whereas ATC-pie considers that a strip sent through the hand-over pipe is gone and should land directly on a receiver's rack at the other end, without anybody else necessarily to know.

For most interactions to work while still respecting both philosophies as much as possible, the following principles were chosen:

  • ATC-pie users can only hand over strips that are linked to a radar contact (no lone strip can be sent);
  • aircraft under ATC-pie control are not shown as "owned" to OpenRadar users;
  • handovers from ATC-pie will fail if an OpenRadar user in range is claiming ownership;
  • when sending to ATC-pie controllers, OpenRadar users will see their transfers acknowledged straight away, unconditionally.

Callsign exchange policy:

  • O-R to ATC-pie: FGMS callsign will appear on the strip, as if the sender had filled the detail properly;
  • ATC-pie to O-R: callsign resolved for the receiver, sender's entry will reappear next time ATC-pie handles the strip;
  • pie-to-pie handovers: strip detail preserved, whether present or absent.

Detail note: wake turbulance category detail does not show in OpenRadar, but is preserved and visible to ATC-pie instances later receiving the strip.

In practice, in ATC-pie, a strip can be handed over by dropping it on the chosen ATC in the list of connected controllers in range. Received strips appear unlinked on the reserved rack, with an identification of the sender which disappears as soon as the strip is clicked on. For a full presentation about the feature, check tutorial video 6.

Background images

Pixmap image example with a topographic map shot around LIMW (Aosta, Italy)
Hand drawing example with procedures for LSGG (Geneva, Switzerland)

Background images allow to decorate radar scopes with all sorts of maps and useful information about the airspace, terrain or procedures.

There are two ways to add images to the radar background. One is to import pixmap files, which may contain transparency. The other is to write a text drawing specification file to draw coloured lines and label points. This allows to import anything from the most complex coloured height map to the the most schematic airspace outline. All images are positioned with lat/lon coordinates or navpoint names in radar range. The resources/bg-img/Notice file explains how to import and draw background images.

For example, you can map out SID/STAR routes with one image per published chart, named by procedure and associated runways to make in-game selection easy. If you want more than schematic line plots of the procedures, the best way is certainly to draw the images yourself with good enough resolution, e.g. with Gimp. Superimpose a layer on top of a real map canvas, or over a screenshot of your ATC-pie radar with pinned navaids as landmarks. If you have proper to-scale documentation, it is worth trying the command below (requires ImageMagick) to turn the white background of a ready published chart into transparency, and checking if the rendered images are acceptable and zoom-resistant enough.

convert -transparent white input-file.png output-file.png

ATC-pie comes with two helper tools related to background images, located in the System menu:

  1. The "download OSM background" option facilitates OpenStreetMap retrieval to import maps as radar background images. After specifying corners and a scale, a PNG map will be generated in the output directory for you to import.
  2. The "image positioning helper" tool will help you adjust image corners visually rather than programmatically if you have no exact specification for the corner points. All visible pixmap images will be moved simultaneously, so you can work with several at a time if you need to. On dialog box close, a file is generated in output for you to open and copy/edit, or use as a direct substitution if you do not mind all specs changing to world coordinates.

Text chat

ATC-pie has a powerful text chat system for those who use the keyboard extensively, though of course voice radio communications should be encouraged for realism, whenever possible.

First, a text alias is a dollar-prefixed word (like $foo) that ATC-pie will try to replace with a context-dependant value on message send. This allows to write and save formatted messages and avoid typing exact text in every message of the same format. For instance, anybody will enjoy the comfort of sending Current weather is $metar, whose alias will expand to the current primary station weather, instead of typing or copy-pasting a weather look-up for every such message.

Aliases can be predefined or custom. Predefined aliases take values that are specified by the program, e.g. $metar standing for the current weather, and are listed in the "quick reference", Text aliases section, with their meaning. Make sure you take a look. They can depend on the local environment (declination, airport elevation...), on your configuration (transition altitude, runways in use...) or on the current selection (QDM to airport, assigned route...). All other aliases will be considered custom, in other words to take values specified by you. You can define text aliases and replacements on world level, location (airport/centre) level and individual strip level. The first two levels make use of the integrated notepads; the latter looks inside your strip comments.

Here is how ATC-pie decides what to do with a text alias of the form $foo on chat message send:

  1. If it is one of the predefined list, the substitution is the one described. If not, it is a custom alias and we carry on to the next step.
  2. Look for a line beginning with "foo=" in the general notes (notepad dock). If one is found, the alias is substituted with what follows the '='.
  3. Perform the same search through the local notes. If nothing is found, consider the current selection.
  4. If a strip is part of the current selection, look inside the comment field and search likewise.
  5. Substitution is unsuccessful. ATC-pie will open an edit box so that you can review your message before sending it.

NB: You can test all this without polluting any game channel by holding the mouse down on the "Msg" button and selecting "check message". This will allow you to view what replacements would take place.

Moreover, ATC-pie strips everything up to the first pipe character (|), if any, before a message is processed and sent. You may check this with test line "stripped part|sent part" and observe that only the "sent part" makes it to the message contents. Since any entry already triggers a filtered pop-up menu of preset messages as yout type, pipe shortcuts can also make your life easier if you want to recall preset messages without pulling down the preset list. You can prefix your messages with a custom shortcut and a pipe, which will enable the automatic suggestion list to pull up the desired message line as you start typing the prefix. For example, the following preset message enables something like a dot-command for sending a bearing to your base airport in a few key strokes:

.qdm|Heading to airport $qdm

Lastly, if a troll or angry user is polluting your session with undesired messages, click and hold the Dest. tool button in the text chat dock to add their callsign to the senders blacklist. All messages from the user will then be filtered out from the message pane. You can view and clear this list at any time during the game.

Tips

Here are a few tips to help you navigate and use the program.

Interface and information display

The Options menu is divided in two sections. Items above the separator are unsaved session options, which go back to their default setting on restart. Under the separator are the saved settings, which come in two flavours:

  • location-specific (under a single submenu): saved and restored when started at the same location again, e.g. runway ILS capabilities for an airport, main METAR station;
  • global settings (all other entries): saved and restored regardless of location or game mode, e.g. preset text chat messages.

You can customise the radar colours by editing the colour codes in the settings/colours.ini file generated on first run.

Heading displays are mostly magnetic so they can be read out to pilots. The only exceptions perhaps are the navigator and handover list tooltips, for easier human identification on the scope. All directions are geodesic.

The transition level displayed in the weather analysis is the lowest flight level that is still above the transition altitude. This does not mean the lowest to be expected in ATC clearances, which may be higher, for more vertical separation on either side of the transition layer or due to coordination with neighbouring zones and fields.

The grouped tick marks along the localiser line (when shown) indicate best altitudes AMSL for final approach along the defined flight path angle: every mark in a group is 1,000 ft.

Radio communications

Multiple radios can be opened and tuned in at once, and you can talk on either one by holding the PTT mouse button down for the chosen radio box. The left-Ctrl keyboard key will also let you PTT on selected frequencies. You can transmit on several at once, for example to service GND+TWR frequencies in view of splitting them seemlessly again if a controller is expected soon to fill one of the two positions. Tick the Kbd PTT option in the radio boxes of the frequencies to merge. Your keyboard PTT key will then transmit on them all simultaneously. Note that while you will be broadcasting on, and hearing incoming transmissions from, all frequencies, pilots will not be hearing each other across frequencies.

Say you are TWR coordinating with GND at your airport, and you want to monitor both radio frequencies while you are only in charge of TWR. To set this up, start your radio box on TWR frequency and turn on a second one to monitor GND. Tick "Kbd PTT" only for TWR so that you only transmit to your frequency and don't interfere with the other, and set the volume to "soft" on the latter so that you can tell the radio you are hearing the messages from, and know if it is for you to answer.

The PTT turns off sounds option is recommended for those of you who do not wear headsets, as it will avoid GUI sound notifications being picked up by your microphone while transmitting on frequencies.

Strip and flight plan details

Every initial contact by a pilot should basically make you hit F2 and enter at least the call sign announced. You should then soon figure out if:

  • a flight plan is filed, in which case you can save the strip relatively quickly and look for the FPL to link to it (middle click on the FPL entry);
  • a flight plan must be filed (e.g. IFR departure not filed by lazy pilot), which only takes a tick in the bottom-line box before saving to open a freshly linked FPL detail sheet to fill;
  • he was asked to contact you by a previous ATC, in which case you may have a strip handed over to you already (check the unassigned strip rack);
  • etc.

In airport mode, typing a single dot character '.' in an airport input field will instantly fill the box with your ICAO position. Use this as a shortcut from/to your airport when filling details.

Resolving strip–FPL conflicts:

  • to confirm strip details: open the strip detail sheet, tick the "push details to FPL" box and save to propagate the strip details;
  • to confirm FPL details: "pull FPL details" from the button menu to reset the conflicting strip details to the values filled in the linked flight plan;
  • to confirm some details of each source: open the strip sheet, get rid of the bad details before pushing to the flight plan.

Resolving local–online flight plan conflicts:

  • to update the online version with your local modifications, double-click the flight plan and tick the "publish" box before saving (if still decorated red, there was a network problem or the change was rejected by the server);
  • to discard all local modifications of an online FPL, remove the FPL from the list and check for new flight plans again (the deleted entry should be retrieved with online state).