ATC-pie user guide: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
m (Superfluous 1st-level title)
(v1.7.1)
(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 section is a guide to help one download and run '''[[ATC-pie]]''', and lists a few tips on some of its features. Other sources to learn to use 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]].
* the '''online video tutorial''' on ''YouTube'' (follow/bookmark the [https://www.youtube.com/playlist?list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb link to the full playlist]);
* the in-app '''quick reference''' available from the ''Help'' menu (summary of mouse/keyboard gestures, display conventions, etc.).


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 ==
Other sources to learn the program are:
* 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...);
* a skilled '''teacher''' to connect to as a student (personal training);
* to '''play solo'''!


=== Downloading ===
== Flight strips ==
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''':
Whether dematerialised or on physical paper, printed out 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, and every strip represents a contact. This helps to ensure that no aircraft is ever forgotten about. Strip positioning and updating then enable to monitor the aircraft's status, sequence number, position, intentions, etc.
# get the latest stable version from [https://sourceforge.net/projects/atc-pie the project page];
# extract the files to the directory of your choice.


To clone the '''repository''':
=== Filling details and linking ===
: <code>git clone git://git.code.sf.net/p/atc-pie/code ATC-pie</code>
A click on the "new strip" tool bar button (shortcut F2) or double-click on an empty rack space will open a dialog to fill flight details on a fresh strip, e.g. destination, type of aircraft, etc. Double-clicking on an existing strip allows to edit the filled details.


When a new release is announced and if you have cloned the repository, you can update your software with a single command from the downloaded directory:
If providing radar service, strips should be '''linked''' to identified contacts to inform the radar display with the filled details and enable joint selection. To link a strip to a radar contact, select one and middle-click on the other. Conflicts between the strip details and the values squawked by the linked transponder contact are reported: the strip displays a "!!XPDR" warning and the strip dialog labels the conflicting details.
: <code>git pull</code>


=== Starting the program ===
A strip can also be linked to a filed flight plan (FPL) to merge the information. The strip dialog also shows the mismatching information between the two, though this is rather common because the strip typically gets updated as the flight progresses.
Depending on your system and preference, you might be double-clicking, typing stuff or pulling your hair out. In any case what you need to start the program is to run a Python3 interpreter on the <code>ATC-pie.py</code> file in the top-level directory. To start at a chosen airport location, say with code ICAO, add a system command line argument, which may look as simple as:
: <code>./ATC-pie.py ICAO</code>


If no ICAO code is given, good old KSFO will be chosen as default. After a few seconds, you should see the main window appear with a radar scope and a depiction of your airport in the centre.
All together, a selection can involve up to three linked elements: strip, radar contact, flight plan. You can pull details from linked elements to strips (strip panel bottom menu), and push strip details to their linked flight plan if necessary (strip dialog bottom tick box). Unlinking is possible with SHIFT+middle-click. If you use linking carefully, auto-fill options are available from the general settings, to fill blank strip details with newly-linked information.


Additional command line options are available:
For fast and efficient service, every initial contact by a pilot should basically make you hit F2 and type the callsign announced. You should then soon figure out if:
{| class="wikitable"
* a flight plan is already filed: a matching FPL count is displayed near the callsign field as you type, if any (click on the button to view them);
! Option || Effect and argument specification || Default
* a flight plan must be filed (e.g. IFR departure not filed by lazy pilot): select "new FPL" from the bottom line to open a fresh FPL detail sheet to link to the strip;
|-
* he was asked to contact you by a previous ATC, in which case you may have a strip handed over to you already;
| --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)
* etc.
|-
 
| --tower-view-ports=''udp'',''telnet'' || Specify the tower view ports to send/connect to. These can be the same (UDP+TCP on same port), and are used whether the view is a child (internal), local or remote process. || 5010,5010
=== Strip placeholders ===
|-
ATC-pie provides with various placeholders for flight strips, namely ''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.
| --add-view=''host'':''port'' || Register an additional FlightGear instance to forward MP and solo game packets to. This option can be repeated. || (none)
 
|-
[[File:ATC-pie-screenshot-stripRacks.png|thumbnail|Strip rack panel]]
| --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
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 and name them appropriately. Double click on the rack name to edit its properties. Use mouse drag to move strips up and down a rack sequence.
|-
 
| --fgcom-server=''address'' || Set the server used by internal FGCom radio boxes. || fgcom.flightgear.org
A '''loose strip bay''' allows free-hand positioning of strips in its reserved space. Such bays are useful for any kind of 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-img/Notice</code> to learn how.
|-
 
| --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)
[[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 runway and denoting a clearence to use it (enter, cross, land...). Runway boxes are contained in their own dock, and made visible if a corresponding runway is marked in use. 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:
* a connected ATC to initiate a handover;
* a '''strip shelf''' (flat button at the bottom of loose and racked strip panels), which clears the strip from your work bench and stores it as shelved.
 
== Airport scene rendering ==
 
=== Tower view window ===
[[File:ATC-pie-screenshot-towerViewing.png|thumbnail|Tower viewing, following a departing aircraft]]
This feature allows you to overlook your airport and the connected or simulated traffic, like a controller from a tower viewpoint. It allows to choose from the tower positions specified in the source data if any (X-plane seems only to allow for one, but feel free to declare more for ATC-pie), otherwise defaults to somewhere over the airport to allow towering everywhere. 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 to listen for traffic and accept telnet connections.
 
'''Running internally''' only requires FlightGear installed on your computer. A basic installation is enough, but you will need the [[scenery]] for your airport if you want anything exciting to see (and not sea!). Also, aircraft will only be drawn properly if the appropriate [[Aircraft|models]] are available. In FlightGear sessions, the models required are those flown by the pilots. For all other session types, models are chosen according to the ICAO type designators of the aircraft and the specifications in <code>icao2fgfs</code>. Read <code>CONFIG/acft/Notice</code> to understand how ATC-pie chooses models and liveries for its viewers. Aircraft and scenery locations can be filled in the ''System'' settings dialog if they are not in your [[$FG_ROOT|FlightGear root directory]].
 
Connecting to an '''external viewer''' allows to run FlightGear on a different machine and thereby relieve your session from the CPU load a local instance induces. If you want to do so, get a hint of the required positioning options you should start your viewer with, from the tower view tab in the system settings dialog. Of course, scenery, models and liveries must also be available to the running process.
 
In either case, once activated from the ''View'' menu, the tower view '''control pane''' is enabled, from which you can turn to runway points, follow selected aircraft... Direct FlightGear input in the view window is also possible: right click and drag allows to look around, <code>x</code>/<code>X</code> keys change the zoom level, etc.
 
=== Additional scene views ===
You can hook up '''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 from the ''View'' menu. Additional viewers are registered by their host+port address, from the ''View'' menu at run-time or from a custom settings file (see <code>CONFIG/Notice</code>), read at start-up and on explicit reload (''System'' menu).
 
Every such viewer registered on host ''XXX'' and port ''YYY'' should be running on ''XXX'' and started with options <code>--multiplay=out,TTT,HHH,PPP</code> and <code>--multiplay=in,TTT,,YYY</code>, where:
* ''HHH'' is the host on which ATC-pie is running;
* ''PPP'' is the default 5009, or the chosen port number if ATC-pie was started with <code>--views-send-from</code>;
* ''TTT'' is the network polling frequency (100 is common practice; change as desired if you know what you are doing).
 
== Vectors, routes and separation warnings ==


=== 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 multi-player games, check the [[FGCom]] version setting in the ''System'' menu, and try an echo test. Read the <code>resources/fgcom/Notice</code> file if you have problems hearing yourself, and check the FAQ section in this article.
* help monitor traffic, checking against vectors;
* 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.
* anticipate route and FL conflicts between controlled aircraft.
* Set up the airport runway parameters in the airport settings, especially ILS capability if you will be playing solo often at the same location.


Note for multi-player games: callsigns for ATCs are typically expected to start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service: twr, gnd... When choosing your callsign on MP connect, make sure it is unique, 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;
* hold SHIFT, click and drag vertically for altitude/FL vectors;
* hold SHIFT, click and drag horizontally for speed instructions;
* hold SHIFT and double-click 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. See more exhaustive list at the top of this article.


=== Routing 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.


A '''route''' is parsed for every strip with both recognised departure and destination airports (names shown near respective fields on the strip sheet), as follows:
=== Routes ===
[[File:ATC-pie-screenshot-routeDetailsView.png|thumbnail|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;
* 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 (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);
* other tokens are kept as route leg specifications to the following waypoint;
* 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 always 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).


When a route is parsed and a radar contact linked to the strip, the current route leg is detected based on distance to destination, and:
[[File:ATC-pie-screenshot-routeDrawing.png|thumbnail|Assigned routes are drawn as dashed lines on the radar scope when linked to contacts]]
* the route to go is drawn as a dotted line on the radar scope (according to scope "show" options);
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 current leg is displayed in the selection info pane, including any contained specification;
* 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 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 both DEP and ARR airports are not identified, radar tags show the strip destination detail if it is filled, possibly with a heading if it is recognised.
 
See tutorial [https://www.youtube.com/watch?v=LfdukpBc90w video 7] for a demonstration of routes.


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.
=== Conflicts and anticipation ===
[[File:ATC-pie-screenshot-routeConflictDetection.png|thumbnail|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 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 86: Line 119:
! 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
|}
|}


=== Solo training mode ===
== Playing solo ==
This mode allows to train on your own in different situations. Three combinable positions are available:
 
* tower (TWR), controlling runways and immediate surroundings;
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:
* departure (DEP), bringing departing traffic to their exit point;
* ground (GND), to taxi aircraft between parking positions and runways;
* approach (APP), vectoring arrivals onto final.
* 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.


In any case, you will be controlling virtual IFR planes via the software interface, and receiving and handing over strips to virtual ATCs, depending on your position and on the aircraft's intentions (see table below). Approaches can be requested ILS or visual, and the balance between the two is adjustable from the solo mode settings.
=== Objectives ===
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 routes.


Assuming APP, aircraft requesting ILS must be vectored to intercept a runway localiser and cleared for ILS approach, whereas those requesting visual require vectors until they report the expected runway is in sight. Then, approaching aircraft must be handed over to TWR, unless you are in the TWR position as well. If you are, you must clear them to land—or they will climb back up for go-around—and hand them over to ground control (GND) once they have vacated the runway. Tower also manages departures, which appear ready holding short of runways. After take-off, hand over your strips to departure control, unless 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 enough to their exit point if specified.
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. Playing 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 play 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).


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


'''Vectors''' are given by means of the vectoring assignment tool (click&drag on radar contact for heading, with SHIFT for altitude/FL and speed). '''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. Non-vectoring instructions are sent to the callsign entered in the top field, which should fill automatically on aircraft or strip selection if a callsign is known.
=== Instructing aircraft ===
[[File:ATC-pie-screenshot-taxiInstructionTool.png|thumbnail|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 <code>Ctrl</code> 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;
* if the aircraft is connected to CPDLC, you can choose to be prompted to send the instruction through the data link (see ''General settings'' dialog, CPDLC tab).


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:
Things you can train for:
* approach in dense traffic: select APP position only and increase traffic density;
* towering a single runway with mixed traffic: select TWR position and an equal balance of departures and arrivals;
* towering a single runway, optimising its use: 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, play for a while and go back to the dialog to change for the opposite runway;
* 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 change for opposite runway use;
* CTR mode with a low ceiling to increase the number of conflicts to resolve;
* etc.
* etc.


=== Tower viewing ===
== ATC coordination ==
This feature allows you to overlook your airport and the connected (MP) or simulated (solo) traffic, like a controller from a '''tower viewpoint'''. It uses the tower position specified in the source data if any, otherwise defaults to somewhere over the airport to allow towering all available airports.


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.
"ATC coordination" refers to the following:
* strip exchange, i.e. sending and receiving strips (handovers);
* CPDLC transfers between ATCs;
* ATC text chat, to exchange messages between connected ATCs (see ''Communications'' section);
* ''who-has'' requests, to query the system and know who is claiming contact/control of callsigns.


Running internally only requires FlightGear installed on your computer. A basic installation is enough, but:
=== Strip exchange ===
* 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 FlightGear [[$FG_ROOT|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;
[[File:ATC-pie-screenshot-receivedStrip.png|thumbnail|Example of a strip received from "GND"]]
* 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).
To hand a strip over, drag it and drop it on the recipient in the list of connected controllers. Received strips appear on their collecting rack (if defined), with an identification of the sender which disappears as soon as the strip is clicked on. They may link automatically to identified radar contacts, according to the auto-link configuration (general settings). Double-click on the rack name to add an ATC callsign from which to collect strips.


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).
See [https://www.youtube.com/watch?v=oQIud-cAlT4 tutorial video 6] for a presentation of the feature.


You can also connect '''additional viewers''' to your session, for example placed around your airport for exciting camera footage of challenging landings. You will not be able to control those viewers from ATC-pie like the tower viewer, but you will be able to activate/stop the connection with a switch in the application ''View'' menu. To do so, start every additional FlightGear viewer with options <code>--multiplay=out,TTT,HHH,PPP</code> and <code>--multiplay=in,TTT,,YYY</code>, and append an option <code>--add-view=XXX:YYY</code> to your ATC-pie command. In these options:
=== FlightGear sessions and compatibility with OpenRadar ===
* ''HHH'' is the host on which ATC-pie is running (same value for all viewers);
On FlightGear session start, there are two "sub-systems" that can be activated for coordination. They differ in terms of supported features and interoperability with other clients:
* ''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);
* the '''IRC sub-system''' enables all coordination features with other ATC-pie clients, but does not currently operate with other software (recommended in all cases);
* ''TTT'' is the network polling frequency (100 is common practice; change as desired if you know what you are doing);
* the '''OpenRadar handover service''' is [[OpenRadar]]'s native system, which ATC-pie implements to enable coordination with its users, but some limitations apply (see below).
* ''XXX'' is the host where this viewer is started;
Both systems can be enabled together.
* ''YYY'' is the port to use on ''XXX'' for FGMS packet reception by the viewer.


=== Multi-player strip exchange (handovers) and OpenRadar interoperability ===
ATC-pie and OpenRadar's 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:
* OpenRadar's basic processing unit is the FGMS callsign, whereas ATC-pie's is the strip;
* 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;
* 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 and write a callsign on it;
* 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.
* in OpenRadar, a handover must be acknowledged by the receiver for the sender to lose ownership and for all neighbouring users to see it complete, whereas ATC-pie considers that a strip sent is gone and assumed to land on the receiver's rack, 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:
For most interactions to work while respecting both approaches as much as possible, the following principles and restrictions apply to strip exchange:
* ATC-pie users can only hand over strips that are linked to a radar contact (no lone strip can be sent);
* ATC-pie users can only hand over strips to OpenRadar that are linked to a radar contact;
* aircraft under ATC-pie control are not shown as "owned" to OpenRadar users;
* 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;
* handovers from ATC-pie will fail if an OpenRadar user is claiming ownership on the linked radar contact;
* when sending to ATC-pie controllers, OpenRadar users will see their transfers acknowledged straight away, unconditionally.
* when sending to ATC-pie controllers, OpenRadar users will see their transfers acknowledged straight away, unconditionally.


Callsign exchange policy:
Callsign handover policy:
* O-R to ATC-pie: FGMS callsign will appear on the strip, as if the sender had filled the detail properly;
* 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;
* 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.


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.
Features not supported by OpenRadar:
* wake turbulance category on strips (but detail preserved for ATC-pie instances later receiving the strip);
* ATC text messaging;
* CPDLC.


=== Background drawings ===
Note that who-has requests are fully supported.
Background drawings allow to decorate radar scopes with all sorts of maps and useful information about the airspace, terrain or procedures.


There are two ways of drawing in the radar background. One is to import '''image files with 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 and drawing points specified using lat/lon coordinates or navpoints in radar range. The <code>resources/bgdrawings/Notice</code> file explains how to import and create background drawings.
=== FSD sessions and compatibility with Euroscope ===
Euroscope is a popular program to control on VATSIM, a flight simulation network which is historically based on the FSD protocol, although made incompatible with it today. For a long time Euroscope allowed to connect to "plain" FSD servers, until it started being tailored more specifically for VATSIM, and closed the door to outside FSD connections. Older versions of Euroscope are still around, which ATC-pie is able to interact with, but only to a limited extent:
* sending a strip to Euroscope will result in a loss of all strip details but the callsign (which must be connected), the only information left to the recipient being the FPL details for that callsign if any (strip changes made after FPL data retrieval are therefore lost);
* receiving a strip from Euroscope is supported, but the sender will see the hondover pending (never "assumed");
* who-has requests will remain unanswered by Euroscope.


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 drawing 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.
ATC-pie clients interact normally between each other, but note that CPDLC is not supported by the FSD protocol.
:<code>convert -transparent white input-file.png output-file.png</code>


Use the image positioning helper tool in the ''System'' menu if you want to adjust image corners visually rather than programmatically. All visible pixmap drawings will be moved simultaneously, so you can work with several at a time if you need to. On dialog box close, a file is generated in the <code>output</code> folder for you to open and copy/edit, or use as a direct substitution.
== Background images ==


== Tips ==
[[File:ATC-pie-screenshot-backgroundPixmapDrawing.png|thumbnail|Pixmap image example with a topographic map shot around LIMW (Aosta, Italy)]]
Here are a few tips to help you navigate and use the program.
[[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;
* loose strip bays, to move unracked strips over custom backgrounds, e.g. ground charts of the airport.


=== Interface and information display ===
There are two ways to create backgrounds in the program. One working for all purposes is to '''import pictures''' (pixmap files like JPEG or PNG, including transparency); the other works only for radar backgrounds and consists in writing '''drawing specification''' files to paint coloured lines and labelled points. This allows to import anything from the most complex coloured height map to the the most schematic airspace outline. The <code>CONFIG/bg-img/Notice</code> file explains how to import and draw background images.
The '''''Options'' menu''' is divided in two sections. The top section contains unsaved session options, which go back to their default setting on restart. The bottom section are saved settings, which come in two flavours:
* airport-specific (all under a unique submenu): saved and restored when started at the same airport again, e.g. runway ILS capabilities;
* global settings: saved and restored regardless of airports, 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.
For example, you can map out procedures (SID, STAR, IAD...), grouping them by associated runways. Drawings are generally appropriate for that because they allow referring to named points as per the published procedures and avoid manual positioning. But if you want more than schematic line plots, you should create the picture yourself. Using an image processing tool like ''GIMP'', superimpose a transparent layer on top of a real map canvas, or over a screenshot of your ATC-pie radar with pinned navaids as landmarks, and freely decorate your picture.


'''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.
ATC-pie comes with a couple of '''helper tools''' to create or import background images:
# If you have a VATSIM/IVAO sector file for your area (.sct), the "extract drawings from sector file" option will translate the contained diagrams into ATC-pie drawings. While the generated files always require some filtering and post-editing, it is generally the best option for things like SID/STAR diagrams.
# Located in the ''System'' menu, the "image positioning helper" allows to move and resize imported pictures, adjusting the corners visually rather than programmatically if you have no specification for them. All visible pixmap images will be moved simultaneously, so you can work with several at a time if you want to. On dialog box close, a file is generated in the <code>OUTPUT</code> directory for you to copy from.
# An [[OpenStreetMap]] option will take you to the free online map server, centred on your radar centre position. For a quick and dirty start (e.g. for access to coastlines, borders and rivers) you can screenshot the map and use it as a background.


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.
== Communications ==


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 features described in this section do not apply to solo sessions, where text sending is disabled and voice radio interaction is dealt with through speech recognition and synthesis (see the appropriate section above).


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


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


The '''''PTT turns off sounds''''' option is recommended for those of you who do not wear headsets, as it will avoid GUI sound notifications being picked up by your microphone while transmitting on frequencies.
The '''''PTT turns off sounds''''' option is recommended if you not wear a headset. It will avoid picking up GUI sound notifications with your microphone while transmitting.
 
For more efficient text chat, '''text aliases''' are available and allowed in both instant and preset chat messages, e.g. <code>$wind</code>, <code>$qnh</code>... When the containing message is sent, they automatically expand to the current context-dependant value. Custom aliases can be used, whose replacement will be searched for in the general and airport notes (your notepads) and in the selected strip comments. This allows for variable text by controller, by airport and by radar contact. Have a look at the ''Quick reference'' available from the ''Help'' menu, ''Text aliases'' section. Unsuccessful replacements will trigger an edit box so that you can review your message before sending it.
 
Everything up to the first pipe character (<code>|</code>, if any) in a text chat line will be stripped before the message is processed and sent. For quicker access to preset messages if you use them and the keyboard a lot, you can therefore '''prefix your messages''' with a custom shortcut and a pipe, which will enable autocompletion to pull up the desired message line as you start typing the prefix. Here is a preset message example enabling something like a dot-command for sending a bearing to your airport to the currently selected pilot:
: <code>.qdm|Heading to airport $qdm</code>
 
=== Strip and flight plan details ===
Every '''initial contact by a pilot''' should basically make you hit F2 and enter at least the call sign announced. You should then soon figure out if:
* a flight plan is filed, in which case you can save the strip relatively quickly and look for the FPL to link to it (middle click on the FPL entry);
* a flight plan must be filed (e.g. IFR departure not filed by lazy pilot), which only takes a tick in the bottom-line box before saving to open a freshly linked FPL detail sheet to fill;
* he was asked to contact you by a previous ATC, in which case you may have a strip handed over to you already (check the unassigned strip rack);
* etc.


In '''airport input fields''', typing a single dot will instantly fill the box with your ICAO position. Use this as a shortcut from/to your airport when filling details.
=== Radio text chat ===
ATC-pie has a powerful text chat system for those who use the keyboard extensively to interact with pilots in network sessions, although voice communications should be encouraged for realism whenever possible.


Resolving '''strip–FPL conflicts''':
First, '''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 write and save formatted messages instead of repeating chunks of a recurrent format. For instance, anybody will enjoy the comfort of sending "Current weather is $metar" instead of copy-pasting a weather look-up for every such message.
* 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''':
Aliases can be predefined or custom. Predefined aliases take values that are specified by the program, e.g. <code>$metar</code>, and may 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...). They are all listed with their meaning in the "quick reference", ''Text aliases'' section. Make sure to take a look.
* 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).


== FAQ ==
All other aliases will be considered custom, in other words to take values specified by you. You can define text aliases on three different levels:
* world (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.


Questions frequently asked (at least twice) about the program:
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 <code>foo=</code> in the general notes. If one is found, the alias is substituted with what follows the '<code>=</code>' character.
# 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.


'''Q: How do I start anywhere else than bl*ody KSFO?'''
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. 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:
 
: <code>.qdm|Heading to airport $qdm</code>
A: Use a command line argument: <code>./ATC-pie.py ICAO</code>
 
'''Q: Why am I not seeing this aircraft on my radar? I know it is there: the pilot is sending chat messages and/or it is visible on the online live map...'''
 
A: You only see an aircraft on your screen if your radar picks up a transponder signal from it. The two following cases will therefore prevent you from seeing a connected aircraft:
# Its onboard transponder is turned off, i.e. not responding to your radar ping, and you should tell the pilot to switch it on. See the [https://www.youtube.com/watch?v=kpPzRiwzx9Q&list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb&index=1 ATC-pie video tutorial 1]. If the aircraft model does not support the transponder feature, it will be simulated by ATC-pie according to the fallback mode you have selected in the settings dialog; any non-zero mode will do. Another, more radical way is to cheat with menu options "reveal OFF/STBY" or "radar cheat mode" ([https://www.youtube.com/watch?v=lSyH88HR-4w&index=3&list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb tutorial 3]).
# The aircraft is under the radar floor setting. Check in the ''General settings'' dialog; set it to "SFC" to pick up all signals.
 
'''Q: What is the strip exchange server? Which one to use?'''
 
A: The strip exchange feature allows you to hand over strips to ATCs who are connected to the same server and within 180 NM from your position. The public server currently open for general multi-player use is <code>http://h2281805.stratoserver.net/FgFpServer</code>. To hand over a strip, drag it from its rack and drop it on the chosen callsign in the ATC handover list. Publicise your frequency so that ATCs around know what to tell pilots for them to contact you!
 
'''Q: What nickname should I use for the strip exchange server? Where to get my ID?'''
 
A: This feature is not linked to any account or identification process; just choose any name you would like to be recognised by. It will appear in a tooltip over your callsign in the handover list of ATCs who will connect near enough to see you. In a sense, this feature is more social than technical, but makes sense as typical ATC callsigns remain mostly anonymous over MP. Use this field so that other players can identify you.
 
'''Q: Can I draw SID and STAR procedures on the radar?'''
 
A: Yes, and virtually anything else, using background images and hand drawings. To learn how, see the corresponding section above, read the <code>resources/bgdrawings/Notice</code> file and have a look at the packaged example for KSFO.
 
'''Q: How do I assign SIDs and STARs to aircraft?'''


A: This question seems asked quite a lot more than it sounds relevant to a real controller's task. Say you could click around the interface and "assign" a STAR to an inbound aircraft; what would the effect be after that? Should this be important to you, you can always freely comment your strips with the information you want to save. But the realistic wishes in relation to this question are already addressed otherwise:
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.
* Planning routes
*: Published standard departure and arrival procedures (SIDs and STARs) are very often relied on when planning a route for an aircraft, usually prior to departure. Hopefully copied straight from an existing flight plan, the route is written on the flight strip, modified as the flight progresses and passed along with handovers. Like any piece of route specification, you can specify that a SID or STAR is to be followed in the strip route field, e.g. "SID FUBAR en route stuff DUMMY STAR". This will even be recognised by ATC-pie and accounted for in the second line of the radar contact info box when appropriate (see feature note on routing).
* Reference for easy text chat communications
*: When such route is parsed on the selected strip, text aliases <code>$wpsid</code> and <code>$wpstar</code> will respectively be replaced with the first and last en-route waypoints if the "SID"/"STAR" keywords are present and placed correctly. With the example route above, <code>$wpsid</code> will turn into "FUBAR" and <code>$wpstar</code> into "DUMMY". Now if you specifically want to assign a full published procedure name to a contact, e.g. FUBAR4E, and use it in text chat messages without typing it, include a line "sid=FUBAR4E" in your strip comments. It will pop up with the strip mouse-over tooltip, and create a custom <code>$sid</code> alias that will automatically be filled in your sent messages when that strip is selected.


'''Q: FGCom radio is not working. What is going on?'''
=== ATC text chat ===
The ATC text messaging system allows to talk to other ATCs in channels that are separate from the public one read by pilots. It offers '''private channels''' simulating one-to-one landline conversations, and a '''general ATC chat room''' in network sessions, readable by all connected ATCs.


A: There can be a variety of reasons, all of them to rule out before reporting a bug in the program. Start a single ATC-pie instance and try the echo test (''System'' menu). If it works, you may skip directly to item 3 below.
'''Note on interoperability''': While only ATC-pie integrates ATC-side text chat in its interface, other users can join the same channel with an IRC client. 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 best results, they should use their FlightGear network callsign as their IRC nickname.
# Bad FGCom version setting
#: Verify the "FGCom version" set in the ''System'' menu, which should point to the right executable file under <code>resources/fgcom</code> and suit your operating system (see <code>Notice</code> file). Four versions are initially packaged with ATC-pie: Linux64, Linux32, Mac, Win32.
# FGCom server down
#: This can happen, unfortunately even for up to a few days. Check for responses from the server, e.g. with <code>ping fgcom.flightgear.org</code>.
# FGCom subprocess error
#: If the server is up (responding to ping), check for errors in the logged FGCom output files in the <code>output</code> directory.
# Port mess-up on your side
#: If you are running multiple instances of ATC-pie, make sure you have no more than one radio box on every port. In any case, verify you only choose available ports that are not already in use by your operating system for example. Typically, default ports (from 16661 counting up) work fine, but you will have to change them for parallel instances, using the <code>--fgcom-ports</code> command line option (see section: ''starting the program''). To check what port a radio box is using, see its "on/off" button tooltip.


'''Q: Tower view is not starting. The menu option is ticked but nothing happens.'''
== Teacher & student connections (ATC tutoring) ==


A: Ruling out that FlightGear is not installed at all, your system path settings are probably wrong. From a terminal, find the right command to start FlightGear and enter it as ''FlightGear executable'' from the ''System'' menu. Do not add options of any kind; they will be taken care of internally. You may have to enter a ''[[$FG_ROOT|FlightGear root directory]]'' as well, especially if you have the program files installed somewhere unexpected. Your entries will be saved after that.
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.


'''Q: Why is my tower in the middle of the sea, and aircraft water landing/floating?'''
When '''playing teacher''':
* 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 simulate landline conversations with the student (select ATC callsign to interact as), or to speak to the student directly as the teacher.
* 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.


A: You are missing the FlightGear scenery data for your location, or ATC-pie does not know where it is. Check out the ''Tower viewing'' feature note in this article.
[[Category:ATC-pie]]

Revision as of 15:38, 1 September 2020

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.

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 sources to learn the program are:

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

Flight strips

Whether dematerialised or on physical paper, printed out 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, and every strip represents a contact. This helps to ensure that no aircraft is ever forgotten about. Strip positioning and updating then enable to monitor the aircraft's status, sequence number, position, intentions, etc.

Filling details and linking

A click on the "new strip" tool bar button (shortcut F2) or double-click on an empty rack space will open a dialog to fill flight details on a fresh strip, e.g. destination, type of aircraft, 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 and enable joint selection. To link a strip to a radar contact, select one and middle-click on the other. Conflicts between the strip details and the values squawked by the linked transponder contact are reported: the strip displays a "!!XPDR" warning and the strip dialog labels the conflicting details.

A strip can also be linked to a filed flight plan (FPL) to merge the information. The strip dialog also shows the mismatching information between the two, though this is rather common because the strip typically gets updated as the flight progresses.

All together, a selection can involve up to three linked elements: strip, radar contact, flight plan. You can pull details from linked elements to strips (strip panel bottom menu), and push strip details to their linked flight plan if necessary (strip dialog bottom tick box). Unlinking is possible with SHIFT+middle-click. If you use linking carefully, auto-fill options are available from the general settings, to fill blank strip details with newly-linked information.

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

  • a flight plan is already filed: a matching FPL count is displayed near the callsign field as you type, if any (click on the button to view them);
  • a flight plan must be filed (e.g. IFR departure not filed by lazy pilot): select "new FPL" from the bottom line to open a fresh FPL detail sheet to link to the strip;
  • he was asked to contact you by a previous ATC, in which case you may have a strip handed over to you already;
  • etc.

Strip placeholders

ATC-pie provides with various placeholders for flight strips, namely 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 and name them appropriately. Double click on the rack name to 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 any kind of 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-img/Notice to learn how.

Reserved runway marked in yellow

A runway box is a placeholder for a single strip, named after a runway and denoting a clearence to use it (enter, cross, land...). Runway boxes are contained in their own dock, and made visible if a corresponding runway is marked in use. 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:

  • a connected ATC to initiate a handover;
  • a strip shelf (flat button at the bottom of loose and racked strip panels), which clears the strip from your work bench and stores it as shelved.

Airport scene rendering

Tower view window

Tower viewing, following a departing aircraft

This feature allows you to overlook your airport and the connected or simulated traffic, like a controller from a tower viewpoint. It allows to choose from the tower positions specified in the source data if any (X-plane seems only to allow for one, but feel free to declare more for ATC-pie), otherwise defaults to somewhere over the airport to allow towering everywhere. 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 to listen for traffic and accept telnet connections.

Running internally only requires FlightGear installed on your computer. A basic installation is enough, but you will need the scenery for your airport if you want anything exciting to see (and not sea!). Also, aircraft will only be drawn properly if the appropriate models are available. In FlightGear sessions, the models required are those flown by the pilots. For all other session types, models are chosen according to the ICAO type designators of the aircraft and the specifications in icao2fgfs. Read CONFIG/acft/Notice to understand how ATC-pie chooses models and liveries for its viewers. Aircraft and scenery locations can be filled in the System settings dialog if they are not in your FlightGear root directory.

Connecting to an external viewer allows to run FlightGear on a different machine and thereby relieve your session from the CPU load a local instance induces. If you want to do so, get a hint of the required positioning options you should start your viewer with, from the tower view tab in the system settings dialog. Of course, scenery, models and liveries must also be available to the running process.

In either case, once activated from the View menu, the tower view control pane is enabled, from which you can turn to runway points, follow selected aircraft... Direct FlightGear input in the view window is also possible: right click and drag allows to look around, x/X keys change the zoom level, etc.

Additional scene views

You can hook up 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 from the View menu. Additional viewers are registered by their host+port address, from the View menu at run-time or from a custom settings file (see CONFIG/Notice), read at start-up and on explicit reload (System menu).

Every such viewer registered on host XXX and port YYY should be running on XXX and started with options --multiplay=out,TTT,HHH,PPP and --multiplay=in,TTT,,YYY, where:

  • HHH is the host on which ATC-pie is running;
  • PPP is the default 5009, or the chosen port number if ATC-pie was started with --views-send-from;
  • TTT is the network polling frequency (100 is common practice; change as desired if you know what you are doing).

Vectors, routes and separation warnings

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

  • inform strip and radar display;
  • help monitor traffic, checking against vectors;
  • anticipate 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;
  • hold SHIFT, click and drag vertically for altitude/FL vectors;
  • hold SHIFT, click and drag horizontally for speed instructions;
  • hold SHIFT and double-click 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 (world navigation aid, airfield, fix, RNAV point) creates a waypoint on the path to destination, and a route leg from the previous point (a final leg connects the last point to the destination airport);
  • if ambiguous (navpoint names are not all unique around the world), a waypoint is always the nearest homonym to the point beginning the leg;
  • other tokens are kept as route leg specifications to the following waypoint (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 both DEP and ARR airports are not identified, 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

Playing solo

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

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 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. Playing 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 play 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 when playing solo in airport mode, assuming all three available positions
Handovers with virtual ATCs in airport mode
Departure strips Arrival strips
Assuming positions Receive from Hand over to Receive from Hand over to
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;
  • if the aircraft is connected to CPDLC, you can choose to be prompted to send the instruction through the data link (see General settings dialog, CPDLC tab).

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, play for a while and change for opposite runway use;
  • CTR mode with a low ceiling to increase the number of conflicts to resolve;
  • etc.

ATC coordination

"ATC coordination" refers to the following:

  • strip exchange, i.e. sending and receiving strips (handovers);
  • CPDLC transfers between ATCs;
  • ATC text chat, to exchange messages between connected ATCs (see Communications section);
  • who-has requests, to query the system and know who is claiming contact/control of callsigns.

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 connected controllers. Received strips appear on their collecting rack (if defined), with an identification of the sender which disappears as soon as the strip is clicked on. They may link automatically to identified radar contacts, according to the auto-link configuration (general settings). Double-click on the rack name to add an ATC callsign from which to collect strips.

See tutorial video 6 for a presentation of the feature.

FlightGear sessions and compatibility with OpenRadar

On FlightGear session start, there are two "sub-systems" that can be activated for coordination. They differ in terms of supported features and interoperability with other clients:

  • the IRC sub-system enables all coordination features with other ATC-pie clients, but does not currently operate with other software (recommended in all cases);
  • the OpenRadar handover service is OpenRadar's native system, which ATC-pie implements to enable coordination with its users, but some limitations apply (see below).

Both systems can be enabled together.

ATC-pie and OpenRadar's philosophies differ in several ways:

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

For most interactions to work while respecting both approaches as much as possible, the following principles and restrictions apply to strip exchange:

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

Callsign handover policy:

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

Features not supported by OpenRadar:

  • wake turbulance category on strips (but detail preserved for ATC-pie instances later receiving the strip);
  • ATC text messaging;
  • CPDLC.

Note that who-has requests are fully supported.

FSD sessions and compatibility with Euroscope

Euroscope is a popular program to control on VATSIM, a flight simulation network which is historically based on the FSD protocol, although made incompatible with it today. For a long time Euroscope allowed to connect to "plain" FSD servers, until it started being tailored more specifically for VATSIM, and closed the door to outside FSD connections. Older versions of Euroscope are still around, which ATC-pie is able to interact with, but only to a limited extent:

  • sending a strip to Euroscope will result in a loss of all strip details but the callsign (which must be connected), the only information left to the recipient being the FPL details for that callsign if any (strip changes made after FPL data retrieval are therefore lost);
  • receiving a strip from Euroscope is supported, but the sender will see the hondover pending (never "assumed");
  • who-has requests will remain unanswered by Euroscope.

ATC-pie clients interact normally between each other, but note that CPDLC is not supported by the FSD protocol.

Background images

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

Background images allow to decorate:

  • radar scopes, with all sorts of maps and useful information about the airspace, terrain or procedures;
  • loose strip bays, to move unracked strips over custom backgrounds, e.g. ground charts of the airport.

There are two ways to create backgrounds in the program. One working for all purposes is to import pictures (pixmap files like JPEG or PNG, including transparency); the other works only for radar backgrounds and consists in writing drawing specification files to paint coloured lines and labelled points. This allows to import anything from the most complex coloured height map to the the most schematic airspace outline. The CONFIG/bg-img/Notice file explains how to import and draw background images.

For example, you can map out procedures (SID, STAR, IAD...), grouping them by associated runways. Drawings are generally appropriate for that because they allow referring to named points as per the published procedures and avoid manual positioning. But if you want more than schematic line plots, you should create the picture yourself. Using an image processing tool like GIMP, superimpose a transparent layer on top of a real map canvas, or over a screenshot of your ATC-pie radar with pinned navaids as landmarks, and freely decorate your picture.

ATC-pie comes with a couple of helper tools to create or import background images:

  1. If you have a VATSIM/IVAO sector file for your area (.sct), the "extract drawings from sector file" option will translate the contained diagrams into ATC-pie drawings. While the generated files always require some filtering and post-editing, it is generally the best option for things like SID/STAR diagrams.
  2. Located in the System menu, the "image positioning helper" allows to move and resize imported pictures, adjusting the corners visually rather than programmatically if you have no specification for them. All visible pixmap images will be moved simultaneously, so you can work with several at a time if you want to. On dialog box close, a file is generated in the OUTPUT directory for you to copy from.
  3. An OpenStreetMap option will take you to the free online map server, centred on your radar centre position. For a quick and dirty start (e.g. for access to coastlines, borders and rivers) you can screenshot the map and use it as a background.

Communications

The features described in this section do not apply to solo sessions, where text sending is disabled and voice radio interaction is dealt with through speech recognition and synthesis (see the appropriate section above).

FGCom radio

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

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

The PTT turns off sounds option is recommended if you not wear a headset. It will avoid picking up GUI sound notifications with your microphone while transmitting.

Radio text chat

ATC-pie has a powerful text chat system for those who use the keyboard extensively to interact with pilots in network sessions, although voice communications should be encouraged for realism whenever possible.

First, 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 write and save formatted messages instead of repeating chunks of a recurrent format. For instance, anybody will enjoy the comfort of sending "Current weather is $metar" instead of copy-pasting a weather look-up for every such message.

Aliases can be predefined or custom. Predefined aliases take values that are specified by the program, e.g. $metar, and may 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...). They are all listed with their meaning in the "quick reference", Text aliases section. Make sure to take a look.

All other aliases will be considered custom, in other words to take values specified by you. You can define text aliases on three different levels:

  • world (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 on chat message send:

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

Moreover, ATC-pie strips everything up to the first pipe character (|), if any, before a message is processed and sent. You may check this with test line "stripped part|sent part" and observe that only the "sent part" makes it to the message contents. 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 text chat

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

Note on interoperability: While only ATC-pie integrates ATC-side text chat in its interface, other users can join the same channel with an IRC client. 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 best results, they should use their FlightGear network callsign as their IRC nickname.

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.

When playing teacher:

  • 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 simulate landline conversations with the student (select ATC callsign to interact as), or to speak to the student directly as the teacher.
  • 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.