265
edits
Mickybadia (talk | contribs) (r8c) |
Mickybadia (talk | contribs) (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 | * 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> | ||
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>./ATC-pie.py --ctr=location_code radar_position</code> | ||
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). | |||
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 | | --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 | * 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. | ||
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. | ||
=== | === 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: | ||
|} | |} | ||
=== | === Playing solo === | ||
In solo games, you control virtual IFR planes | 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 ( | 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. | 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. | ||
=== | === 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> | ||
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 | === 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 <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. | ||
=== 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). | ||
[[Category:ATC-pie]] | [[Category:ATC-pie]] | ||
edits