ATC-pie user guide: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(r9 released (teacher-student connection type))
(v1.8.7)
 
(34 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{forum|83|ATC-Pie support & development}}
{{forum|83|ATC-Pie support & development}}


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 the air traffic control simulation program [[ATC-pie]], describing some of its major features. A more exhaustive list can be found in the main article. For download and installation help, refer to the [[ATC-pie installation guide]]. For support and troubleshooting, the [[ATC-pie FAQ]] might get you an answer first. Otherwise kindly ask on the dedicated FlightGear sub-forum so that the discussion is public.
* 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.);
* 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.
Other ways to learn the program are:
* to watch the online [https://www.youtube.com/playlist?list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb video tutorial];
* to read the in-app ''Quick reference'' available from the ''Help'' menu (summary of mouse/keyboard gestures, display conventions...);
* to connect with a skilled teacher as a student (personal training);
* to [[#Solo_sessions|train solo]]!


== Getting ATC-pie to run ==
== Flight strips ==


=== Downloading ===
Whether electronic (dematerialised) or on paper, printed automatically or filled by hand, the '''flight progress strip''' is the essential piece of air and ground traffic control. Every aircraft in contact is represented by a unique strip on the ATC workbench, and every strip represents a unique contact, present or expected. This ensures that no aircraft is ever forgotten about. Strip positioning and updating then enable to monitor the aircraft's status, sequence number, position, intentions, etc.
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 [http://git-scm.com 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 <code>README</code> file (Python3 + bindings to Qt5).


Downloading the '''tarball''':
=== Strip details and linking ===
# get the latest stable version from [https://sourceforge.net/projects/atc-pie the project page];
[[File:ATC-pie-screenshot-stripDetailSheet.png|thumbnail|The ATC-pie strip detail sheet]]
# extract the files to the directory of your choice.
A click on the "new strip" tool bar button (shortcut {{key press|F2}}) or double-click on an empty strip rack or bay space will open a dialog to fill flight details on a fresh blank strip, e.g. callsign, type of aircraft, destination, etc. Double-clicking on an existing strip allows to edit the filled details.


To clone the Git '''repository''':
If providing radar service, strips should be '''linked''' to identified contacts to inform the radar display with the filled details, e.g. assigned altitude, and enable joint selection. To link a strip to a radar contact, select one and middle-click on the other. Conflicts between strip details and the values squawked by the linked transponder will mark the strip with a "!!XPDR" warning.
: <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:
A strip can also be linked to a filed flight plan (FPL). This will make radar and strip display fall back on filed information for missing details. The strip does not warn of mismatching information between the two because it is normal for the strip information to be updated as the flight progresses.
: <code>git pull</code>


=== Starting the program ===
All together, a selection can therefore involve up to three linked elements: strip, radar contact, flight plan. From the strip menu at the bottom of any strip panel, you can pull details from linked elements (copy them to the selected strip), or push strip details to their linked flight plan if necessary. If you use linking carefully, auto-fill options are available from the general settings, to fill blank strip details with newly-linked information. Unlinking is possible with {{key press|Shift}}+middle-click.
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 <code>ATC-pie.py</code> 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:
For fast and efficient service, every initial contact by a pilot should basically make you hit {{key press|F2}} and type the spoken callsign. You should then soon figure out if:
: <code>./ATC-pie.py ICAO</code>
* you already have a strip for that contact: a "!!dup" warning appears next to the input field;
If no ICAO code is given, good old KSFO will be chosen as default.
* a flight plan is filed whose details can be linked immediately: a list of candidate FPL matches is displayed in the bottom row, which you can select from to link on dialog save;
* a flight plan must be filed, e.g. IFR departure not filed by lazy pilot: save the dialog and use the {{key press|Shift+F3}} shortcut to create a new FPL linked to the selected strip.


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:
=== Strip placeholders ===
: <code>./ATC-pie.py --ctr=location_code radar_position</code>
ATC-pie provides with three types of placeholders for flight strips: ''racks'', ''loose strip bays'' and ''runway boxes''. According to your ATC position and local facilities, you should choose and arrange your placeholders for optimal control. Strips can then be moved between them using mouse drag and drop.
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:
[[File:ATC-pie-screenshot-stripRacks.png|thumbnail|Strip rack panel]]
: <code>./ATC-pie.py location_code</code>
A '''strip rack''' is the preferred way of keeping track of a sequence, e.g. a departure queue at a runway threshold. Rack panels can be created from the main window workspace, popped out as separate windows, and a persistent one can be found among the available docks. You can create as many racks as you wish in every panel. Double click on a rack's name to rename it or edit its properties. Use mouse drag to move strips up and down a rack sequence.


Besides the location code argument, the following '''command line options''' are available:
A '''loose strip bay''' allows free-hand positioning of strips in its reserved space. Such bays are useful for unsequenced traffic, or to map out relative positions when controlling without a radar. You may also import background images, e.g. a ground chart to keep visual track of taxiing aircraft and vehicles. See <code>CONFIG/bg/Notice</code> to learn how.
{| class="wikitable"
 
! Option || Effect and argument specification || Default
[[File:ATC-pie-screenshot-runwayReserved.png|thumbnail|Reserved runway marked in yellow]]
|-
A '''runway box''' is a placeholder for a single strip, named after a physical runway and denoting a clearence to use it (enter, cross, land...). Runway boxes are contained in their own dock, with one made visible for each runway marked as in use in either direction. Thorough use of runway boxes will help you avoid bad mistakes like clear an aircraft to land over lined up traffic. When freed, runway boxes start and display a timer together with the wake turbulance category of the last contained strip to help with TKOF/LDG separation. What is more, if you use radar, a filled runway box marks the runway as ''reserved'' on the scope.
| --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)
 
|-
Besides, there are two other places a strip can be dropped on, usually when releasing a contact:
| --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
* an ATC callsign in the ATC panel to initiate a handover (or CPDLC transfer/instruction if {{key press|Alt}} is pressed);
|-
* a '''strip shelf''' (flat button at the bottom of strip panels), which clears the strip from your workbench and stores it as shelved.
| --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)
 
|-
== Vectors, routes and separation ==
| --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 ===
ATC-pie can register and analyse issued vectors and routes to:
A few things you will want to do when running ATC-pie for the first time:
* inform strip and radar display;
* 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]].
* help monitor traffic, checking tracked positions against route/vector assignments;
* 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.
* help manage traffic, anticipating route and FL conflicts between controlled aircraft.
* 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. :-(
=== Vectors ===
[[File:ATC-pie-screenshot-courseAndAssignmentsGraphics.png|thumbnail|Course/vector drawing for linked radar contact]]
Registering vectors on strips enhances the drawing of linked radar contacts, enables easy monitoring of tracks and detection of aircraft flying off course. To register vectors automatically when a radar contact is linked to a strip, use the following mouse gestures:
* click and drag out of a radar contact to issue a heading vector;
* holding {{key press|Shift}}, click and drag vertically for altitude/FL vectors;
* holding {{key press|Shift}}, click and drag horizontally for speed instructions;
* holding {{key press|Shift}}, double-click on the radar target to clear registered vecors from the linked strip.


== Feature notes ==
See [https://www.youtube.com/watch?v=BvA3MRlGJjU video 5] of the tutorial for more on vectoring, and check the quick reference ''display conventions'' to interpret the lines and colours of the course and vector graphics around radar contacts.
This section describes a few major features. A more exhaustive list can be found in the main article.


=== Routes and conflict warnings ===
NB: In network sessions, an appropriate text chat instruction is suggested for every mouse vectoring action. This allows you to send it easily, for example to pilots whose communications are limited to text chat.
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.


=== Routes ===
[[File:ATC-pie-screenshot-routeDetailsView.png|thumbnail|Route details dialog with world path drawn, available when both end airfields are recognised]]
[[File:ATC-pie-screenshot-routeDetailsView.png|thumbnail|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:
A route is analysed for every strip with recognised departure and destination airports (entry fields both turned green), as follows:
* route tokens are whitespace-separated;
* 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);
* each recognised navpoint token (radio navigation beacon, 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;
* if ambiguous (navpoint names are not all unique around the world), a waypoint is 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).
* other tokens are kept as route leg specifications to the following waypoint, e.g. airways between fixes.


[[File:ATC-pie-screenshot-routeDrawing.png|thumbnail|Assigned routes can be drawn as dotted lines on the radar scope when linked to contacts]]
[[File:ATC-pie-screenshot-routeDrawing.png|thumbnail|Assigned routes are drawn as dashed 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:
Routes on flight plans and strips are viewable in a route dialog, showing geodesic paths, headings and leg distances on a world map. When a specified route is 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 viewing button enabled;
* 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 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 route to go is drawn as a dashed line on the radar (unless aircraft is inbound and near enough);
* the radar tag 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 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.
** 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.
NB: If DEP and ARR airports are not both recognised, radar tags show the strip destination detail if it is filled, possibly with a heading if it is recognised.


[[File:ATC-pie-screenshot-separationRings.png|thumbnail|Separation rings, coloured when a conflict is detected and involving the aircraft (see table)]]
See tutorial [https://www.youtube.com/watch?v=LfdukpBc90w video 7] for a demonstration of routes.
 
=== Conflicts and anticipation ===
[[File:ATC-pie-screenshot-routeConflictDetection.png|thumbnail|Route conflict depiction]]
[[File:ATC-pie-screenshot-routeConflictDetection.png|thumbnail|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.
ATC-pie 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.
When looking for conflicts, a horizontal (ground projection) path is considered for aircraft with a linked strip and an assigned route or heading. 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. When the projections of two aircraft intersect, a conflict is anticipated if the respective intervals between the current and assigned altitudes overlap. When an aircraft's altitude is unknown, the assigned altitude will be assumed. If an altitude assignment is missing, a ''possible'' conflict is reported.


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.
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.
Line 103: Line 96:
! Alarm || Shown on scope (default colours) || Meaning
! Alarm || Shown on scope (default colours) || Meaning
|-
|-
| Separation incident || Bright red intersecting circles || Separation loss between aircraft
| Separation incident || Thick bright red intersecting circles || Separation loss between aircraft
|-
|-
| Path conflict || Red circles and paths || Anticipated paths and altitudes are intersecting
| 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
| Possible path conflict || Yellow circles and paths || Paths intersecting but some altitudes unknown
|}
|}


=== Playing solo ===
== Communications with aircraft ==
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.
=== Voice radio ===
In solo sessions, voice radio interaction is simulated through speech recognition of instructions and read-back synthesis. Use the {{key press|Ctrl}} key to PTT.  


[[File:ATC-pie-screenshot-handoverPane-solo.png|thumbnail|Handover pane when playing solo in airport mode, assuming all three available positions]]
In FlightGear and FSD network sessions, multiple radios can be opened and tuned in simultaneously. You can transmit on either one by holding down the PTT button of the chosen radio, or on a selected set (''Kbd PTT'' boxes ticked) using the {{key press|Ctrl}} key. This lets you PTT on multiple frequencies at once (merged frequencies), for example to service GND+TWR frequencies in view of splitting them seemlessly again later. To monitor frequencies without attending them, a trick is to set their volume to "soft" to tell them apart.
{| class="wikitable" style="text-align:center"
|+ Handovers with virtual ATCs in airport mode
|-
| || colspan="2" | Departure strips || colspan="2" | Arrival strips
|-
! Assuming positions || Receive from || Hand over to || Receive from || Hand over to
|-
! DEP only
| TWR || CTR || colspan="2" | N/A
|-
! APP only
| colspan="2" | 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 [https://www.youtube.com/watch?v=BvA3MRlGJjU 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.
Note: Except for solo sessions, you may always use a separate voice communication program for radio. In this case, try making the same {{key press|Ctrl}} key the PTT to preserve other features such as RDF for receiving stations in FG sessions, or the ''PTT turns off notification sounds'' option recommended if not wearing a headset.


Things you can train for:
=== CPDLC ===
* approach in dense traffic: select APP position only and increase traffic density;
When [[CPDLC]] is serviced (location setting), aircraft can establish a data link from their cockpit for a direct text communication channel supplementing the radio frequency. You can monitor connections from the CPDLC dock and open a window for each active or terminated connection in the CPDLC history. Combining the {{key press|Alt}} key with a double-click on a strip or radar contact opens the current or latest dialogue for the selected callsign.
* 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) ===
Each active CPDLC dialogue window allows to manually compose preformatted or free text message elements. But the most frequent and convenient way of creating message elements is to combine the {{key press|Alt}} key with a mouse gesture (also see ''Mouse gestures'' in the quick reference):
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.
* click-and-drag vectoring gesture to send a heading, altitude/FL or speed instruction (see [[#Vectors|section on vectors]]);
* strip drop on an ATC to initiate a CPDLC authority transfer or to send the aircraft a "contact" instruction;
* "OK" button click in the instruction panel to send the corresponding formatted instruction.


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.
Created message elements are appended to the message buffer in the connection dialogue window until you send the message manually. The other party must then acknowledge it before it times out.


When '''playing teacher''':
=== Radio text chat ===
* The teaching console dock is enabled, which you should keep visible for efficient control of the student's environment.
Although voice communications should be encouraged for realism whenever possible, ATC-pie has a powerful text chat system for keyboard interaction with pilots in network sessions. In FlightGear sessions, all messages from within at least 100 NM and up to the radar range are visible in the chat. In FSD sessions, whose protocol simulates text frequencies, ATC-pie tunes the chat to the "publicised frequency" in the radio panel.
* 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.
'''Text aliases''' are dollar-prefixed words that ATC-pie tries to replace with context-dependant values when sent. For example, <code>$metar</code> expands to the current primary station weather. This allows to send/save formatted messages like "Current weather is $metar" instead of copy-pasting a weather look-up for every such message.


Note: unlike in FlightGear games where limitations apply (see section further down), all strips are exchangeable in tutorial sessions.
Predefined aliases such as <code>$metar</code> take values that are specified by the program and may depend on the local environment (weather, declination, airport elevation...), on your configuration (transition altitude, runways in use...) or on the current selection (QDM to airport, assigned route...). They are all listed with their meaning in the "quick reference", ''Text aliases'' section.


=== Tower viewing ===
All other aliases will be considered custom, in other words expected to take a value specified by you, on either of the following levels:
[[File:ATC-pie-screenshot-towerViewing.png|thumbnail|Tower viewing, following a departing aircraft]]
* world (value saved for replacement anywhere that the program will be opened), in the general notes (notepad dock);
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.
* location (saved for this airport or centre), in the local notes;
* single aircraft contact (by selected strip), in the strip comments.


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.
Here is how ATC-pie decides what to do with a text alias of the form <code>$foo</code> in a sent message:
# If it is one of the predefined list, the specified substitution is performed. If not, it is a custom alias and we carry on to the next step.
# Look for a line beginning with <code>foo=</code> in the general notes. If one is found, the alias is replaced with what follows the '<code>=</code>' character.
# Look for a line beginning with <code>foo=</code> in the local notes. If one is found, the alias is replaced with what follows the '<code>=</code>' character.
# If a strip is part of the current selection, search likewise in its comment field and substitute if the search succeeds.
# Substitution is unsuccessful. ATC-pie will open an edit box so that you can review your message before sending it.


Running internally only requires FlightGear installed on your computer. A basic installation is enough, but:
Moreover, ATC-pie strips everything up to the first '''pipe character''' (<code>|</code>) in the message if any, before it is processed and sent. You may test this by sending "stripped part|sent part" and observe that only the "sent part" makes it to the message contents. You can therefore make your life easier with piped shortcuts in your preset message list. They will pop up like any other message in the filtered menu as you type. 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:
* not all aircraft will be drawn properly if you do not have the corresponding [[Aircraft|models]] installed—it is up to you to add models or create substitution links (in your [[$FG_ROOT|FlightGear root directory]] or in <code>resources/fg-aircraft</code> according to the <code>Notice</code> file), or be happy with the default blue and yellow glider that will stand for any missing model;
: <code>.qdm|Heading to airport $qdm</code>
* more importantly, you will need the [[scenery]] for your airport if you want anything exciting to see (and not sea!)—go to [http://www.flightgear.org/download/scenery/ 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 <code>x</code>/<code>X</code> keys to change the zoom level from the view window (this is direct FlightGear input).
Lastly, if a troll or angry user is polluting your session with undesired messages, 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.


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.
== ATC coordination ==


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:
"ATC coordination" refers to the following:
* ''HHH'' is the host on which ATC-pie is running (same value for all viewers);
* strip exchange, i.e. sending and receiving strips (handovers);
* ''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);
* ATC phone lines, for private voice calls (except in solo sessions);
* ''TTT'' is the network polling frequency (100 is common practice; change as desired if you know what you are doing);
* CPDLC authority transfers;
* ''YYY'' is the port number used by the viewer for FGMS packet reception.
* ''who-has'' requests, to query ATCs about who is claiming control of callsigns;
* ATC text chat, to exchange text messages with other ATCs (except in solo sessions).


=== FlightGear strip exchange (handovers) and OpenRadar interoperability ===
=== Strip exchange ===
[[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 "GND"]]
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:
To hand a strip over, drag it and drop it on the recipient in the list of controllers in the ''ATC coordination'' dock. A received strip appears with an identification of the sender which disappears as soon as the strip is clicked on.
* 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:
A received strip lands on the collecting rack set for the sender if any (double-click on a rack name to add an ATC callsign from which to collect strips), or on the "Default" rack otherwise. It may link automatically to an identified radar contact according to the selected auto-link options (general settings).
* 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:
See [https://www.youtube.com/watch?v=oQIud-cAlT4 tutorial video 6] for a presentation of the feature.
* 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.
=== ATC phone lines ===
Phone lines allow to call and talk to other ATCs directly from the ''ATC coordination'' dock. Each line has an outgoing state that you control, toggling between open and closed with a double-click on its phone icon. Opening a line places a call to the connected ATC, showing as "incoming" on their side. When two parties have their line open to one another, they are in direct communication (no push-to-talk). In other words, opening an incoming call puts you on the phone with the caller. Closing a call hangs up the active line, but you can pick it back up as long as the other party holds it open ("still incoming" for you).


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].
You can only talk to one ATC at a time but may place multiple outgoing calls. If a call you placed is answered while you are in another call, the answered call switches to show as incoming without interrupting the one in progress. Conversely, opening (answering) an incoming call while already in another call drops the current line. An incoming call you answer which turns to "placed" (outgoing only) instead of "in progress" means that the other party is already on the phone and is now seeing an incoming call from you.


=== Background images ===
=== ATC text chat ===
[[File:ATC-pie-screenshot-backgroundPixmapDrawing.png|thumbnail|Pixmap image example with a topographic map shot around LIMW (Aosta, Italy)]]
The ATC text messaging system allows to chat with other ATCs in channels that are separate from the "radio text chat" read by pilots. It offers private channels for one-to-one conversations, and a general ATC chat room in network sessions, readable by all connected ATCs.
[[File:ATC-pie-screenshot-backgroundHandDrawing.png|thumbnail|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 <code>resources/bg-img/Notice</code> file explains how to import and draw background images.
'''Note on interoperability in FG sessions''': While only ATC-pie integrates ATC text chat in its interface, other users can interact with a regular IRC client connected to <code>mpirc.flightgear.org</code>, with their FlightGear network callsign as IRC nickname, and joining the set IRC channel. They will be able to send and receive public and private messages and chat with everybody, at the only cost of ignoring the system messages that will sometimes appear on their side.


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.
== Solo sessions ==
:<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:
In solo sessions, you control virtual IFR planes, receiving and handing over strips to virtual ATCs depending on your position and the aircraft's intentions. You can train as an en-route controller in CTR mode, or as an airport controller in AD mode, where four combinable positions are available:
# 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.
* ground (GND), to taxi aircraft between parking positions and runways;
# 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.
* tower (TWR), to control runways and immediate surroundings;
* departure (DEP), to bring departing traffic to their exit point;
* approach (APP), to vector arrivals onto final.


=== Text chat ===
=== Objectives ===
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.
In '''CTR mode''', 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 routes.


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.
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 or visual. Assuming TWR, you must clear them to land when appropriate, i.e. cleared for ILS approach or expected runway reported in sight. If landing cannot take place (too high, not cleared...), aircraft will go around. Controlling GND, you must move inbound traffic near their parking position once they have vacated the runway, and hand them over to the ramp. Outbound traffic must be brought to hold short of a runway threshold and report ready for departure with TWR. If you assume 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 in their route. Entry and exit points are configurable in <code>CONFIG/nav/AD-entry-exit</code> (see <code>Notice</code> in the directory).


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.
[[File:ATC-pie-screenshot-handoverPane-solo.png|thumbnail|Handover pane in an AD solo session, assuming all three available positions]]
{| class="wikitable" style="text-align:center"
|+ Handovers with virtual ATCs in airport mode
|-
| || colspan="2" | Departure strips || colspan="2" | Arrival strips
|-
! Assuming positions || Receive from || Hand over to || Receive from || Hand over to
|-
! GND only
| DEL || TWR || TWR || Ramp
|-
! TWR only
| GND || DEP || APP || GND
|-
! DEP only
| TWR || CTR || colspan="2" | N/A
|-
! APP only
| colspan="2" | N/A || CTR || TWR
|-
! TWR+GND
| DEL || DEP || APP || Ramp
|-
! TWR+DEP
| GND || CTR || APP || GND
|-
! TWR+APP
| GND || DEP || CTR || GND
|-
! APP+DEP
| TWR || CTR || CTR || TWR
|-
! TWR+GND+DEP
| DEL || CTR || APP || Ramp
|-
! TWR+GND+APP
| DEL || DEP || APP || Ramp
|-
! TWR+APP+DEP
| GND || CTR || CTR || GND
|-
! All 4
| DEL || CTR || CTR || Ramp
|}


Here is how ATC-pie decides what to do with a text alias of the form <code>$foo</code> on chat message send:
=== Instructing aircraft ===
# 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.
[[File:ATC-pie-screenshot-taxiInstructionTool.png|thumbnail|Click&drag taxi instruction tool at OMDB ground]]
# 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 '='.
Instructions are given through different means:
# Perform the same search through the local notes. If nothing is found, consider the current selection.
* provided the speech recognition modules are installed, you can turn on voice instructions from the solo simulation settings dialog and instruct aircraft through your microphone, using the {{key press|Ctrl}} key as push-to-talk and standard phraseology (see the quick reference tab about it);
# If a strip is part of the current selection, look inside the comment field and search likewise.
* if voice instructions are turned off:
# Substitution is unsuccessful. ATC-pie will open an edit box so that you can review your message before sending it.
** mouse vector assignments issue the corresponding instructions (see section on vectors above);
** handoffs are issued when dropping strips on an ATC receiver;
* instruct taxi routes by dragging out of radar contacts when they are considered on the ground (low enough or squawking GND);
* the dockable instruction panel works regardless of voice vs. mouse selection;
* alternatively, if the aircraft is connected to CPDLC, you can send instructions through the [[#CPDLC|data link]].


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.
Instructions from the panel are always issued to the callsign entered in the top field, which should fill automatically on aircraft or strip selection when a callsign is known. Therefore, make sure you do not mess up your strip links or your instructions will realistically be acknowledged and followed by the wrong aircraft.


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:
=== Need a scenario? ===
: <code>.qdm|Heading to airport $qdm</code>
Things you can train for:
 
* towering a single runway with mixed traffic: select TWR position and an equal balance of departures and arrivals;
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.
* optimising approach spacing in dense traffic: select APP position only, increase traffic density, turn on spacing hints and try to stabilise them all at "3:00" for example;
 
* change of runways (e.g. irl after wind direction change): start with APP+TWR and select a runway for arrivals at least, run the simulation for a while and change for opposite runway use;
== Tips ==
* CTR mode with a low ceiling to increase the number of conflicts to resolve;
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 <code>settings/colours.ini</code> 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 <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.
 
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.
* 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.
== Teacher & student connections (ATC tutoring) ==


Resolving '''strip–FPL conflicts''':
This session type is made to bring an ATC student and a teacher together for tutorial sessions. 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. The teacher creates and manipulates traffic for the student to work with, controls the weather and decides on the ATC neighbours. Strip exchange and ATC text chat is possible, either between both parties ("offline" exchanges) or between the student and the virtual ATCs (in-sim coordination). All exchanges are monitored by the teacher, and transparent to the student. The teacher can also snapshot traffic position situations to recall them later.
* 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''':
In '''teacher sessions''':
* 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);
* The teaching console is enabled, which allows you to control most aspects of the environment visible to the student.
* 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).
* You create new traffic holding {{key press|Shift}} down with a right click-and-drag on the radar specifying the position and face heading. A dialog pops up and allows you to choose a callsign (one is initially generated), altitude and other details. If near a ground route node, a parking position or runway, you can create it on the ground, ready to taxi or for departure (NB: parking overrides position/heading input).
* Traffic is initially created in an "unspawned" state (radar contact marked "+"), in other words visible to you but not to the student. This allows you to set its transponder or get it into a certain state before spawning it into the student's world.
* Controlling the traffic is done in the same way as in solo sessions without voice, i.e. using the click&drag vector and taxi tools and the instruction dock. The only difference is that you control the selected aircraft directly, regardless of your strip links and details. You therefore do not need a strip and a correctly filled callsign to instruct a pilot, though it is a good idea to have one if you want your vectors registered and drawn on the radar. The traffic creation dialog offers to create a linked strip with every new aircraft.
* You may pause the whole simulation, or freeze each aircraft individually. Frozen aircraft will result in stationary flights on the student's radar.
* The ATC text chat system allows to chat to the student directly as the teacher, and to simulate private ATC conversations with the student (select callsign to interact as).
* To exchange strips, drop them on "Student" and select whom the strip should appear from on the student's side. Note that for your convenience in further control of the traffic, teacher strips do not disappear on handovers;
* CPDLC is supported, the dialogue windows reflecting the change of perspective (ACFT instead of ATC) and the {{key press|Alt}} key combinations generating requests rather than instructions.


[[Category:ATC-pie]]
[[Category:ATC-pie]]

Latest revision as of 15:44, 31 January 2023

This article is a guide to the air traffic control simulation program ATC-pie, describing some of its major features. A more exhaustive list can be found in the main article. For download and installation help, refer to the ATC-pie installation guide. For support and troubleshooting, the ATC-pie FAQ might get you an answer first. Otherwise kindly ask on the dedicated FlightGear sub-forum so that the discussion is public.

Other ways to learn the program are:

  • to watch the online video tutorial;
  • to read the in-app Quick reference available from the Help menu (summary of mouse/keyboard gestures, display conventions...);
  • to connect with a skilled teacher as a student (personal training);
  • to train solo!

Flight strips

Whether electronic (dematerialised) or on paper, printed automatically or filled by hand, the flight progress strip is the essential piece of air and ground traffic control. Every aircraft in contact is represented by a unique strip on the ATC workbench, and every strip represents a unique contact, present or expected. This ensures that no aircraft is ever forgotten about. Strip positioning and updating then enable to monitor the aircraft's status, sequence number, position, intentions, etc.

Strip details and linking

The ATC-pie strip detail sheet

A click on the "new strip" tool bar button (shortcut F2) or double-click on an empty strip rack or bay space will open a dialog to fill flight details on a fresh blank strip, e.g. callsign, type of aircraft, destination, etc. Double-clicking on an existing strip allows to edit the filled details.

If providing radar service, strips should be linked to identified contacts to inform the radar display with the filled details, e.g. assigned altitude, and enable joint selection. To link a strip to a radar contact, select one and middle-click on the other. Conflicts between strip details and the values squawked by the linked transponder will mark the strip with a "!!XPDR" warning.

A strip can also be linked to a filed flight plan (FPL). This will make radar and strip display fall back on filed information for missing details. The strip does not warn of mismatching information between the two because it is normal for the strip information to be updated as the flight progresses.

All together, a selection can therefore involve up to three linked elements: strip, radar contact, flight plan. From the strip menu at the bottom of any strip panel, you can pull details from linked elements (copy them to the selected strip), or push strip details to their linked flight plan if necessary. If you use linking carefully, auto-fill options are available from the general settings, to fill blank strip details with newly-linked information. Unlinking is possible with Shift+middle-click.

For fast and efficient service, every initial contact by a pilot should basically make you hit F2 and type the spoken callsign. You should then soon figure out if:

  • you already have a strip for that contact: a "!!dup" warning appears next to the input field;
  • a flight plan is filed whose details can be linked immediately: a list of candidate FPL matches is displayed in the bottom row, which you can select from to link on dialog save;
  • a flight plan must be filed, e.g. IFR departure not filed by lazy pilot: save the dialog and use the Shift+F3 shortcut to create a new FPL linked to the selected strip.

Strip placeholders

ATC-pie provides with three types of placeholders for flight strips: racks, loose strip bays and runway boxes. According to your ATC position and local facilities, you should choose and arrange your placeholders for optimal control. Strips can then be moved between them using mouse drag and drop.

Strip rack panel

A strip rack is the preferred way of keeping track of a sequence, e.g. a departure queue at a runway threshold. Rack panels can be created from the main window workspace, popped out as separate windows, and a persistent one can be found among the available docks. You can create as many racks as you wish in every panel. Double click on a rack's name to rename it or edit its properties. Use mouse drag to move strips up and down a rack sequence.

A loose strip bay allows free-hand positioning of strips in its reserved space. Such bays are useful for unsequenced traffic, or to map out relative positions when controlling without a radar. You may also import background images, e.g. a ground chart to keep visual track of taxiing aircraft and vehicles. See CONFIG/bg/Notice to learn how.

Reserved runway marked in yellow

A runway box is a placeholder for a single strip, named after a physical runway and denoting a clearence to use it (enter, cross, land...). Runway boxes are contained in their own dock, with one made visible for each runway marked as in use in either direction. Thorough use of runway boxes will help you avoid bad mistakes like clear an aircraft to land over lined up traffic. When freed, runway boxes start and display a timer together with the wake turbulance category of the last contained strip to help with TKOF/LDG separation. What is more, if you use radar, a filled runway box marks the runway as reserved on the scope.

Besides, there are two other places a strip can be dropped on, usually when releasing a contact:

  • an ATC callsign in the ATC panel to initiate a handover (or CPDLC transfer/instruction if Alt is pressed);
  • a strip shelf (flat button at the bottom of strip panels), which clears the strip from your workbench and stores it as shelved.

Vectors, routes and separation

ATC-pie can register and analyse issued vectors and routes to:

  • inform strip and radar display;
  • help monitor traffic, checking tracked positions against route/vector assignments;
  • help manage traffic, anticipating route and FL conflicts between controlled aircraft.

Vectors

Course/vector drawing for linked radar contact

Registering vectors on strips enhances the drawing of linked radar contacts, enables easy monitoring of tracks and detection of aircraft flying off course. To register vectors automatically when a radar contact is linked to a strip, use the following mouse gestures:

  • click and drag out of a radar contact to issue a heading vector;
  • holding Shift, click and drag vertically for altitude/FL vectors;
  • holding Shift, click and drag horizontally for speed instructions;
  • holding Shift, double-click on the radar target to clear registered vecors from the linked strip.

See video 5 of the tutorial for more on vectoring, and check the quick reference display conventions to interpret the lines and colours of the course and vector graphics around radar contacts.

NB: In network sessions, an appropriate text chat instruction is suggested for every mouse vectoring action. This allows you to send it easily, for example to pilots whose communications are limited to text chat.

Routes

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

A route is analysed 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 (radio navigation beacon, 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 the nearest homonym to the point beginning the leg;
  • other tokens are kept as route leg specifications to the following waypoint, e.g. airways between fixes.
Assigned routes are drawn as dashed lines on the radar scope when linked to contacts

Routes on flight plans and strips are viewable in a route dialog, showing geodesic paths, headings and leg distances on a world map. When a specified route is linked to a radar contact, ATC-pie works out its current leg based on distance to destination, and:

  • details of the current leg are displayed in the selection info pane, and the route viewing button enabled;
  • the strip shows only the remainder of the route for this contact;
  • the route to go is drawn as a dashed line on the radar (unless aircraft is inbound and near enough);
  • the radar tag 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.

NB: If DEP and ARR airports are not both recognised, radar tags show the strip destination detail if it is filled, possibly with a heading if it is recognised.

See tutorial video 7 for a demonstration of routes.

Conflicts and anticipation

Route conflict depiction

ATC-pie 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 aircraft with a linked strip and an assigned route or heading. 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. When the projections of two aircraft intersect, a conflict is anticipated if the respective intervals between the current and assigned altitudes overlap. When an aircraft's altitude is unknown, the assigned altitude will be assumed. If an altitude assignment is missing, a possible conflict is reported.

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 Thick 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 and paths Paths intersecting but some altitudes unknown

Communications with aircraft

Voice radio

In solo sessions, voice radio interaction is simulated through speech recognition of instructions and read-back synthesis. Use the Ctrl key to PTT.

In FlightGear and FSD network sessions, multiple radios can be opened and tuned in simultaneously. You can transmit on either one by holding down the PTT button of the chosen radio, or on a selected set (Kbd PTT boxes ticked) using the Ctrl key. This lets you PTT on multiple frequencies at once (merged frequencies), for example to service GND+TWR frequencies in view of splitting them seemlessly again later. To monitor frequencies without attending them, a trick is to set their volume to "soft" to tell them apart.

Note: Except for solo sessions, you may always use a separate voice communication program for radio. In this case, try making the same Ctrl key the PTT to preserve other features such as RDF for receiving stations in FG sessions, or the PTT turns off notification sounds option recommended if not wearing a headset.

CPDLC

When CPDLC is serviced (location setting), aircraft can establish a data link from their cockpit for a direct text communication channel supplementing the radio frequency. You can monitor connections from the CPDLC dock and open a window for each active or terminated connection in the CPDLC history. Combining the Alt key with a double-click on a strip or radar contact opens the current or latest dialogue for the selected callsign.

Each active CPDLC dialogue window allows to manually compose preformatted or free text message elements. But the most frequent and convenient way of creating message elements is to combine the Alt key with a mouse gesture (also see Mouse gestures in the quick reference):

  • click-and-drag vectoring gesture to send a heading, altitude/FL or speed instruction (see section on vectors);
  • strip drop on an ATC to initiate a CPDLC authority transfer or to send the aircraft a "contact" instruction;
  • "OK" button click in the instruction panel to send the corresponding formatted instruction.

Created message elements are appended to the message buffer in the connection dialogue window until you send the message manually. The other party must then acknowledge it before it times out.

Radio text chat

Although voice communications should be encouraged for realism whenever possible, ATC-pie has a powerful text chat system for keyboard interaction with pilots in network sessions. In FlightGear sessions, all messages from within at least 100 NM and up to the radar range are visible in the chat. In FSD sessions, whose protocol simulates text frequencies, ATC-pie tunes the chat to the "publicised frequency" in the radio panel.

Text aliases are dollar-prefixed words that ATC-pie tries to replace with context-dependant values when sent. For example, $metar expands to the current primary station weather. This allows to send/save formatted messages like "Current weather is $metar" instead of copy-pasting a weather look-up for every such message.

Predefined aliases such as $metar take values that are specified by the program and may depend on the local environment (weather, declination, airport elevation...), on your configuration (transition altitude, runways in use...) or on the current selection (QDM to airport, assigned route...). They are all listed with their meaning in the "quick reference", Text aliases section.

All other aliases will be considered custom, in other words expected to take a value specified by you, on either of the following levels:

  • world (value saved for replacement anywhere that the program will be opened), in the general notes (notepad dock);
  • location (saved for this airport or centre), in the local notes;
  • single aircraft contact (by selected strip), in the strip comments.

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

  1. If it is one of the predefined list, the specified substitution is performed. 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. If one is found, the alias is replaced with what follows the '=' character.
  3. Look for a line beginning with foo= in the local notes. If one is found, the alias is replaced with what follows the '=' character.
  4. If a strip is part of the current selection, search likewise in its comment field and substitute if the search succeeds.
  5. Substitution is unsuccessful. ATC-pie will open an edit box so that you can review your message before sending it.

Moreover, ATC-pie strips everything up to the first pipe character (|) in the message if any, before it is processed and sent. You may test this by sending "stripped part|sent part" and observe that only the "sent part" makes it to the message contents. You can therefore make your life easier with piped shortcuts in your preset message list. They will pop up like any other message in the filtered menu as you type. 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, 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.

ATC coordination

"ATC coordination" refers to the following:

  • strip exchange, i.e. sending and receiving strips (handovers);
  • ATC phone lines, for private voice calls (except in solo sessions);
  • CPDLC authority transfers;
  • who-has requests, to query ATCs about who is claiming control of callsigns;
  • ATC text chat, to exchange text messages with other ATCs (except in solo sessions).

Strip exchange

Example of a strip received from "GND"

To hand a strip over, drag it and drop it on the recipient in the list of controllers in the ATC coordination dock. A received strip appears with an identification of the sender which disappears as soon as the strip is clicked on.

A received strip lands on the collecting rack set for the sender if any (double-click on a rack name to add an ATC callsign from which to collect strips), or on the "Default" rack otherwise. It may link automatically to an identified radar contact according to the selected auto-link options (general settings).

See tutorial video 6 for a presentation of the feature.

ATC phone lines

Phone lines allow to call and talk to other ATCs directly from the ATC coordination dock. Each line has an outgoing state that you control, toggling between open and closed with a double-click on its phone icon. Opening a line places a call to the connected ATC, showing as "incoming" on their side. When two parties have their line open to one another, they are in direct communication (no push-to-talk). In other words, opening an incoming call puts you on the phone with the caller. Closing a call hangs up the active line, but you can pick it back up as long as the other party holds it open ("still incoming" for you).

You can only talk to one ATC at a time but may place multiple outgoing calls. If a call you placed is answered while you are in another call, the answered call switches to show as incoming without interrupting the one in progress. Conversely, opening (answering) an incoming call while already in another call drops the current line. An incoming call you answer which turns to "placed" (outgoing only) instead of "in progress" means that the other party is already on the phone and is now seeing an incoming call from you.

ATC text chat

The ATC text messaging system allows to chat with other ATCs in channels that are separate from the "radio text chat" read by pilots. It offers private channels for one-to-one conversations, and a general ATC chat room in network sessions, readable by all connected ATCs.

Note on interoperability in FG sessions: While only ATC-pie integrates ATC text chat in its interface, other users can interact with a regular IRC client connected to mpirc.flightgear.org, with their FlightGear network callsign as IRC nickname, and joining the set IRC channel. They will be able to send and receive public and private messages and chat with everybody, at the only cost of ignoring the system messages that will sometimes appear on their side.

Solo sessions

In solo sessions, you control virtual IFR planes, receiving and handing over strips to virtual ATCs depending on your position and the aircraft's intentions. You can train as an en-route controller in CTR mode, or as an airport controller in AD mode, where four combinable positions are available:

  • ground (GND), to taxi aircraft between parking positions and runways;
  • tower (TWR), to control runways and immediate surroundings;
  • departure (DEP), to bring departing traffic to their exit point;
  • approach (APP), to vector arrivals onto final.

Objectives

In CTR mode, 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 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 or visual. Assuming TWR, you must clear them to land when appropriate, i.e. cleared for ILS approach or expected runway reported in sight. If landing cannot take place (too high, not cleared...), aircraft will go around. Controlling GND, you must move inbound traffic near their parking position once they have vacated the runway, and hand them over to the ramp. Outbound traffic must be brought to hold short of a runway threshold and report ready for departure with TWR. If you assume 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 in their route. Entry and exit points are configurable in CONFIG/nav/AD-entry-exit (see Notice in the directory).

Handover pane in an AD solo session, 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
GND only DEL TWR TWR Ramp
TWR only GND DEP APP GND
DEP only TWR CTR N/A
APP only N/A CTR TWR
TWR+GND DEL DEP APP Ramp
TWR+DEP GND CTR APP GND
TWR+APP GND DEP CTR GND
APP+DEP TWR CTR CTR TWR
TWR+GND+DEP DEL CTR APP Ramp
TWR+GND+APP DEL DEP APP Ramp
TWR+APP+DEP GND CTR CTR GND
All 4 DEL CTR CTR Ramp

Instructing aircraft

Click&drag taxi instruction tool at OMDB ground

Instructions are given through different means:

  • provided the speech recognition modules are installed, you can turn on voice instructions from the solo simulation settings dialog and instruct aircraft through your microphone, using the Ctrl key as push-to-talk and standard phraseology (see the quick reference tab about it);
  • if voice instructions are turned off:
    • mouse vector assignments issue the corresponding instructions (see section on vectors above);
    • handoffs are issued when dropping strips on an ATC receiver;
  • instruct taxi routes by dragging out of radar contacts when they are considered on the ground (low enough or squawking GND);
  • the dockable instruction panel works regardless of voice vs. mouse selection;
  • alternatively, if the aircraft is connected to CPDLC, you can send instructions through the data link.

Instructions from the panel are always issued to the callsign entered in the top field, which should fill automatically on aircraft or strip selection when a callsign is known. Therefore, make sure you do not mess up your strip links or your instructions will realistically be acknowledged and followed by the wrong aircraft.

Need a scenario?

Things you can train for:

  • towering a single runway with mixed traffic: select TWR position and an equal balance of departures and arrivals;
  • optimising approach spacing in dense traffic: select APP position only, increase traffic density, turn on spacing hints and try to stabilise them all at "3:00" for example;
  • change of runways (e.g. irl after wind direction change): start with APP+TWR and select a runway for arrivals at least, run the simulation for a while and change for opposite runway use;
  • CTR mode with a low ceiling to increase the number of conflicts to resolve;
  • etc.

Teacher & student connections (ATC tutoring)

This session type is made to bring an ATC student and a teacher together for tutorial sessions. 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. The teacher creates and manipulates traffic for the student to work with, controls the weather and decides on the ATC neighbours. Strip exchange and ATC text chat is possible, either between both parties ("offline" exchanges) or between the student and the virtual ATCs (in-sim coordination). All exchanges are monitored by the teacher, and transparent to the student. The teacher can also snapshot traffic position situations to recall them later.

In teacher sessions:

  • The teaching console is enabled, which allows you to control most aspects of the environment visible to the student.
  • You create new traffic holding Shift down with a right click-and-drag on the radar specifying the position and face heading. A dialog pops up and allows you to choose a callsign (one is initially generated), altitude and other details. If near a ground route node, a parking position or runway, you can create it on the ground, ready to taxi or for departure (NB: parking overrides position/heading input).
  • Traffic is initially created in an "unspawned" state (radar contact marked "+"), in other words visible to you but not to the student. This allows you to set its transponder or get it into a certain state before spawning it into the student's world.
  • Controlling the traffic is done in the same way as in solo sessions without voice, i.e. using the click&drag vector and taxi tools and the instruction dock. The only difference is that you control the selected aircraft directly, regardless of your strip links and details. You therefore do not need a strip and a correctly filled callsign to instruct a pilot, though it is a good idea to have one if you want your vectors registered and drawn on the radar. The traffic creation dialog offers to create a linked strip with every new aircraft.
  • You may pause the whole simulation, or freeze each aircraft individually. Frozen aircraft will result in stationary flights on the student's radar.
  • The ATC text chat system allows to chat to the student directly as the teacher, and to simulate private ATC conversations with the student (select callsign to interact as).
  • To exchange strips, drop them on "Student" and select whom the strip should appear from on the student's side. Note that for your convenience in further control of the traffic, teacher strips do not disappear on handovers;
  • CPDLC is supported, the dialogue windows reflecting the change of perspective (ACFT instead of ATC) and the Alt key combinations generating requests rather than instructions.