ATC-pie at the KSFO mess
|Developed by||Michael Filhol|
|Initial release||Febuary 1, 2015|
|Latest release||Febuary 1, 2015|
|License||GNU GPL v3|
ATC-pie is a radar air traffic control simulation program for the FlightGear multi-player network, initially released Febuary 2015. It is comparable to OpenRadar, but essentially designed for realism.
It is programmed in Python3 for Qt5, hence system-independant, only both must be installed as well as the python3-qt5 bindings. That done, it is meant to work straight away, with no other resource to install or make/compile command to run. No need to install or update FlightGear, download scenery or fetch any external resource before it can run.
- 1 Features
- 2 Working principles
- 3 User guide
Features listed below are already implemented and supposedly stable. Tested on Linux and Windows; still waiting for Mac users to report.
- Floatable/dockable GUI panes: strips, radios, text chat, etc.
- Real METAR updates with selectable weather station
- Real declination lookup and true/magnetic distinction
- Data retrieved from the latest X-Plane file set
- In-app announcement of ATC session on Lenny64's popular ATC event page
- General and airport-specific settings saved on close and restored on restart
- Notification system combining sounds and a time-tagged list
- Network text chat system
- Manage ignored contacts
- Personal notepads (general and airport-specific) saved across sessions
- Realistic mode-dependant behaviour (modes 0, A, C, S)
- Choice for default mode for the many FlightGear aircraft models still not equipped
- Individual and general cheat modes to "see all" (override XPDR settings)
- Radar identification assistant (unique squawk link between radar pick-up and strip assignment detection)
- Variety of show/hide options: navigation points and fixes, aircraft info boxes, vectoring assignments...
- Directly assign headings, altitudes/FLs and speeds by click&drag on radar contacts
- All-in-one display of aircraft course, vector assignments and conflict warning
- Measuring tool for quick point-to-point heading & distance checks
- In-game custom text labels to annotate radar background (saved across sessions)
- FGCom 3 integration
- ATIS recording with information letter and pre-filled preparation notepad
- Multiple radio management enabling simultaneous transmission on different frequencies
- Frequency-specific sound level selection enabling efficient monitoring
- Mouse and keyboard PTT
- Integrated echo test
- Use of separate (externally running) FGCom possible
- User-defined strip racks
- Strip drag&drop along and across racks
- Link strips to flight plans and radar contacts to merge editable details and inform radar display
- FPL, transponder and vectoring assignment conflicts reported
- Interface with Lenny64's flight plan data base including in-game FPL retrieval, filing and editing
- Work with local FPL copies and manage sync with online publication
You are the air traffic controller, and players will connect to the network with different types of aircraft and transponder equipment. As in real-life, the radar is SSR, hence will show you only (unless you cheat) what you pick up from on-board transponders in your range. That means:
- If a transponder is off or on standby, you will not see the aircraft on your radar screen.
- If a transponder is on, you will at least be able to see its position and read the transponder code, possibly its altitude and even its type and callsign, depending on the mode set by the pilot.
Your basic traffic flow and sequence working unit is the strip, each representing a controlled (or soon expected) aircraft. Strips are created, filled with details and moved along and across racks until handed over to a different controller or discarded. Details written on strips include:
- most importantly, the aircraft's callsign, to be used on the radio;
- details like aircraft type, airspeed, route... that can be specified by the pilots themselves when filing flight plans; and
- transponder code and flight parameter assignments (or vectors: heading, altitude/FL, speed).
Double-clicking on a strip will open a strip detail sheet where those details can be manually edited, but each strip can also be linked to a flight plan and/or a visible radar contact on the scope screen—a strip can only be linked to one flight plan and to one radar contact. Linking to a strip will automatically:
- make the strip display the missing elements made available by the linked aircraft transponder or flight plan;
- label the radar contact dot with the more informed linked details (e.g. assigned altitude).
Any detail mismatch between a strip and its linked flight plan or radar contact will be reported for you to resolve.
To identify an aircraft and link the right radar contact to a strip, an ATC can rely on different things. He can read an aircraft's callsign straight away if it is visible (or cheated), tell from reported positions and altitudes, or use a transponder code. For instance, say a VFR traffic makes an initial radio contact giving his callsign and approximate position. ATC will typically pull out a new blank strip and give the pilot a unique transponder code to squawk, writing it on the strip alongside the announced callsign, then wait for it to appear on the radar. This allows for what ATC-pie calls soft links, in essence radar identification of an aircraft–strip pair such that:
- the strip is assigned a transponder code;
- no other strip is assigned the same code;
- the aircraft is the only one squawking that code in radar range.
Soft links are reported to you so you can properly link the two and consider the aircraft identified, before getting back to the pilot with subsequent instructions.
This section is pretty much the only documentation there is for now. A better one might come one day, but there should be enough here to get anyone started.
Getting it 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 (e.g. Qt5), listed in the
Downloading the tarball requires nothing but the standard tar+gzip combo:
- go to  and click on the download button to collect the compressed archive;
- extract the files in the directory of your choice.
To clone the repository, from the directory of your choice:
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 to start the program is to run a Python3 interpreter on the
ATC-pie.py file in the top-level directory. To start at a chosen airport location, say with code ICAO, use a system command-line argument, which may look as simple as:
After a few seconds, you should see the main window appear with a radar scope and a depiction of your airport in the centre.
Here are a few unsorted tips to help you navigate the program...
- Callsigns typically start with the ICAO code of a controlled airport, and end with a hint on the provided service: twr, gnd... With no callsign given, you will appear as "ICAOobs" on network connect. Note that FGMS restricts callsigns lengths to 7 characters. :-(
- For more efficient text chat, a growing list of text aliases exist (
$icao...), which you can use in instant and preset chat messages. They expand to the current value on message send.
- To discard all local modifications of an online FPL (decorated red), simply remove the FPL from the list and check for new flight plans again. The deleted entry should be retrieved with online state.
- Heading displays are mostly magnetic so they can be read out to pilots. The only exception perhaps are the navigator tooltips, for easier identification on the scope.
- The transition level is by definition the lowest flight level that is still above the transition altitude. This does not mean the lowest assignable FL, which may take more vertical separation.
- The grouped tick marks along the localiser line (when shown) indicate best altitudes AMSL for final approach along the defined slope rate. Every mark in a group is 1,000 ft.
- The FGCom version setting is the name of a subdirectory in
- "OK" near the "route" field on the strip detail sheet means that the route could be parsed correctly; otherwise "!!" is displayed. This does not matter, only the info boxes will be showing destination (or nothing if unknown) instead of next waypoint.
Resolving strip–FPL conflicts:
- to confirm all strip details: open the strip detail sheet, tick the "push details to FPL" box and save to propagate the strip details;
- to confirm all FPL details: pull down the "FPL" menu under the strip rack and click "retrieve all (overwrite)";
- to confirm some details of each source:
- open the strip detail sheet;
- get rid of the bad strip details and save;
- retrieve missing strip details from the "FPL" pull-down menu;
- finally push the strip details to the flight plan.
Say you are TWR coordinating with GND at an airport and you want to monitor both frequencies while you are only in charge of one. You can set this up by starting your own radio box on TWR frequency, and turn on a second one to monitor GND, setting the volume to "soft" on the latter so that you can always tell if a message is for you to answer or not.
Display conventions and colour codes
- square: aircraft is properly equipped with a transponder (properties are found in FGMS packets received)
- circle: no transponder on board (no point instructing to squawk)---warning: if reported, alt./FL value in this case is a geometric distance, not a pressure-altitude, hence approximate when comparing to other aircrafts' values
- solid shape: contact is linked to a strip (you control it)
- outlined only: unlinked contact (somebody else might be)
- "X": ignored contact
- "?": contact has timed out (gone or having network problems)
Info box (radar tags):
- First line: callsign or "?" if unknown; aircraft type/model if known
- Second line:
- if contact is linked to a strip: next known waypoint on route or destination
- otherwise: transponder code (empty if not equipped or off and cheating)
- Third line: reported altitude or "alt?" if none; vario char ('^' climbing, 'v' descending, '=' neither, '-' N/A); assigned alt. if any; assigned or current ground speed
Courses and assignments:
- course line: solid if heading assigned, dotted otherwise; red if flying off assigned course, grey otherwise
- altitude arc (drawn if alt./FL too different from assigned): solid arc shows point at which assignment will be reached assuming vertical speed of 500 ft/min, dotted if reach point is beyond arc
- speed marks: each mark shows distance flown in 1 minute at assigned speed, current speed or TAS (first available); grey if correct speed or none assigned, red otherwise (marks then point to either accelerate or decelerate to reach assignment)
- black: unlinked strip
- blue: soft link detected, matching aircraft marked as well
- green: linked strip with no conflicts
- red: linked strip with unfollowed vector assignments ("!!vect", see courses and assignments above) or transponder conflicts to resolve ("!!XPDR", open detail sheet for more info)
- "!!FPL": conflicts with flight plan
- black: local (not published) flight plan
- green: FPL is online, and in sync unless modified by somebody else online
- red: FPL exists online, but local modifications have been made
GUI gestures and key strokes
- CTRL: PTT all radios whose "kbd PTT" boxes are ticked (works within major dialogs too)
- F2: create new blank strip
- SHIFT+F2: create new strip linked to selection
- entry in navigator pane: show a tool tip with true heading and distance from radar
- unpinned navpoint on radar scope: show short name, and frequency/channel if navaid
Left mouse button alone:
- click on aircraft body, info box, strip or FPL: select
- click on navpoint: set filter in navigator
- click on radar background: deselect
- click on text chat message: recall dest./message in entry line
- own message: recalls both
- other: fill dest. and focus message field
- click&drag info box: move box
- click&drag aircraft body if a strip is linked: assign heading to aircraft
- double-click on aircraft body or info box: edit linked strip if any
- double-click on navpoint: pin/unpin label
- double-click on notification: notification-dependant
Left mouse button with modifier key:
- SHIFT+click strip with linked radar contact: indicate aircraft location
- SHIFT+click&drag aircraft body if a strip is linked: assign alt/FL or speed to aircraft
- SHIFT+double-click on aircraft body: remove hdg/alt./FL/speed assignments
- SHIFT+double-click on info box: reset box position
- SHIFT+double-click on radar background: add custom text label
- SHIFT+double-click on custom text label: remove label
Middle mouse button:
- click on aircraft body, info box, strip or FPL: link to current selection if any and if possible
- SHIFT+click on aircraft body, info box or FPL (if selected and linked): unlink from strip
Right mouse button:
- click&drag anywhere on radar scope: pan view
- SHIFT+click&drag anywhere on radar scope: heading and distance measuring tool