ATC-pie user guide
| The FlightGear forum has a
subforum related to: ATC-Pie support & development
This article is a guide to help one download and run ATC-pie. It describes some of its major features and lists a few tips. Other sources to learn the program are:
- the online video tutorial;
- the in-app quick reference available from the Help menu (summary of mouse/keyboard gestures, display conventions...);
- to play solo!
Anyone motivated to write a full user guide is obviously welcome to contact the developer, or improve this article. For support and troubleshooting, the ATC-pie FAQ might get you an answer first. Otherwise kindly ask on the FlightGear forum, where we have a dedicated sub-forum, so the discussion is public and its contents shared.
- 1 Getting ATC-pie to run
- 2 Feature notes
- 3 Tips
Getting ATC-pie to run
There are essentially two ways of downloading ATC-pie: one is to download a tarball to extract locally; the other is to clone the Git repository. The latter requires Git, but will keep you in sync with updates more easily. Your choice. In either case, you will have no compiling to do (make, etc.), but do make sure you have the few dependencies installed, listed in the
README file (Python3 + bindings to Qt5).
Downloading the tarball:
- get the latest stable version from the project page;
- extract the files to the directory of your choice.
To clone the Git repository:
git clone git://git.code.sf.net/p/atc-pie/code ATC-pie
If you choose cloning with Git, you can update your software when a new release is announced with a single command from the downloaded directory:
Starting the program
Depending on your system and preference, you might be double-clicking, typing stuff or pulling your hair out. In any case what you need is to run a Python3 interpreter on the
ATC-pie.py file in the top-level directory. A welcome launcher window should open, from which you may start a session in either airport (AD) or centre (CTR) mode, i.e. respectively with or without a base airfield.
The airport mode is for ATC positions like approach or tower control. In this mode, ATC-pie places the radar at the chosen base airfield, depicts its tarmac and runways, and enables features like tower viewing and runway selection.
The centre mode is designed for en-route control centre simulation. It disables all airport-specific features, and allows to place the radar anywhere on Earth. When selecting this mode:
- The location code is a designator of your choice (excluding airport codes), under which to save your location-specific settings. A good idea is to use ICAO airspace designations, e.g.
SBBSfor the Brasilia FIR in central Brazil or
LFFFfor the Paris region in France.
- The radar position field specifies the point on which to centre the radar. For example,
LFPO>090,15will centre the radar on a point 15 NM to the East of Orly airport. See down
resources/bg-img/Noticefor a full description of the syntax for point specification.
You may also bypass the launcher and start directly at a given location with the following command, using an ICAO code for an airport, or a previously defined CTR position:
Besides the location code, the following command line options are available:
|Option||Effect and argument specification||Default|
|--map-range=range||Define the distance in NM from the radar centre up to which the map will be drawn and navpoints listed in the navigator (accepted values are 20..500). This option can only be used with a location argument.||100 in AD mode; 300 in CTR mode|
|--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|
Running for the first time
A few things you will want to do when running ATC-pie for the first time:
- If you intend to use the radio like you should in FlightGear multi-player games, check the FGCom version setting in the System menu, and try an echo test. Read the
resources/fgcom/Noticefile if you have problems hearing yourself, and search for "FGCom" in the ATC-pie FAQ.
- In the same menu, if you want to use the tower viewing system and not bother making it external (see feature note below), make sure you have the right paths set for your FlightGear installation.
- Set up the important location-specific settings like airport runway parameters, especially ILS capability if you will be playing solo often at the same location.
NB: callsigns for ATCs in FlightGear are expected to start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service (twr, gnd, ctr...). Before choosing your callsign on MP connect, make sure it is not already in use, and note that FGMS restricts callsign length to 7 characters. :-(
This section describes a few major features. A more exhaustive list can be found in the main article.
Strips and placeholders
Whether dematerialised or on physical paper, printed out or filled by hand, the flight 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 no aircraft is ever forgotten about. Strip positioning and updating then enable to monitor every aircraft's status, sequence number, position, intentions, etc.
ATC-pie provides with various placeholders for flight strips, namely racks, loose strip bays and runway boxes. Depending on your ATC position and local facilities, you should choose and arrange your placeholders for optimal control. Strips can then be moved between all of them using mouse drag and drop.
A strip rack is the preferred way of keeping track of a sequence, e.g. a departure queue at a runway threshold. You can create as many racks as you wish and name them appropriately. Racks can be viewed in the main window and in their own docked or floating panel. The column view shows all racked strips at once; the tabbed view avoids spreading the window horizontally. Received and recovered strips will automatically fall in the permanent "default" rack.
In the same panel, above the racks or in their own tab (resp. column or tabbed view), you can opt to show the runway boxes. A runway box is a placeholder for a single strip, named after a runway in use and denoting a clearence to use it (enter, cross, land...). Thorough use of runways boxes will help you never clear an aircraft to land over lined up traffic for example. When freed, runway boxes display a timer since last use together with the wake turbulance category of the last contained strip, to help with separation. What is more, if you use radar, a filled runway box marks the runway as reserved on the scope, and if you have runway occupation monitoring enabled, allows for one traffic before the runway incursion warning turns on.
The third placeholder type available is the loose strip bay, allowing free-hand positioning of strips in a dedicated window. Such bays can be 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
resources/bg-img/Notice to learn how.
Besides, there are two other places a strip can be dropped on, usually when releasing a contact:
- a connected ATC (if accepting strip exchange), to initiate a handover;
- the strip shelf (visible under every rack or loose strip panel), which removes the strip from your work bench and stores it as shelved.
Routes and conflict warnings
ATC-pie analyses routes and assigned vectors to assist traffic management and anticipate path conflicts between controlled aircraft. This feature is essential in centre mode.
A route is parsed for every strip with recognised departure and destination airports (entry fields both turned green), as follows:
- route tokens are whitespace-separated;
- each recognised navpoint token (world navigation aid, airfield, fix, RNAV point) creates a waypoint on the path to destination, and a route leg from the previous point (a final leg connects the last point to the destination airport);
- if ambiguous (navpoint names are not all unique around the world), a waypoint is always the nearest homonym to the point beginning the leg;
- other tokens are kept as route leg specifications to the following waypoint (allows for airway or procedure names for example).
Parsed routes on flight plans and strips are viewable in a route dialog, showing leg details and the geodesic paths on a world map. Also, when a route is parsed and linked to a radar contact, ATC-pie works out its current leg based on distance to destination, and:
- the route to go is drawn as a dotted line on the radar scope (according to scope "show" options);
- details of the current leg are displayed in the selection info pane, and the route dialog enabled for full route viewing;
- the strip shows only the remainder of the route for this contact;
- the info box contains the next waypoint and the heading leading the aircraft to it on a great circle, unless:
- the current route leg is the first, and the keyword "SID" appears in its specification: "SID wp" is displayed, where wp is the first waypoint on the route;
- the current route leg is the last, and the keyword "STAR" appears in its specification: "STAR wp" is displayed, where wp is the last en-route waypoint.
See tutorial video 7 for a demonstration of routes.
NB: 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.
ATC-pie also features a conflict prediction system, which can be activated or turned off from the Options menu. It uses route and vector assignments to anticipate and alert you of path conflicts so you can take action and prevent separation losses.
When looking for conflicts, a horizontal (ground projection) path is considered for every aircraft with a linked strip and a parsed route or an assigned heading vector. An aircraft is assumed to follow its route, unless a heading vector is given in which case it is assumed to be flying the assigned straight course. Path conflicts occur when horizontal paths intersect and the intervals between respective current and assigned altitudes overlap. When no altitude is assigned, the interval is one around the current altitude. When an aircraft's altitude is unknown, any assigned altitude will be considered instead.
Another possible alarm is the separation incident, a serious ATC mistake which calls for immediate action. The table below summarises the different levels of conflicts, ranked in decreasing order of emergency.
|Alarm||Shown on scope (default colours)||Meaning|
|Separation incident||Bright red intersecting circles||Separation loss between aircraft|
|Path conflict||Red circles and paths||Anticipated paths and altitudes are intersecting|
|Possible path conflict||Yellow circles, red paths||Ground projection of paths are conflicting but not all altitudes are known|
In solo games, you control virtual IFR planes, receiving and handing over strips to virtual ATCs depending on your position and the aircraft's intentions. ATC-pie allows to train in different situations:
- as an en-route controller (CTR) if started in centre mode;
- or in airport mode, where four combinable positions are available:
- ground (GND), to taxi aircraft between gates 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.
When playing CTR, your task is to transit the aircraft across your airspace, always ensuring separation, and to hand each of them over to the most appropriate neighbouring centre North, South, East or West of your sector. You can specify local navpoints in the location settings so that the system includes them as turning points in the randomised aircraft's routes.
In airport mode, traffic is either inbound or outbound. Assuming APP, inbound aircraft must be sequenced and vectored into tower range for handover, unless you are in the TWR position as well. Each inbound aircraft either requests ILS 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 its route. Entry and exit points are configurable in the location settings.
|Departure strips||Arrival strips|
|Assuming positions||Receive from||Hand over to||Receive from||Hand over to|
Instructions are given through different means:
- vectors are issued by way of the vectoring assignment tool: click&drag out of a radar contact for heading, hold SHIFT and drag for altitude/FL vertically and speed horizontally (see video 5 of the tutorial);
- taxi instructions are also sent by dragging out of radar contacts, when they are picked up on the ground (stopped and low enough);
- all other instructions (line up and wait, clear to land...) must be sent from the dockable instruction panel.
NB: Instructions 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.
Things you can train for:
- approach in dense traffic: select APP position only and increase traffic density;
- towering a single runway, optimising its use: select TWR position and an equal balance of departures and arrivals;
- change of runways (e.g. irl after wind direction change): start with APP+TWR and select a runway for arrivals at least, play for a while and go back to the dialog to change for the opposite runway;
- CTR mode with a low ceiling to increase the number of conflicts to resolve;
Teacher & student connections (ATC tutoring)
This connection type is made to bring an ATC student and a teacher together for tutorial or training sessions. The teacher creates and manipulates traffic for the student to work with, controls the weather and decides on the ATC neighbours.
To set up a session, the student must connect to the teacher, so make sure the teacher's session is running first. Only one student can connect to a teacher at a time. To communicate via voice during the session, the two parties may use nearby FGCom frequencies, but a private channel on Mumble is also an option to avoid interfering with multi-player users sharing the same server. The best choice is probably to tune into unused (guard or secondary) FGCom frequencies for in-simulation transmissions, and to open a separate channel for teacher–student conversations.
When playing teacher:
- The teaching console dock is enabled, which you should keep visible for efficient control of the student's environment.
- New traffic can be created at any time with a simple SHIFT+click&drag on the radar, specifying the place and face heading of the wanted traffic. A dialog pops up and allows you to choose a callsign (one is initially generated), altitude and other details. If near a parking position or runway threshold, you can place it on the ground instead, ready to taxi or for departure.
- Traffic is initially created in an "unspawned" state, in other words visible to you (marked "?") but not to the student. This allows you to change his transponder settings or get it into a certain state or place before spawning it into the student's world.
- Controlling the traffic is done in the same way as in solo sessions, i.e. with the click&drag vector and taxi tools and through 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 linked if you want your vectors to be 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. NB: frozen aircraft result in stationary flights on radars.
Strip exchange is possible, either between both parties ("offline" exchanges) or between the student and the virtual ATCs (in-sim handovers). As the teacher, you must drop every strip on "Student" and select as prompted whom the strip should appear from on the student's side. As the student, drop your strip on any of the ATCs in the neighbours list to simulate a handover, or on "Teacher" if only showing it to your mentor. All student handovers are made visible to the teacher for supervision. Interestingly, for his convenience in further control of the traffic, the teacher's strips do not disappear on handovers.
NB: Unlike in FlightGear games where limitations apply (see section further down), all strips are exchangeable in tutorial sessions.
This feature allows you to overlook your airport and the connected (multi-player games) or simulated (solo and teaching sessions) traffic, like a controller from a tower viewpoint. It uses the tower position specified in the source data if any, otherwise defaults to somewhere over the airport to allow towering all available airports. It is disabled in CTR mode.
There are two ways of activating a tower view. You may let ATC-pie start its own suitably configured FlightGear process, or have it connect to an external viewer, manually set up and accepting connections.
Running internally only requires FlightGear installed on your computer. A basic installation is enough, but:
- aircraft will only be drawn properly if you have the corresponding models installed—read the notice in
resources/acftand check out the
icao2fgfsfile to understand how ATC-pie chooses models for FlightGear (initially included are a few ugly substitutions like B772 for A320 to avoid the lighter installations to miss out on planes, but you can edit the file and use your own models);
- more importantly, you will need the scenery for your airport if you want anything exciting to see (and not sea!)—add it to your FlightGear root directory or enter the directory in the System settings dialog (ATC-pie will pass it on to FlightGear).
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. More options should also be considered, e.g.
--fdm=null. 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 controller 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 keys change the zoom level, etc.
You can 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. Additional viewers are registered by their host+port address, from the View menu at run-time or from a custom settings file (see
settings/Notice), read at start-up and on explicit reload (System menu).
Every additional viewer registered on host XXX and port YYY should be running on XXX and started with options
- 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
- TTT is the network polling frequency (100 is common practice; change as desired if you know what you are doing).
Handovers in FlightGear and OpenRadar interoperability
Strips can be handed over by dropping them on recipients in the list of connected controllers. Received strips appear unlinked on the default rack, with an identification of the sender which disappears as soon as the strip is clicked on. For a full presentation about the feature, check tutorial video 6.
The handover feature in FlightGear multi-player games is based on OpenRadar's exchange server to enable ATC coordination between users of both software programs. However, it is to note that their philosophies differ in several ways:
- OpenRadar's basic processing unit is the FGMS callsign, whereas ATC-pie's is the strip;
- OpenRadar's concept of handover is based on a shared notion of aircraft ownership, whereas ATC-pie allows any controller to pull out a strip, write any callsign and link it to a radar contact;
- in OpenRadar, a handover must be acknowledged by the receiver for the sender to lose ownership and for all neighbouring OpenRadar users to see the handover complete, whereas ATC-pie considers that a strip sent through the hand-over pipe is gone and should land directly on a receiver's rack at the other end, without anybody else necessarily to know.
For most interactions to work while still respecting both philosophies as much as possible, the following principles and restrictions were chosen:
- ATC-pie users can only hand over strips that are linked to a radar contact (no lone strip can be sent);
- aircraft under ATC-pie control are not shown as "owned" to OpenRadar users;
- handovers from ATC-pie are restricted to a 180 NM range, and will fail if an OpenRadar user in range is claiming ownership;
- when sending to ATC-pie controllers, OpenRadar users will see their transfers acknowledged straight away, unconditionally.
Callsign 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.
Detail note: wake turbulance category does not show in OpenRadar, but is preserved and visible to ATC-pie instances later receiving the strip.
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
resources/bg-img/Notice file explains how to import and draw background images. All pictures and drawing points are positioned using lat/lon coordinates, navpoints in map range and radial/distance expressions as per the "point specification" syntax explained in the notice.
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 handful of helper tools to create or import background images:
- 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
outputdirectory for you to copy from.
- The "download OSM background" option facilitates map retrieval from the OpenStreetMap still image server. After specifying corners and a scale, a PNG map will be generated in the
outputdirectory for you to import. Caution: downloads can fail for large images; try reducing the requested size or resolution in such case. Also, the server is rather limited so make parsimonious use of it.
- If you have a sector file for your area (.sct), the
sectorExtract.pyscript will translate the contained diagrams into ATC-pie drawings. While the generated files always require some post-editing, it is generally the best option for things like SID/STAR diagrams. See the
READMEfile for a description.
ATC-pie has a powerful text chat system for those who use the keyboard extensively, though of course voice radio communications should be encouraged for realism, whenever possible.
First, text aliases are dollar-prefixed words (like
$foo) that ATC-pie will try to replace with context-dependant values on message send. This allows to write and save formatted messages and avoid typing verbatim for every message of a recurrent format. For instance, anybody will enjoy the comfort of sending
Current weather is $metar, whose alias will expand to the current primary station weather, instead of typing or copy-pasting a weather look-up for every such message.
Aliases can be predefined or custom. Predefined aliases take values that are specified by the program, e.g.
$metar standing for the current weather, and 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 and replacements on three different levels:
- world (program user), in the general notes;
- location (airport/centre), in the local notes;
- individual (selected strip), in your strip comments.
Here is how ATC-pie decides what to do with a text alias of the form
$foo on chat message send:
- If it is one of the predefined list, the substitution is the one described. If not, it is a custom alias and we carry on to the next step.
- Look for a line beginning with "foo=" in the general notes (notepad dock). If one is found, the alias is substituted with what follows the '='.
- Perform the same search through the local notes. If nothing is found, consider the current selection.
- If a strip is part of the current selection, look inside the comment field and search likewise.
- Substitution is unsuccessful. ATC-pie will open an edit box so that you can review your message before sending it.
NB: You can test all this without polluting any game channel by holding the mouse down on the "Msg" button and selecting "check message". This will allow you to view what replacements would take place.
Moreover, ATC-pie strips everything up to the first pipe character (
|), 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, click and hold the Dest. tool button in the text chat dock to add their callsign to the senders blacklist. All messages from the user will then be filtered out from the message pane. You can view and clear this list at any time during the game.
Here are a few tips to help you navigate and use the program.
Interface and information display
You can customise the radar & strip colours by editing the colour codes in the
settings/colours.ini file generated on first run.
Heading displays are mostly magnetic so they can be read out to pilots. The only exceptions are the navigator and handover list tooltips, for easier human identification on the scope. All directions are geodesic.
The grouped diamond and tick marks along the landing helper lines indicate best altitudes AMSL for final approach along the configured flight path angle: diamond marks read 5,000 ft each; every other tick mark is 1,000 ft.
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.
Multiple radios can be opened and tuned in at once, and you can talk on either one by holding the PTT mouse button down for the chosen radio box. The
left-Ctrl keyboard key will also let you PTT on selected frequencies. You can transmit on several at once, for example to service GND+TWR frequencies in view of splitting them seemlessly again if a controller is expected soon to fill one of the two positions. Tick the Kbd PTT option in the radio boxes of the frequencies to merge. Your keyboard PTT key will then transmit on them all simultaneously. Note that while you will be broadcasting on, and hearing incoming transmissions from, all frequencies, pilots will not be hearing each other across frequencies.
Say you are TWR coordinating with GND at your airport, and you want to monitor both radio frequencies while you are only in charge of TWR. To set this up, start your radio box on TWR frequency and turn on a second one to monitor GND. Tick "Kbd PTT" only for TWR so that you only transmit to your frequency and don't interfere with the other, and set the volume to "soft" on the latter so that you can tell the radio you are hearing the messages from, and know if it is for you to answer.
The PTT turns off sounds option is recommended for those of you who do not wear headsets, as it will avoid GUI sound notifications being picked up by your microphone while transmitting on frequencies.
Strip and flight plan details
Every initial contact by a pilot should basically make you hit F2 and enter at least the call sign announced. You should then soon figure out if:
- a flight plan is filed, in which case you can save the strip relatively quickly and look for the FPL to link to it (middle click on the FPL entry);
- a flight plan must be filed (e.g. IFR departure not filed by lazy pilot), which only takes a tick in the bottom-line box before saving to open a freshly linked FPL detail sheet to fill;
- he was asked to contact you by a previous ATC, in which case you may have a strip handed over to you already (check the default strip rack);
In airport mode, typing a single dot character
. in an airport input field will instantly fill the box with your ICAO position. Use this as a shortcut from/to your airport when filling details.
* symbol in front of a strip callsign means that a strip comment is present (filled in the details). Open the detail sheet to view, or hover the strip with the mouse to show it as a tool tip.